Nếu đang có các ứng dụng dựa trên API Google Trang tính phiên bản 3, thì bạn có thể chuyển sang API Google Trang tính phiên bản 4. Phiên bản v4 dựa trên JSON, có giao diện dễ sử dụng hơn và bổ sung một lượng chức năng đáng kể không có trong phiên bản v3.
Trang này cung cấp mối liên kết giữa các lệnh API Trang tính cũ phiên bản 3 và các thao tác tương đương với các lệnh đó trong API Trang tính phiên bản 4. Quá trình liên kết tập trung chủ yếu vào bộ sưu tập spreadsheets.values, cung cấp chức năng đọc và ghi ô trực tiếp. Các khía cạnh khác như thêm trang tính hoặc cập nhật thuộc tính trang tính sẽ do bộ sưu tập bảng tính xử lý. Lưu ý rằng cấu trúc JSON của API v4 không tương thích ngược với các cấu trúc XML dùng trong v3.
Để biết thêm thông tin về các tài nguyên có sẵn trong API Trang tính v4, hãy xem Tài liệu tham khảo API.
Ký hiệu và điều khoản
API v3 gọi các trang tính trong một bảng tính cụ thể là "trang tính". Điều này đồng nghĩa với thuật ngữ "trang tính" mà API phiên bản 4 sử dụng.
Các API thường yêu cầu bạn chỉ định mã nhận dạng bảng tính của bảng tính mà bạn đang xử lý. Các trường này cũng thường yêu cầu chỉnh sửa mã nhận dạng của trang tính. 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 trong nội dung yêu cầu. Trên trang này, phần giữ chỗ spreadsheetId và sheetId lần lượt tham chiếu đến mã nhận dạng bảng tính và mã 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í đó.
API v3 cũng chỉ định 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 thể hiện trên 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
API Trang tính 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à biệt hiệu của
https://www.googleapis.com/auth/spreadsheets
Bạn có thể sử dụng định dạng phạm vi.
API phiên bản 4
API Trang tính phiên bản 4 sử dụng một hoặc nhiều nhóm phạm vi sau:
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 phạm vi chỉ có thể đọc nếu ứng dụng của bạn không cần chỉnh sửa các thuộc tính của trang tính hoặc trang tính của người dùng. 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 API cũ hơn, thuật ngữ visibility 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
API Trang tính phiên bản 3 thể hiện chế độ hiển thị ngay trong các điểm cuối. Bảng tính public đã được "Xuất bản lên web" nên API có thể truy cập mà không cần được uỷ quyền, trong khi bảng tính private yêu cầu phải 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 API Trang tính phiên bản 4 mới, không có nội dung khai báo rõ ràng nào về chế độ hiển thị. 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 đã 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ự kiến
Thuật ngữ phép chiếu được API Trang tính phiên bản 3 sử dụng để đề cập đến tập dữ liệu được một lệnh gọi API nhất định trả về – tất cả hoặc một tập hợp con cố định được xác định trong API. API Trang tính 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 tốt hơn dữ liệu nào được trả về.
API phiên bản 3
Chỉ có hai chế độ cài đặt phép chiếu trong API Trang tính 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 dữ liệu cố định nhỏ hơn (đối với nguồn cấp dữ liệu trang tính, danh sách và ô).
Giống như chế độ hiển thị, phép chiếu phải được chỉ định 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 dữ liệu nhỏ hơn do phép chiếu basic cung cấp rất có giá trị trong việc làm cho mã hiệu quả hơn, nhưng bạn không thể tuỳ chỉnh.
API phiên bản 4
Mặc dù API Trang tính 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 con cố định tương tự với chế độ cài đặt chế độ hiển thị basic của API Trang tính v3.
Các phương thức trong quá trình thu thập bảng tính hạn chế lượng dữ liệu mà các phương thức này trả về thông qua việc sử dụng tham số truy vấn trường.
Ví dụ: Truy vấn sau đây chỉ trả về tiêu đề của tất cả các trang tính 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
API Trang tính phiên bản 3 không cung cấp phương thức tạo bảng tính mới; thay vào đó, bạn có thể dùng phương thức API Drive Files.create để tạo tệp bảng tính mới. Để thực hiện thao tác này, ứng dụng phải khai báo phạm vi https://www.googleapis.com/auth/drive.
API phiên bản 4
Bạn cũng có thể sử dụng phương thức API Drive Files.create với API Trang tính phiên bản 4, nhưng yêu cầu ứng dụng cung cấp phạm vi https://www.googleapis.com/auth/drive.
Một giải pháp thay thế tương đương khác là API Trang tính 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 thuộc tính bảng tính và trang tính cũng như thêm dải ô được đặt tên. Ví dụ: nội dung 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 API Trang tính phiên bản 3 cho phép ứng dụng truy xuất danh sách tất cả bảng tính mà người dùng đã xác thực có thể truy cập. Điểm cuối của 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
API Trang tính 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 của mình để sử dụng phạm vi drive.file kết hợp với Bộ chọn của Google để chọn bảng tính.
Trong trường hợp bắt buộc phải liệt kê bảng tính, bạn có thể sao chép bảng tính đó thông qua phương thức API Files.list của Drive, sử dụng 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 API Drive để liệt kê tất cả bảng tính của người dùng cần có một phạm vi bị hạn chế.
Truy xuất siêu dữ liệu trang tính
API Trang tính 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 API Trang tính phiên bản 4 sẽ cung cấp quyền truy cập vào thông tin này và nhiều chức năng khác.
API phiên bản 3
Bạn có thể truy cập nguồn cấp dữ liệu trang tính qua điểm cuối API này (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ư thế này, với dữ liệu của mỗi trang tính nằm trong một <entry> riêng:
<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ể sử dụng phương thức spreadsheets.get
để lấy các thuộc tính trang tính và siêu dữ liệu khác — nhiều hơn
so với tính năng có sẵn khi sử dụng API Trang tính 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; bạn có thể tìm thấy tiêu đề trang tính và thông tin cụ thể về kích thước 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 tính vào bảng tính
Cả hai API đều cho phép bạn thêm trang tính mới vào bảng tính hiện có.
API phiên bản 3
API Trang tính phiên bản 3 có thể thêm trang tính mới vào bảng tính bằng cách thực hiện yêu cầu POST sau (đã xác thực). 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 tạo 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ả thuộc tính đều không bắt buộc. Sẽ là lỗi khi cung cấp tiêu đề 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
API Trang tính phiên bản 3 cho phép bạn cập nhật tiêu đề và kích thước trang tính; API Trang tính phiên bản 4 cũng cho phép bạn cập nhật tiêu đề và kích thước trang tính nhưng cũng có thể dùng để cập nhật các thuộc tính khác của trang tính. Lưu ý rằng việc giảm kích thước của 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 rồi tìm mục nhập trang tính mong muốn có chứa 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 trang tính khác, hãy thực hiện một yêu cầu updateSheetProperties trong phương thức
spreadsheets.batchUpdate. 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 các 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 cách viết tắt để liệt kê tất cả). Ví dụ: nội dung sau đây chỉ định rằng tiêu đề trang tính và thuộc tính kích thước phải được cập nhật cho trang tính có mã nhận dạng cho sẵn:
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
API có thể xoá 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 nhập 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 tạo yêu cầu DeleteSheet trong phương thức spreadsheets.batchUpdate. Nội dung yêu cầu POST chỉ được chứa sheetId của trang tính 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 danh sách là một trong hai phương thức mà API Trang tính 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 nhằm hỗ trợ các thao tác phổ biến trong bảng tính (đọc từng hàng, nối hàng, sắp xếp), nhưng đưa ra một số giả định nhất định khiến việc 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à các điểm cuối 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 trang tính.
Ngược lại, API Trang tính phiên bản 4 không sử dụng các phương thức truy cập dành riêng cho từng 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 ký hiệu A1. Dải ô có thể là các 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 ô không liên tục.
API phiên bản 3
Để xác định URL của 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 rồi tìm URL nguồn cấp dữ liệu danh sách trong mục trang tính bạn quan tâm.
Để truy xuấ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 của nguồn cấp dữ liệu danh sách, bằng cách sử dụng một 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 các nội dung khác. Các ô riêng lẻ được tham chiếu theo tên được cung cấp trong hàng tiêu đề của trang tính (bắt buộc). Ví dụ: dưới đây là mục nhập 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 được trả về theo thứ tự hàng. API Trang tính phiên bản 3 cung cấp các tham số truy vấn để thay đổi thứ tự đó.
Thứ tự ngược:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Sắp xếp theo cột cụ thể:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastname
API Trang tính 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 các 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 API Trang tính phiên bản 4, bạn có thể truy xuất hàng theo phạm vi bằng cách sử dụng phương thức spreadsheets.values.get hoặc spreadsheets.values.batchGet. Ví dụ: nội dung sau đây sẽ trả về tất cả các hàng trong "Trang tính1":
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.
API Trang tính phiên bản 4 không có các tham số tương đương cho tham số truy vấn theo thứ tự hàng do API Trang tính v3 cung cấp. Thứ tự đảo ngược là không quan trọng; chỉ cần xử lý mảng values được trả về theo thứ tự đảo ngược. Không hỗ trợ sắp xếp thứ tự 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 đó.
API Trang tính phiên bản 4 hiện không có phiên bản tương đương trực tiếp cho truy vấn có cấu trúc API Trang tính 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 bạn.
Thêm 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 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 rồi 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 của bài đăng bằng cách sử dụng một tiêu đề uỷ quyền thích hợp. Ví dụ:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Phần nội dung của yêu cầu POST phải chứa mục nhập để thêm dữ liệu hàng, trong đó có 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 nối vào cuối trang tính được chỉ định.
API phiên bản 4
Với API Trang tính phiên bản 4, bạn có thể thêm các hàng bằng cách sử dụ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 "Trang tính1" của bảng tính.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}
Ngoài ra, API Trang tính phiên bản 4 cũng cho phép bạn nối 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 một spreadsheets.batchUpdate.
Chỉnh sửa hàng có dữ liệu mới
Cả hai API đều cho phép cập nhật các giá trị mới cho dữ liệu hàng.
API phiên bản 3
Để chỉnh sửa một hàng dữ liệu, hãy kiểm tra nguồn cấp dữ liệu danh sách để tìm mục nhập cho hàng bạn muốn cập nhật. Cập nhật nội dung của mục nhập đó nếu cần. Hãy đảm bảo rằng giá trị mã nhận dạng trong mục nhập mà bạn sử dụng khớp chính xác với mã của mục nhập hiện có.
Sau khi cập nhật mục nhập, hãy gửi yêu cầu PUT có mục nhập dưới dạng 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 API Trang tính 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 bạn muốn chỉnh sửa và đưa ra yêu cầu spreadsheets.values.update để ghi đè hàng đó. Dải ô được chỉ định chỉ cần tham chiếu đến ô đầu tiên trong hàng; API dự đoán 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 ô nhiều ô, thì các giá trị bạn cung cấp phải nằm trong phạm vi đó; nếu không, API sẽ trả về một lỗi.
Nội dung yêu cầu và 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 từ phương thức spreadsheet.values.batchUpdate. Phương thức này sẽ hiệu quả hơn nếu bạn đang thực hiện cập nhật nhiều hàng hoặc ô.
Ngoài ra, API Trang tính phiên bản 4 cũng cho phép bạn chỉnh sửa thuộc tính ô và định dạng ô bằng cách sử dụng các yêu cầu UpdateCells hoặc RepeatCell trong một spreadsheets.batchUpdate.
Xoá một hàng
Cả hai API đều hỗ trợ xoá hàng. Một hàng đã xoá sẽ bị gỡ bỏ khỏi bảng tính và các hàng bên dưới hàng đó 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 cũng chính là URL 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á hàng đã bị một ứng dụng khác thay đổi kể từ khi bạn truy xuất, 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 gốc 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 này bất kể người khác đã cập nhật hàng kể từ khi bạn truy xuất hay chưa, 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á hàng có API Trang tính phiên bản 4 sẽ đượ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ể được dùng để xoá cột, và nhà phát triển cũng có thể chọn chỉ xoá một phần của hàng hoặc cột. Ví dụ: nội dung sau đây sẽ xoá hàng thứ 6 của trang tính có mã nhận dạng đã cho (các chỉ mục hàng được tính dựa trên giá trị 0, trong đó chỉ mục startIndex bao gồm và không bao gồm endIndex):
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 ô
API Trang tính phiên bản 3 cung cấp nguồn cấp dữ liệu ô để bạn có thể truy cập cơ bản vào tất cả dữ liệu được lưu trữ trong bảng tính. Để có 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 xác định bằng một bộ tham số truy vấn, nhưng chỉ dưới dạng một khối duy nhất. Bạn phải truy xuất riêng các dải ô không liên kết bằng cách sử dụng các yêu cầu GET bổ sung.
API Trang tính phiên bản 4 có thể truy xuất tập dữ liệu ô bất kỳ trên một trang tính (bao gồm nhiều dải ô rời rạc). API Trang tính v3 chỉ có thể trả về nội dung ô dưới dạng giá trị đầu vào (như được người dùng nhập bằng bàn phím) và/hoặc kết quả của công thức (nếu ở dạng số); API Trang tính v4 cấp toàn quyền truy cập 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 ô 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 nguồn cấp dữ liệu dựa trên ô, hãy gửi yêu cầu GET đến URL của nguồn cấp dữ liệu ô, bằng cách sử dụng một 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 cách sử dụng số hàng và số cột. Bạn có thể thực hiện việc 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ụ: quy trình sau đây truy xuất tất cả các ô trong cột 4 (D), bắt đầu bằng hàng 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4
API Trang tính v3 sẽ trả về inputValue của cá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 công thức dẫn đến một số. Ví dụ: một phản hồi có thể bao gồm các mục nhập ô 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 ô bạn quan tâm, theo cách tương ứng. Ví dụ: nội dung sau đây trả về các ô trong cột D của "Trang tính2", bắt đầu từ hàng 2, theo thứ tự chính của cột và trả về các công thức như đã nhập (bỏ qua các ô trống ở cuối):
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"]]
}]
}
Việc sử dụng spreadsheet.values.batchGet sẽ hiệu quả hơn nếu bạn đị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 bắt buộc phải sử dụng phương thức spreadsheet.get.
Chỉnh sửa ô
API Trang tính phiên bản 3 cho phép bạn chỉnh sửa nội dung ô bằng cách phát một lệnh PUT tới nguồn cấp dữ liệu ô, trong đó mục nhập ô được sửa đổi làm nội dung yêu cầu.
Ngược lại, API Trang tính phiên bản 4 lại 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 chứa 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 đó gửi yêu cầu PUT tới URL chỉnh sửa với mục nhập ô đã cập nhật làm phần nội dung của yêu cầu. Ví dụ: sau đây cập nhật ô D2 (R2C4) để chứa một 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ể thực hiện chỉnh sửa một ô trong API Trang tính phiên bản 4 bằng phương thức spreadsheets.values.update. Phương thức này đòi hỏi một tham số truy vấn ValueInputOption. Tham số này chỉ định xem dữ liệu đầu vào sẽ được xử lý như thể được 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à lấy nguyên trạng (RAW). Ví dụ: sau đây 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 thực hiện chỉnh sửa nhiều ô, hãy sử dụng phương thức spreadsheets.values.batchUpdate để thực hiện 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 đều cung cấp phương tiện để thực hiện thay đổi đối với nội dung của nhiều ô bằng một yêu cầu (theo lô). Các ô được yêu cầu hàng loạt tham chiếu đến không bắt buộc phải nằm trong một dải ô ngẫu nhiên.
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, API Trang tính phiên bản 3 sẽ cho phép các thao tác khác thành công. Tuy nhiên, API Trang tính phiên bản 4 sẽ trả về lỗi nếu có bất kỳ bản cập nhật theo lô nào không thành công và không áp dụng bất kỳ lỗi nào trong số đó 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 nguồn cấp dữ liệu ô cho trang tính. Mục nhập chứa một URL của lô. Gửi yêu cầu POST đến URL này, cùng với nội dung yêu cầu mô tả các ô bạn muốn cập nhật và nội dung của ô mới. Nội dung yêu cầu và yêu cầu POST 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 duy nhất yêu cầu trong lô.
Trường batch:operation phải có giá trị update để chỉnh sửa ô. gs:cell xác định ô theo số hàng và số cột, đồng thời cung cấp dữ liệu mới để chèn vào đó. id chứa URL đầy đủ đến ô 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 ô. Tất cả các trường này là bắt buộc cho mỗi mục nhập.
API phiên bản 4
API Trang tính phiên bản 4 cho phép 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 tạo một 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 ô làm dải ô, thì tất cả giá trị đã cung cấp sẽ được ghi vào trang tính, bắt đầu với ô đó là toạ độ trên bên trái. Thay vào đó, nếu bạn chỉ định một dải ô nhiều ô, 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ề một lỗi.