Nếu có các ứng dụng hiện tại dựa trên Google Sheets API phiên bản 3, bạn có thể di chuyển sang Google Sheets API phiên bản 4. Phiên bản 4 dựa trên JSON, có giao diện dễ sử dụng hơn và bổ sung một lượng lớn chức năng không có trong phiên bản 3.
Trang này cung cấp thông tin đối chiếu giữa các lệnh cũ của Sheets API phiên bản 3 và các thao tác tương đương trong Sheets API phiên bản 4. Hoạt động ánh xạ chủ yếu tập trung vào tập hợp spreadsheets.values, cung cấp chức năng đọc và ghi trực tiếp vào ô. Các khía cạnh khác, chẳng hạn như thêm trang tính hoặc cập nhật thuộc tính trang tính, sẽ do tập hợp bảng tính xử lý. Xin lưu ý rằng cấu trúc JSON của API phiên bản 4 không tương thích ngược với cấu trúc XML được dùng trong phiên bản 3.
Để biết thêm thông tin về các tài nguyên có trong API Trang tính phiên bản 4, hãy xem Tài liệu tham khảo về API.
Ký hiệu và thuật ngữ
API phiên bản 3 gọi các trang trong một bảng tính cụ thể là "trang tính". Đây là từ đồng nghĩa với thuật ngữ "trang tính" mà API phiên bản 4 sử dụng.
Các API này thường yêu cầu bạn chỉ định một mã nhận dạng bảng tính của bảng tính mà bạn đang làm việc. Các hàm này cũng thường yêu cầu mã nhận dạng của trang tính đang được thao tác. Các giá trị này xuất hiện dưới dạng một phần của URL điểm cuối API, dưới dạng tham số truy vấn hoặc dưới dạng một phần của nội dung yêu cầu. Trong trang này, các phần giữ chỗ spreadsheetId và sheetId lần lượt đề cập đến mã nhận dạng của bảng tính và trang tính. Khi sử dụng các phương thức được mô tả trên trang này, hãy thay thế bằng mã nhận dạng thực tế ở những vị trí này.
API phiên bản 3 cũng chỉ định một mã nhận dạng cho các hàng được truy xuất bằng nguồn cấp dữ liệu danh sách; mã này được biểu thị trong trang này bằng phần giữ chỗ rowId.
Cấp phép cho yêu cầu
Khi chạy, ứng dụng của bạn sẽ yêu cầu người dùng cấp một số quyền nhất định; các phạm vi mà bạn chỉ định trong ứng dụng sẽ xác định những quyền mà ứng dụng yêu cầu.
API phiên bản 3
Sheets API phiên bản 3 hoạt động với một phạm vi uỷ quyền duy nhất:
https://spreadsheets.google.com/feeds
là tên thay thế cho
https://www.googleapis.com/auth/spreadsheets
Bạn có thể sử dụng một trong hai định dạng phạm vi.
API phiên bản 4
Sheets API phiên bản 4 sử dụng một hoặc nhiều nhóm phạm vi sau đây:
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
Sử dụng các phạm vi chỉ đọc nếu ứng dụng của bạn không cần chỉnh sửa trang tính hoặc thuộc tính trang tính của người dùng. Sử dụng phạm vi bảng tính thay vì phạm vi Drive nếu ứng dụng không cần quyền truy cập chung vào Drive.
Chế độ hiển thị
Trong các phiên bản cũ của API, thuật ngữ visibility (khả năng hiển thị) được dùng để chỉ tính sẵn có của một bảng tính nhất định.
API phiên bản 3
Sheets API phiên bản 3 thể hiện khả năng hiển thị ngay trong các điểm cuối của mình. Một bảng tính public đã được "Xuất bản lên web" và do đó, API có thể truy cập vào bảng tính này mà không cần uỷ quyền, trong khi bảng tính private yêu cầu xác thực. Chế độ hiển thị được chỉ định trong điểm cuối sau mã nhận dạng bảng tính:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
API phiên bản 4
Trong Sheets API v4 mới, không có khai báo rõ ràng về khả năng hiển thị. Các lệnh gọi API được thực hiện bằng mã nhận dạng bảng tính. Nếu ứng dụng không có quyền truy cập vào bảng tính được chỉ định, thì hệ thống sẽ trả về lỗi. Nếu không, cuộc gọi sẽ tiếp tục.
Dự đoán
API Trang tính phiên bản 3 sử dụng thuật ngữ phép chiếu để chỉ tập hợp dữ liệu mà một lệnh gọi API nhất định trả về (toàn bộ hoặc một tập hợp con cố định được xác định trong API). Sheets API phiên bản 4 không sử dụng phép chiếu; thay vào đó, API này cho phép bạn kiểm soát chặt chẽ hơn những dữ liệu được trả về.
API phiên bản 3
Chỉ có 2 chế độ cài đặt phép chiếu có thể có trong Sheets API phiên bản 3. Phép chiếu full trả về tất cả thông tin có sẵn, trong khi basic trả về một tập hợp con nhỏ hơn, cố định của dữ liệu (đối với các trang tính, danh sách và nguồn cấp dữ liệu ô).
Giống như chế độ hiển thị, bạn phải chỉ định phép chiếu trong điểm cuối API (sau chế độ cài đặt chế độ hiển thị):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Tập hợp con nhỏ hơn của dữ liệu do phép chiếu basic cung cấp rất hữu ích để giúp mã hiệu quả hơn, nhưng không thể tuỳ chỉnh.
API phiên bản 4
Mặc dù Sheets API phiên bản 4 có thể trả về một tập dữ liệu đầy đủ, nhưng API này không xác định các tập hợp con cố định tương tự như chế độ cài đặt chế độ hiển thị basic của Sheets API phiên bản 3.
Các phương thức trong tập hợp spreadsheet (bảng tính) hạn chế lượng dữ liệu mà chúng trả về thông qua việc sử dụng tham số truy vấn fields (trường).
Ví dụ: truy vấn sau đây chỉ trả về tiêu đề của tất cả các trang trong một bảng tính cụ thể:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Tạo bảng tính
API phiên bản 3
Sheets API phiên bản 3 không cung cấp phương tiện để tạo bảng tính mới; thay vào đó, bạn có thể dùng phương thức Drive API Files.create để tạo tệp bảng tính mới. Điều này yêu cầu ứng dụng khai báo phạm vi https://www.googleapis.com/auth/drive.
API phiên bản 4
Bạn cũng có thể dùng phương thức Drive API Files.create với Sheets API phiên bản 4, nhưng ứng dụng phải cung cấp phạm vi https://www.googleapis.com/auth/drive.
Là một lựa chọn thay thế tương đương, Sheets API phiên bản 4 cung cấp phương thức spreadsheets.create. Phương thức này cũng có thể tuỳ ý thêm trang tính, đặt các thuộc tính của bảng tính và trang tính, đồng thời thêm các dải ô được đặt tên. Ví dụ: mã sau đây sẽ tạo một bảng tính mới và đặt tên là "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Liệt kê bảng tính cho người dùng đã xác thực
API phiên bản 3
Nguồn cấp dữ liệu Sheets API phiên bản 3 cho phép một ứng dụng truy xuất danh sách tất cả các bảng tính mà người dùng đã xác thực có thể truy cập. Điểm cuối nguồn cấp dữ liệu bảng tính là:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API phiên bản 4
Sheets API phiên bản 4 không cung cấp thao tác cụ thể này. Bạn nên di chuyển ứng dụng để sử dụng phạm vi drive.file kết hợp với Google Picker để chọn bảng tính.
Trong trường hợp cần liệt kê bảng tính, bạn có thể sử dụng phương thức Files.list của API Drive bằng cách dùng một truy vấn mimeType:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'Việc sử dụng phương thức files.list của Drive API để liệt kê tất cả bảng tính của người dùng yêu cầu một phạm vi bị hạn chế.
Truy xuất siêu dữ liệu của trang tính
Sheets API phiên bản 3 cung cấp một nguồn cấp dữ liệu để truy cập vào siêu dữ liệu của trang tính có trong một bảng tính nhất định (dữ liệu hàng và ô được truy cập thông qua một nguồn cấp dữ liệu riêng). Siêu dữ liệu bao gồm các thông tin như tiêu đề trang tính và thông tin về kích thước.
Phương thức spreadsheets.get của Sheets API phiên bản 4 cho phép truy cập vào thông tin này và nhiều thông tin khác.
API phiên bản 3
Bạn có thể truy cập vào nguồn cấp dữ liệu trang tính từ điểm cuối API này (bằng cách sử dụng tiêu đề uỷ quyền thích hợp):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Phản hồi cho yêu cầu này có cấu trúc tương tự như cấu trúc này, trong đó dữ liệu của mỗi trang tính nằm trong một <entry> riêng biệt:
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
API phiên bản 4
Bạn có thể dùng phương thức spreadsheets.get để thu thập các thuộc tính của trang tính và siêu dữ liệu khác – nhiều hơn so với những gì có sẵn khi dùng Sheets API phiên bản 3. Nếu bạn chỉ muốn đọc các thuộc tính của trang tính, hãy đặt tham số truy vấn includeGridData thành false để ngăn việc đưa dữ liệu ô trong bảng tính vào:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Phản hồi Spreadsheet chứa một mảng các đối tượng Sheet; cụ thể, bạn có thể tìm thấy tiêu đề và thông tin kích thước của trang tính trong phần tử SheetProperties của các đối tượng này. Ví dụ:
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}Thêm trang vào bảng tính
Cả hai API đều cho phép bạn thêm trang tính mới vào một bảng tính hiện có.
API phiên bản 3
Sheets API phiên bản 3 có thể thêm trang tính mới vào bảng tính bằng cách đưa ra yêu cầu POST (đã xác thực) sau đây. Bạn có thể chỉ định kích thước của trang tính mới:
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
API phiên bản 4
Bạn có thể thêm trang tính mới bằng cách đưa ra yêu cầu AddSheet trong phương thức spreadsheets.batchUpdate. Trong nội dung yêu cầu, bạn có thể chỉ định các thuộc tính của trang tính cho trang tính mới; tất cả các thuộc tính đều không bắt buộc. Bạn sẽ gặp lỗi nếu cung cấp một tiêu đề được dùng cho một trang tính hiện có.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Thay đổi tiêu đề và kích thước trang tính
Sheets API phiên bản 3 cho phép bạn cập nhật tiêu đề và kích thước của trang tính; Sheets API phiên bản 4 cũng cho phép bạn làm việc này, nhưng bạn cũng có thể dùng phiên bản này để cập nhật các thuộc tính khác của trang tính. Xin lưu ý rằng việc giảm kích thước của một trang tính có thể khiến dữ liệu trong các ô bị cắt bị xoá mà không có cảnh báo.
API phiên bản 3
Để thay đổi tiêu đề hoặc kích thước của một trang tính, hãy bắt đầu bằng cách truy xuất nguồn cấp dữ liệu trang tính và tìm mục trang tính mong muốn. Mục này chứa một URL edit.
Cập nhật siêu dữ liệu của trang tính và gửi siêu dữ liệu đó dưới dạng nội dung của yêu cầu PUT đến URL chỉnh sửa. Ví dụ:
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
API phiên bản 4
Để cập nhật kích thước, tiêu đề và các thuộc tính khác của trang tính, hãy đưa ra yêu cầu updateSheetProperties trong phương thức spreadsheets.batchUpdate. Phần nội dung yêu cầu POST phải chứa các thuộc tính cần thay đổi và tham số fields phải liệt kê rõ ràng những thuộc tính đó (nếu bạn muốn cập nhật tất cả các thuộc tính, hãy dùng fields:"*" làm từ viết tắt để liệt kê tất cả các thuộc tính). Ví dụ: sau đây chỉ định rằng bạn nên cập nhật các thuộc tính kích thước và tiêu đề trang tính cho trang tính có mã nhận dạng đã cho:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"updateSheetProperties": {
"properties": {
"sheetId": sheetId,
"title": "Expenses",
"gridProperties": {
"rowCount": 45,
"columnCount": 15,
}
},
"fields": "title,gridProperties(rowCount,columnCount)"
}
}
],
}Để truy xuất sheetId của một trang tính, hãy sử dụng phương thức spreadsheets.get của bảng tính.
Xoá trang tính
Cả hai API đều có thể xoá các trang tính khỏi một bảng tính nhất định.
API phiên bản 3
Để xoá một trang tính, hãy bắt đầu bằng cách truy xuất nguồn cấp dữ liệu trang tính, sau đó gửi yêu cầu DELETE trên URL edit của mục trang tính đích.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API phiên bản 4
Để xoá một trang tính, hãy đưa ra yêu cầu DeleteSheet trong phương thức spreadsheets.batchUpdate. Nội dung yêu cầu POST chỉ nên chứa sheetId cho trang cần xoá. Ví dụ:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}Để truy xuất sheetId của một trang tính riêng lẻ, hãy sử dụng phương thức spreadsheets.get của bảng tính.
Truy xuất dữ liệu hàng
Nguồn cấp dữ liệu hàng trong danh sách là một trong hai phương thức mà Sheets API phiên bản 3 cung cấp để truy cập vào dữ liệu trong các ô của bảng tính (phương thức còn lại là nguồn cấp dữ liệu ô). Nguồn cấp dữ liệu hàng được dùng để hỗ trợ các thao tác phổ biến trên bảng tính (đọc từng hàng, thêm hàng, sắp xếp), nhưng đưa ra một số giả định khiến nguồn cấp dữ liệu này không phù hợp với một số tác vụ. Cụ thể, nguồn cấp dữ liệu danh sách giả định rằng các hàng trống là điểm kết thúc của nguồn cấp dữ liệu và các tiêu đề bắt buộc có trong hàng đầu tiên của một trang tính.
Ngược lại, Sheets API phiên bản 4 không sử dụng các phương thức truy cập dành riêng cho hàng. Thay vào đó, dữ liệu ô trong trang tính được truy cập bằng cách tham chiếu đến các dải ô cụ thể cần thiết bằng cách sử dụng ký hiệu A1. Dải ô có thể là khối ô, toàn bộ hàng, toàn bộ cột hoặc toàn bộ trang tính. API này cũng có thể truy cập vào các tập hợp ô rời rạc.
API phiên bản 3
Để xác định URL của một nguồn cấp dữ liệu dựa trên danh sách cho một trang tính nhất định, hãy truy xuất nguồn cấp dữ liệu trang tính và tìm URL nguồn cấp dữ liệu danh sách trong mục trang tính mà bạn quan tâm.
Để truy xuất một nguồn cấp dữ liệu dựa trên danh sách, hãy gửi yêu cầu GET đến URL nguồn cấp dữ liệu danh sách bằng tiêu đề uỷ quyền thích hợp. Ví dụ:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Phản hồi cho yêu cầu này chứa các mục tương ứng với các hàng cụ thể, cùng với những mục khác. Các ô riêng lẻ được tham chiếu theo tên được cung cấp trong hàng tiêu đề trang tính (bắt buộc). Ví dụ: đây là một mục nhập gồm một hàng:
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
Theo mặc định, các hàng được trả về trong nguồn cấp dữ liệu danh sách sẽ được trả về theo thứ tự hàng. Sheets API phiên bản 3 cung cấp các tham số truy vấn để thay đổi thứ tự đó.
Thứ tự ngược lại:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Sắp xếp theo một cột cụ thể:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastnameSheets API phiên bản 3 cũng cho phép lọc các hàng cụ thể thông qua một truy vấn có cấu trúc (được tham chiếu theo tiêu đề cột):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API phiên bản 4
Với Sheets API phiên bản 4, bạn có thể truy xuất các hàng theo dải ô bằng cách sử dụng phương thức spreadsheets.values.get hoặc spreadsheets.values.batchGet. Ví dụ: hàm sau đây trả về tất cả các hàng trong "Trang tính 1":
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
Phản hồi cho yêu cầu này có cấu trúc tương tự như:
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}Các ô trống ở cuối không được đưa vào phản hồi khi truy xuất toàn bộ hàng, cột hoặc trang tính.
Sheets API phiên bản 4 không có các tham số truy vấn theo thứ tự hàng tương đương do Sheets API phiên bản 3 cung cấp. Thứ tự đảo ngược là không đáng kể; chỉ cần xử lý mảng values được trả về theo thứ tự đảo ngược. Thao tác đọc không hỗ trợ sắp xếp theo cột, nhưng bạn có thể sắp xếp dữ liệu trong trang tính (bằng cách sử dụng yêu cầu SortRange) rồi đọc dữ liệu đó.
Sheets API phiên bản 4 hiện không có chức năng tương đương trực tiếp với các truy vấn có cấu trúc của Sheets API phiên bản 3. Tuy nhiên, bạn có thể truy xuất dữ liệu liên quan và sắp xếp dữ liệu đó nếu cần trong ứng dụng của mình.
Thêm một hàng dữ liệu mới
Bạn có thể thêm một hàng dữ liệu mới vào trang tính bằng một trong hai API.
API phiên bản 3
Để xác định URL của một nguồn cấp dữ liệu dựa trên danh sách cho một trang tính nhất định, hãy truy xuất nguồn cấp dữ liệu trang tính và tìm URL bài đăng trong mục trang tính mà bạn quan tâm.
Để thêm một hàng dữ liệu, hãy gửi yêu cầu POST đến URL bài đăng bằng tiêu đề uỷ quyền thích hợp. Ví dụ:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Nội dung của yêu cầu POST phải chứa một mục cho dữ liệu hàng cần thêm, với các ô riêng lẻ được tham chiếu theo tiêu đề cột:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
Các hàng mới sẽ được thêm vào cuối trang tính được chỉ định.
API phiên bản 4
Với Sheets API phiên bản 4, bạn có thể thêm các hàng bằng phương thức spreadsheets.values.append. Ví dụ sau đây ghi một hàng dữ liệu mới bên dưới bảng cuối cùng trong "Sheet1" của một bảng tính.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Ngoài ra, Sheets API phiên bản 4 cũng cho phép bạn thêm các ô có thuộc tính và định dạng cụ thể bằng cách sử dụng các yêu cầu AppendCells trong spreadsheets.batchUpdate.
Chỉnh sửa một hàng bằng dữ liệu mới
Cả hai API đều cho phép cập nhật dữ liệu hàng bằng các giá trị mới.
API phiên bản 3
Để chỉnh sửa một hàng dữ liệu, hãy xem nguồn cấp dữ liệu danh sách để tìm mục nhập cho hàng mà bạn muốn cập nhật. Cập nhật nội dung của mục đó nếu cần. Đảm bảo rằng giá trị mã nhận dạng trong mục mà bạn sử dụng khớp chính xác với mã nhận dạng của mục hiện có.
Sau khi bạn cập nhật mục nhập, hãy gửi yêu cầu PUT có mục nhập đó làm nội dung yêu cầu đến URL edit được cung cấp trong mục nhập hàng đó, bằng cách sử dụng tiêu đề uỷ quyền thích hợp. Ví dụ:
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
API phiên bản 4
Với Sheets API phiên bản 4, bạn có thể chỉnh sửa một hàng bằng cách sử dụng ký hiệu A1 của hàng mà bạn muốn chỉnh sửa và đưa ra yêu cầu spreadsheets.values.update để ghi đè hàng đó. Phạm vi được chỉ định chỉ cần tham chiếu đến ô đầu tiên trong hàng; API sẽ suy ra các ô cần cập nhật dựa trên các giá trị được cung cấp cùng với yêu cầu. Nếu bạn chỉ định một dải ô, thì các giá trị bạn cung cấp phải nằm trong dải ô đó; nếu không, API sẽ trả về lỗi.
Yêu cầu và nội dung yêu cầu mẫu sau đây sẽ thêm dữ liệu vào hàng thứ tư của "Sheet1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Bạn cũng có thể cập nhật dữ liệu hàng bằng phương thức spreadsheet.values.batchUpdate; sẽ hiệu quả hơn nếu bạn thực hiện nhiều lượt cập nhật hàng hoặc ô.
Ngoài ra, Sheets API phiên bản 4 cũng cho phép bạn chỉnh sửa các thuộc tính ô và định dạng của ô bằng cách sử dụng các yêu cầu UpdateCells hoặc RepeatCell trong spreadsheets.batchUpdate.
Xoá một hàng
Cả hai API đều hỗ trợ việc xoá các hàng. Hàng bị xoá sẽ bị loại bỏ khỏi bảng tính và các hàng bên dưới sẽ được đẩy lên một hàng.
API phiên bản 3
Để xoá một hàng, trước tiên, hãy truy xuất hàng cần xoá khỏi nguồn cấp dữ liệu danh sách, sau đó gửi yêu cầu DELETE đến URL edit được cung cấp trong mục nhập của hàng.
Đây là URL được dùng để cập nhật hàng.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Nếu bạn muốn đảm bảo rằng bạn không xoá một hàng đã được thay đổi bởi một ứng dụng khác kể từ khi bạn truy xuất hàng đó, hãy thêm tiêu đề HTTP If-Match chứa giá trị ETag của hàng ban đầu. Bạn có thể xác định giá trị ETag của hàng ban đầu bằng cách kiểm tra thuộc tính gd:etag của phần tử mục nhập.
Nếu bạn muốn xoá hàng bất kể người khác có cập nhật hàng đó hay không kể từ khi bạn truy xuất, hãy sử dụng If-Match: * và không thêm ETag. (Trong trường hợp này, bạn không cần truy xuất hàng trước khi xoá.)
API phiên bản 4
Việc xoá các hàng bằng Sheets API phiên bản 4 được xử lý bằng lệnh gọi phương thức spreadsheet.batchUpdate, sử dụng yêu cầu DeleteDimension. Yêu cầu này cũng có thể dùng để xoá các cột, đồng thời nhà phát triển có thể chọn chỉ xoá một phần của hàng hoặc cột. Ví dụ: mã sau đây sẽ xoá hàng thứ 6 của một trang tính có mã nhận dạng đã cho (chỉ mục hàng dựa trên 0, với startIndex bao gồm và endIndex loại trừ):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}Bạn có thể truy xuất sheetId của một trang tính bằng phương thức spreadsheet.get.
Truy xuất dữ liệu ô
Sheets API phiên bản 3 cung cấp một nguồn cấp dữ liệu ô để truy cập cơ bản vào tất cả dữ liệu được lưu trữ trong một bảng tính. Đối với quyền đọc, nguồn cấp dữ liệu ô có thể cung cấp toàn bộ nội dung trang tính hoặc một dải ô của trang tính do một tập hợp tham số truy vấn xác định, nhưng chỉ dưới dạng một khối duy nhất – bạn phải truy xuất các dải ô rời rạc riêng biệt bằng cách sử dụng các yêu cầu GET bổ sung.
Sheets API phiên bản 4 có thể truy xuất mọi tập hợp dữ liệu ô từ một trang tính (bao gồm cả nhiều dải ô rời rạc). Sheets API phiên bản 3 chỉ có thể trả về nội dung ô dưới dạng giá trị đầu vào (như người dùng nhập bằng bàn phím) và/hoặc đầu ra của công thức (nếu là số); Sheets API phiên bản 4 cấp quyền truy cập đầy đủ vào các giá trị, công thức, định dạng, siêu liên kết, xác thực dữ liệu và các thuộc tính khác.
API phiên bản 3
Để xác định URL của nguồn cấp dữ liệu dựa trên ô cho một trang tính nhất định, hãy kiểm tra nguồn cấp dữ liệu trang tính và tìm URL nguồn cấp dữ liệu ô trong mục trang tính mà bạn quan tâm.
Để truy xuất một nguồn cấp dữ liệu dựa trên ô, hãy gửi yêu cầu GET đến URL nguồn cấp dữ liệu ô bằng cách sử dụng tiêu đề uỷ quyền thích hợp. Ví dụ:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Các ô được tham chiếu bằng số hàng và số cột. Bạn có thể tìm nạp một dải ô cụ thể bằng cách sử dụng các tham số truy vấn max-row, min-row, max-col và min-col. Ví dụ: mã sau đây truy xuất tất cả các ô trong cột 4 (D), bắt đầu từ hàng 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4Sheets API phiên bản 3 trả về inputValue của các ô đã truy xuất – giá trị mà người dùng sẽ nhập vào giao diện người dùng Google Trang tính để thao tác với ô. inputValue có thể là một giá trị cố định hoặc một công thức. Đôi khi, API cũng trả về một numericValue; ví dụ: khi một công thức cho ra kết quả là một số. Ví dụ: một phản hồi có thể bao gồm các mục ô có cấu trúc tương tự như sau:
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
API phiên bản 4
Truy xuất dữ liệu ô bằng cách gọi phương thức spreadsheets.values.get hoặc spreadsheets.values.batchGet cho dải ô hoặc các dải ô mà bạn quan tâm, tương ứng. Ví dụ: hàm sau đây sẽ trả về các ô trong cột D của "Trang tính 2", bắt đầu từ hàng 2, theo thứ tự ưu tiên cột và trả về các công thức như đã nhập (các ô trống ở cuối sẽ bị bỏ qua):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Phản hồi cho yêu cầu này có cấu trúc tương tự như:
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}Sẽ hiệu quả hơn nếu bạn sử dụng spreadsheet.values.batchGet nếu có ý định truy xuất nhiều dải dữ liệu ô. Nếu muốn truy cập vào các thuộc tính của ô (chẳng hạn như định dạng), bạn phải dùng phương thức spreadsheet.get.
Chỉnh sửa ô
Sheets API phiên bản 3 cho phép bạn chỉnh sửa nội dung ô bằng cách phát lệnh PUT cho nguồn cấp dữ liệu ô với mục ô đã sửa đổi làm nội dung yêu cầu.
Ngược lại, Sheets API phiên bản 4 cung cấp các phương thức spreadsheets.values.update và spreadsheets.values.batchUpdate để thay đổi nội dung ô.
API phiên bản 3
Để chỉnh sửa nội dung của một ô, trước tiên, hãy tìm mục nhập của ô đó trong nguồn cấp dữ liệu ô.
Mục nhập này chứa một URL chỉnh sửa. Cập nhật mục nhập để phản ánh nội dung bạn muốn ô có, sau đó đưa ra yêu cầu PUT đối với URL chỉnh sửa bằng mục nhập ô đã cập nhật làm nội dung yêu cầu. Ví dụ: nội dung cập nhật sau đây cho ô D2 (R2C4) chứa công thức SUM:
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
API phiên bản 4
Bạn có thể chỉnh sửa một ô trong Sheets API phiên bản 4 bằng phương thức spreadsheets.values.update. Phương thức này yêu cầu tham số truy vấn ValueInputOption, trong đó chỉ định liệu dữ liệu đầu vào có được coi như đã nhập vào giao diện người dùng Trang tính (USER_ENTERED) hay không được phân tích cú pháp và được lấy nguyên trạng (RAW). Ví dụ: thao tác sau đây sẽ cập nhật ô D2 bằng một công thức:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}Nếu bạn đang chỉnh sửa nhiều ô, hãy sử dụng phương thức spreadsheets.values.batchUpdate để đưa ra các chỉnh sửa đó trong một yêu cầu.
Chỉnh sửa nhiều ô thông qua yêu cầu hàng loạt
Cả hai API này đều cung cấp phương tiện để thay đổi nội dung của nhiều ô bằng một yêu cầu duy nhất (hàng loạt). Các ô được yêu cầu theo lô không bắt buộc phải nằm trong một dải ô liền kề.
Trong trường hợp một hoặc nhiều thao tác chỉnh sửa ô trong lô không thành công, Sheets API phiên bản 3 vẫn cho phép các thao tác khác thành công. Tuy nhiên, Sheets API phiên bản 4 sẽ trả về lỗi nếu có bất kỳ bản cập nhật nào theo lô không thành công và không áp dụng bất kỳ bản cập nhật nào trong trường hợp đó.
API phiên bản 3
Để chỉnh sửa nhiều ô, trước tiên, hãy truy xuất một nguồn cấp dữ liệu ô cho trang tính. Mục này có chứa một URL hàng loạt. Gửi một yêu cầu POST đến URL này, cùng với một phần nội dung yêu cầu mô tả các ô bạn muốn cập nhật và nội dung mới của ô. Yêu cầu POST và nội dung yêu cầu có cấu trúc tương tự như sau:
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
Trường batch:id phải xác định riêng biệt yêu cầu trong lô.
Trường batch:operation phải là update để chỉnh sửa ô. gs:cell xác định ô theo số hàng và cột, đồng thời cung cấp dữ liệu mới để chèn vào đó. id chứa URL đầy đủ của ô cần cập nhật.
link phải có một thuộc tính href chứa đường dẫn đầy đủ đến mã nhận dạng của ô. Bạn phải điền vào tất cả các trường này cho mỗi mục nhập.
API phiên bản 4
Sheets API phiên bản 4 cung cấp tính năng chỉnh sửa hàng loạt giá trị ô thông qua phương thức spreadsheets.values.batchUpdate.
Bạn có thể chỉnh sửa nhiều ô bằng cách đưa ra yêu cầu POST với các thay đổi về dữ liệu được chỉ định trong nội dung yêu cầu. Ví dụ:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
"valueInputOption": "USER_ENTERED"
"data": [
{"range": "D4",
"majorDimension": "ROWS",
"values": [["newData"]]
},
{"range": "B5",
"majorDimension": "ROWS",
"values": [["moreInfo"]]
}
]
}Nếu bạn chỉ định một ô duy nhất làm dải ô, thì tất cả giá trị được cung cấp sẽ được ghi vào trang tính, bắt đầu từ ô đó làm toạ độ trên cùng bên trái. Nếu bạn chỉ định một dải ô, thì các giá trị bạn cung cấp phải khớp chính xác với dải ô đó; nếu không, API sẽ trả về lỗi.