Di chuyển từ API Trang tính v3

Nếu đang có ứng dụng dựa trên API Google Trang tính phiên bản 3, 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à thêm một lượng đáng kể chức năng mà không thể trong phiên bản v3.

Trang này cung cấp mối liên kết giữa các lệnh cũ của API Trang tính phiên bản 3 và các lệnh tương ứng các thao tác tương đương trong API Trang tính phiên bản 4. Việc lập bản đồ tập trung chủ yếu vào spreadsheets.values tập hợp, cung cấp chức năng đọc và ghi trực tiếp ô. 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 được xử lý bằng bộ sưu tập bảng tính. Lưu ý rằng cấu trúc JSON của API v4 không tương thích ngược với Cấu trúc XML được sử dụng trong phiên bản 3.

Để biết thêm thông tin về các tài nguyên có trong Sheets v4 API, hãy xem Tài liệu tham khảo API.

Ký hiệu và điều khoản

API v3 đề cập đến các trang tính trong một bảng tính cụ thể ở dạng "trang tính". Từ này đồng nghĩa với thuật ngữ "trang tính" mà API phiên bản 4 sử dụng.

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 bạn đang làm việc. Các dịch vụ này cũng thường yêu cầu ID của đang bị chỉnh sửa. Các giá trị này xuất hiện dưới dạng một phần của điểm cuối API URL, dưới dạng tham số truy vấn hoặc là một phần của nội dung yêu cầu. Trong trang này, phần giữ chỗ spreadsheetIdsheetId sẽ tham chiếu đến mã bảng tính và mã trang tính tương ứng. Khi sử dụng phương thức được mô tả trên trang này, hãy thay thế mã nhận dạng thực tế ở những vị trí này.

API v3 cũng chỉ định mã nhận dạng cho các hàng được truy xuất bằng cách sử dụng danh sách nguồn cấp dữ liệu; điều 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 của mình để 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à bí danh của

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

Trang tính 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

Dùng 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 của 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ữ chế độ 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

API Trang tính phiên bản 3 cho thấy chế độ hiển thị ngay trong các điểm cuối. Một public bảng tính đã được "Công bố lên Web" và do đó có thể được truy cập bởi API khi chưa được uỷ quyền, trong khi bảng tính private lại yêu cầu xác thực. Chế độ hiển thị được chỉ định trong điểm cuối sau mã 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, chúng tôi không khai báo rõ ràng về chế độ hiển thị. Lệnh gọi API được thực hiện bằng mã 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, một lỗi sẽ được trả về. Nếu không cuộc gọi sẽ tiếp tục.

Dự đoán

Thuật ngữ phép chiếu được API Trang tính phiên bản 3 sử dụng để chỉ tập hợp dữ liệu được 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 xác định trong API. API Trang tính phiên bản 4 không sử dụng tính năng chiếu; đúng hơn là cho phép bạn kiểm soát nhiều hơn đối với 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 có thể áp dụng trong API Trang tính phiên bản 3. full phép chiếu 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 tùy chọn 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 được phép chiếu basic cung cấp có giá trị để làm cho mã hiệu quả hơn, nhưng không thể tuỳ chỉnh được.

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 giá trị cố định các tập hợp con tương tự với chế độ hiển thị basic trong API Trang tính phiên bản 3. Các phương thức trong bảng tính và hạn chế lượng dữ liệu mà các công cụ này trả về thông qua việc sử dụng tham số truy vấn fields.

Ví dụ: truy vấn sau 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

Trang tính API v3 không cung cấp phương tiện để tạo bảng tính mới; thay vào đó, API Drive Files.create phương pháp khác có thể được sử dụng để tạo tệp bảng tính mới. Điều này đòi hỏi để khai báo phạm vi https://www.googleapis.com/auth/drive.

API phiên bản 4

Phương thức API Drive Files.create có thể cũng dùng được 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.

Thay vào đó, API Trang tính v4 cung cấp spreadsheets.create phương thức này, cũng có thể tuỳ ý thêm trang tính, đặt bảng tính và trang tính thuộc tính và thêm dải ô được đặt tên. Ví dụ: đoạn mã sau đây sẽ tạo ra một bảng tính 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 v3 cho phép ứng dụng truy xuất danh sách tất cả mà người dùng đã xác thực có thể truy cập. Nguồn cấp dữ liệu bảng tính điểm cuối 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 bạn để sử dụng phạm vi drive.file kết hợp với Bộ chọn của Google để lựa chọn bảng tính.

Trong trường hợp yêu cầu bảng tính liệt kê, bảng tính đó có thể được sao chép thông qua phương thức API Drive API Files.list bằng cách sử dụng truy vấn mimeType:

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

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ó phạm vi có giới hạn.

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 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à kích thước.

API Trang tính phiên bản 4 spreadsheets.get cung cấ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

Có thể truy cập 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ư thế này, với dữ liệu của mỗi trang tính được chứa 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

Trang spreadsheets.get có thể được sử dụng để thu thập thuộc tính trang tính và các siêu dữ liệu khác—rất nhiều ngoài những gì được cung cấp 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 trang tính, hãy đặt truy vấn includeGridData vào false để ngăn việc thêm dữ liệu ô trong bảng tính:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false

Spreadsheet phản hồi chứa một mảng Sheet đồ vật; tiêu đề trang tính và thông tin kích thước cụ thể trong SheetProperties phần tử 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 đang theo dõi yêu cầu POST (đã 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 một AddSheet trong spreadsheets.batchUpdate . Là một phần của nội dung yêu cầu, bạn có thể chỉ định thuộc tính trang tính cho trang tính mới; tất cả thuộc tính là không bắt buộc. Sẽ xảy ra lỗi khi cung cấp tiêu đề được sử dụng cho 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 kích thước và tiêu đề 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 điều này, nhưng cũng có thể được sử dụng để cập nhật các thuộc tính trang tính khác. 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ả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 nhập trang tính mong muốn, trong đó có chứa URL edit. Cập nhật siêu dữ liệu của trang tính rồi gửi dưới dạng phần nội dung của yêu cầu PUT vào 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 tạo một updateSheetProperties yêu cầu trong spreadsheets.batchUpdate . Nội dung yêu cầu POST phải chứa các thuộc tính cần được đã thay đổi và tham số fields phải liệt kê rõ các thuộc tính đó (nếu bạn muốn cập nhật tất cả thuộc tính, hãy sử dụng fields:"*" làm cách viết tắt cho liệt kê tất cả các nhà cung cấp). Cho ví dụ: sau đây là chỉ định rằng tiêu đề và kích thước trang tính thuộc tính phải được cập nhật cho trang tính bằng 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 trang tính, hãy sử dụng bảng tính spreadsheets.get.

Xoá trang tính

Một trong hai 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 đó là gửi yêu cầu DELETE qua 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

Để xóa trang tính, hãy tạo một DeleteSheet yêu cầu trong spreadsheets.batchUpdate . Nội dung yêu cầu POST chỉ nên chứa sheetId cho phần tử 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 từng trang tính, hãy sử dụng phương thức bảng tính spreadsheets.get .

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 v3 cung cấp truy cập vào dữ liệu trong các ô của một bảng tính (các ô khác là nguồn cấp dữ liệu ô). Chiến lược phát hành đĩa đơn nguồn cấp dữ liệu hàng nhằm hỗ trợ các thao tác phổ biến trên bảng tính (đọc từng hàng, thêm các hàng, sắp xếp), nhưng đưa ra một số giả định nhất định khiến nó không phù hợp cho 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à nguồn cấp dữ liệu và các tiêu đề bắt buộc nằm ở 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 hàng cụ thể. Thay vào đó, dữ liệu ô trang tính được truy cập bằng cách tham chiếu đến dải ô bắt buộc bằng ký hiệu A1. Chiến lược phát hành đĩa đơn 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 cũng có thể truy cập vào các tập hợp ô rời nhau.

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 và tìm URL nguồn cấp dữ liệu danh sách trong mục nhập 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 nguồn cấp dữ liệu danh sách, bằng cách sử dụ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 có chứa các mục nhập, tương ứng với các hàng cụ thể. Từng ô được tham chiếu theo các tên được cung cấp trong hàng tiêu đề của trang tính (bắt buộc). Ví dụ: ở đâ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ự đó.

Đảo ngược thứ tự:

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: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 bảng tính có cấu trúc truy vấn (được tham chiếu bởi các tiêu đề cột):

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?sq=age>25%20and%20height<175

API phiên bản 4

Với API Trang tính phiên bản 4, các hàng có thể được truy xuất theo dải ô bằng cách sử dụng hàm spreadsheets.values.get hoặc spreadsheets.values.batchGet . Ví dụ: lệnh sau đây trả về tất cả các hàng trong "Sheet1":

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ó phiên bản tương đương cho truy vấn theo thứ tự hàng tham số do API Trang tính v3 cung cấp. Thứ tự đảo ngược không đáng kể; đơn giản xử lý mảng values được trả về theo thứ tự đảo ngược. Cột sắp xếp theo được hỗ trợ để đọc, nhưng có thể sắp xếp dữ liệu trong trang tính (sử dụng một SortRange) yêu cầu rồi đọc yêu cầ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 các 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 có liên quan và để chúng tôi có thể sắp xếp 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 và tìm URL của bài đăng trong mục bạn quan tâm trên trang tính.

Để thêm một hàng dữ liệu, hãy gửi một yêu cầu POST đến URL của bài đăng, bằng cách sử dụng 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ột mục nhập cho dữ liệu hàng để thêm, với các ô riêng lẻ được tham chiếu bởi 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 API Trang tính phiên bản 4, bạn có thể nối các hàng bằng cách sử dụng phương thức spreadsheets.values.append . Ví dụ sau viết một hàng dữ liệu mới bên dưới bả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, API Trang tính phiên bản 4 cũng cho phép bạn nối các ô có chứa thuộc tính và định dạng bằng cách sử dụng AppendCells các yêu cầu trong một 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 kiểm tra 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 nhập đó nếu cần. Hãy đảm bảo rằng đúng giá trị mã nhận dạng trong mục nhập mà bạn sử dụng khớp với mã của mục nhập hiện có.

Sau khi mục nhập đã được cập nhật, hãy gửi yêu cầu PUT kèm theo mục nhập là nội dung yêu cầu với URL edit được cung cấp trong mục nhập của 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 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 spreadsheets.values.update yêu cầu 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 kèm theo yêu cầu. Thay vào đó, nếu bạn chỉ định một dải ô nhiều ô, các giá trị mà bạn cung cấp phải nằm trong phạm vi đó; nếu không, API trả về một .

Yêu cầu mẫu và nội dung yêu cầ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ừ spreadsheet.values.batchUpdate phương thức; sẽ hiệu quả hơn nếu bạn sử dụng phương pháp này nếu bạn tạo nhiều nội dung cập nhật hàng hoặc ô.

Ngoài ra, Sheets API v4 cũng cho phép bạn chỉnh sửa các thuộc tính ô và bằng cách sử dụng UpdateCells hoặc RepeatCell các yêu cầu trong một spreadsheets.batchUpdate.

Xoá hàng

Cả hai API đều hỗ trợ tính năng xoá hàng. Một hàng bị xoá sẽ bị gỡ bỏ khỏi và các hàng bên dưới bảng tính đó được đẩy lên trê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 danh sách nguồn cấp dữ liệu, 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 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á một hàng đã bị thay đổi bởi một ứng dụng khác kể từ khi bạn truy xuất, hãy bao gồm tiêu đề HTTP If-Match có chứa giá trị ETag của hàng gốc. Bạn có thể xác định biến thể gốc giá trị ETag của hàng 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ập nhật hay chưa kể từ khi bạn truy xuất, hãy sử dụng If-Match: * và không bao gồ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 bằng API Trang tính phiên bản 4 được xử lý bằng spreadsheet.batchUpdate lệnh gọi phương thức bằng cách sử dụng DeleteDimension của bạn. Bạn cũng có thể dùng yêu cầu này để xoá cột và nhà phát triển và chọn chỉ xoá một phần của hàng hoặc cột. Ví dụ: sau đây sẽ xóa hàng thứ 6 của trang tính có ID đã cho (chỉ mục hàng đều dựa trên 0, bao gồm startIndex 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
        }
      }
    }
  ],
}

Có thể truy xuất sheetId của trang tính bằng cách sử dụ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 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ộ trang tính nội dung hoặc một dải ô của trang tính được xác định bằng một nhóm tham số truy vấn, nhưng chỉ dưới dạng một khối duy nhất—các dải ô rời rạc phải được truy xuất riêng 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 bất kỳ tập dữ liệu ô nào từ 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 các giá trị đầu vào (như được người dùng nhập vào bàn phím) và/hoặc kết quả của công thức (nếu là số); API Trang tính phiên bản 4 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 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 bạn quan tâm trong trang tính.

Để 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 nguồn cấp dữ liệu của ô, 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. Tìm nạp một mục cụ thể dải ô có thể được thực hiện bằng cách sử dụng max-row, min-row, max-colmin-col tham số truy vấn. Ví dụ: lệ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 phiên bản 3 trả về inputValue của các ô đã truy xuất—dữ liệu mà người dùng sẽ nhập vào người dùng Google Trang tính giao diện để 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 này cũng trả về một numericValue; ví dụ: khi công thức cho kết quả là một số. Ví dụ: một phản hồi có thể bao gồm ô mục nhập tương tự có cấu trúc 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 di động bằng cách gọi một spreadsheets.values.get hoặc spreadsheets.values.batchGet cho dải ô hoặc các dải ô quan tâm, tương ứng. Ví dụ: lệnh sau sẽ trả về các ô trong cột D của "Sheet2", 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 (dấu chấm ở cuối là ô trống) ô 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ử dụng cách này sẽ hiệu quả hơn spreadsheet.values.batchGet nếu bạn định truy xuất nhiều dải ô dữ liệu. Nếu bạn muốn truy cập vào các thuộc tính của ô như định dạng, spreadsheet.get là bắt buộc.

Chỉnh sửa ô

API Trang tính v3 cho phép bạn chỉnh sửa nội dung ô bằng cách phát lệnh PUT để nguồn cấp dữ liệu ô có mục nhập ô đã sửa đổi là nội dung yêu cầu.

Ngược lại, API Trang tính v4 cung cấp spreadsheets.values.updatespreadsheets.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 có chứa một URL chỉnh sửa. Cập nhật mục nhập để phản ánh nội dung mà bạn muốn ô có, rồi đưa ra yêu cầu PUT đối với url chỉnh sửa với mục nhập ô được cập nhật là phần nội dung của yêu cầu. Ví dụ: sau khi cập nhật ô 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 API Trang tính phiên bản 4 bằng spreadsheets.values.update . Phương thức này yêu cầu tham số truy vấn ValueInputOption chỉ định xem dữ liệu đầu vào có được xử lý như thể được nhập vào Giao diện người dùng của Trang tính (USER_ENTERED) hoặc không được phân tích cú pháp và giữ nguyên (RAW). Cho ví dụ: đoạn mã 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 nhiều chỉnh sửa ô, hãy sử dụng spreadsheets.values.batchUpdate để phát hành chúng trong một yêu cầu.

Chỉnh sửa nhiều ô 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 phạm vi đồng thời.

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, thì API Trang tính v3 sẽ cho phép người khác thực hiện thành công. Tuy nhiên, API Trang tính phiên bản 4 trả về lỗi nếu có bất kỳ nội dung cập nhật theo lô nào không thành công và không áp dụng bất kỳ nội dung 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 nguồn cấp dữ liệu ô cho trang tính. Mục nhập chứa một URL lô. Gửi một POST yêu cầu cho 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 ô mới. 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 duy nhấ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à 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ó thuộc tính href chứa đường dẫn đầy đủ đến mã nhận dạng ô. 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 các giá trị của ô thông qua spreadsheets.values.batchUpdate .

Bạn có thể chỉnh sửa nhiều ô bằng cách tạo yêu cầu POST với hàm 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ả các giá trị được 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ị mà bạn cung cấp phải vừa với chính xác phạm vi đó; nếu không, API sẽ trả về lỗi.