本頁面由 Cloud Translation API 翻譯而成。

從 Sheets API 第 3 版進行遷移

如果您有以 Google Sheets API v3 為基礎的現有應用程式，可以遷移至 Google Sheets API v4。第 4 版採用 JSON 格式，介面更易於使用，並新增第 3 版無法提供的多項功能。

本頁面提供舊版 Sheets API 第 3 版指令，以及 Sheets API 第 4 版對等作業的對應關係。對應主要著重於 spreadsheets.values 集合，可直接讀取及寫入儲存格。其他方面 (例如新增工作表或更新工作表屬性) 則由 spreadsheets 集合處理。請注意，v4 API 的 JSON 結構無法與 v3 使用的 XML 結構向後相容。

如要進一步瞭解 Google 試算表 v4 API 提供的資源，請參閱「API 參考資料」。

標記法和術語

v3 API 會將特定試算表中的工作表稱為「工作表」。這與 v4 API 使用的「工作表」一詞同義。

使用這些 API 時，通常需要指定您要使用的試算表試算表 ID。此外，通常也需要操作中的試算表 ID。這些值會顯示在 API 端點網址中、做為查詢參數，或是做為要求內文的一部分。在本頁中，預留位置 spreadsheetId 和 sheetId 分別是指試算表和工作表 ID。使用本頁所述方法時，請在這些位置代入實際 ID。

v3 API 也會為透過 list 資訊提供擷取的資料列指派 ID；本頁面會以 rowId 預留位置表示。

授權要求

應用程式執行時，會要求使用者授予特定權限；應用程式中指定的範圍會決定要求哪些權限。

v3 API

Sheets API v3 採用單一授權範圍：

https://spreadsheets.google.com/feeds

這是

https://www.googleapis.com/auth/spreadsheets

您可以使用任一範圍格式。

v4 API

Sheets API v4 會使用下列一或多個範圍：

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

如果應用程式不需要編輯使用者的試算表或試算表屬性，請使用唯讀範圍。如果應用程式不需要一般雲端硬碟存取權，請改用試算表範圍，而非雲端硬碟範圍。

顯示設定

在舊版 API 中，可見性一詞是指特定試算表的可用性。

v3 API

Sheets API 第 3 版直接在端點中表示瀏覽權限。public 試算表已「發布到網路」，因此 API 無須授權即可存取，但 private 試算表則需要驗證。試算表 ID 後的端點會指定瀏覽權限：

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

v4 API

在新的 Sheets API v4 中，沒有明確宣告可見度。API 呼叫是使用試算表 ID 進行。如果應用程式沒有存取指定試算表的權限，系統會傳回錯誤。否則通話會繼續。

預測值

在 Sheets API v3 中，投影是指特定 API 呼叫傳回的資料集，可能是所有資料，也可能是 API 中定義的固定子集。Google 試算表 API 第 4 版不會使用投影，而是讓您進一步控管要傳回哪些資料。

v3 API

Sheets API v3 中只有兩種可能的投影設定。full 投影會傳回所有可用資訊，而 basic 則會傳回較小的固定資料子集 (適用於工作表、清單和儲存格動態饋給)。與顯示設定一樣，投影必須在 API 端點中指定 (顯示設定之後)：

https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic

basic 投影提供的資料子集較小，有助於提高程式碼效率，但無法自訂。

v4 API

雖然 Sheets API 第 4 版可以傳回完整資料集，但不會定義類似於 Sheets API 第 3 版 basic 可見度設定的固定子集。spreadsheet 集合中的方法會使用 fields 查詢參數，限制傳回的資料量。

舉例來說，下列查詢只會傳回特定試算表中所有工作表的標題：

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title

建立試算表

v3 API

Sheets API v3 不提供建立新試算表的方法，但您可以使用 Drive API Files.create 方法建立新的試算表檔案。應用程式必須宣告 https://www.googleapis.com/auth/drive 範圍。

v4 API

Drive API Files.create 方法也可搭配 Sheets API v4 使用，但應用程式必須提供 https://www.googleapis.com/auth/drive 範圍。

做為替代方案，Sheets API v4 提供 spreadsheets.create 方法，這個方法也可以視需要新增工作表、設定試算表和工作表屬性，以及新增已命名的範圍。舉例來說，下列程式碼會建立新的試算表，並將其命名為「NewTitle」：

POST https://sheets.googleapis.com/v4/spreadsheets

{
 "properties": {"title": "NewTitle"}
}

列出已驗證使用者的試算表

v3 API

應用程式可透過 Sheets API v3 資訊提供，擷取通過驗證的使用者可存取的所有試算表清單。試算表動態饋給端點為：

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

v4 API

Sheets API v4 不提供這項特定作業。建議您遷移應用程式，改用 drive.file 範圍，並搭配 Google Picker 選取試算表。

如需列出試算表，可以使用 Drive API Files.list 方法，並使用 mimeType 查詢來模擬這項操作：

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

如要使用 Drive API files.list 方法列出使用者的所有試算表，必須使用受限範圍。

擷取試算表中繼資料

透過 Sheets API v3 提供的動態饋給，您可以存取特定試算表中的試算表中繼資料 (資料列和儲存格資料則透過另一個動態饋給存取)。中繼資料包含工作表標題和大小等資訊。

您可以使用 Sheets API v4 的 spreadsheets.get 方法存取這項資訊，以及更多內容。

v3 API

您可以透過這個 API 端點存取工作表動態饋給 (使用適當的授權標頭)：

GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

這項要求的回應結構類似於此，每個工作表的資料都包含在個別的 <entry> 中：

<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>

v4 API

spreadsheets.get 方法可用於取得工作表屬性和其他中繼資料，遠遠超過 Sheets API v3 的可用資料。如果只想讀取試算表屬性，請將 includeGridData 查詢參數設為 false，避免納入試算表儲存格資料：

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

Spreadsheet 回應包含 Sheet 物件陣列；具體來說，工作表標題和大小資訊位於這些物件的 SheetProperties 元素下方。例如：

{
  "spreadsheetId": spreadsheetId,
  "sheets": [
      {"properties": {
          "sheetId": sheetId,
          "title": "Sheet1",
          "index": 0,
          "gridProperties": {
              "rowCount": 100,
              "columnCount": 20,
              "frozenRowCount": 1,
              "frozenColumnCount": 0,
              "hideGridlines": false
          },
          ...
       },
       ...
      },
      ...
  ],
  ...
}

在試算表中新增工作表

這兩個 API 都允許您在現有試算表中新增工作表。

v3 API

Sheets API v3 可透過發出下列 (已驗證) POST 要求，在試算表中新增工作表。您可以指定新工作表的大小：

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>

v4 API

如要新增工作表，請在 spreadsheets.batchUpdate 方法中提出 AddSheet 要求。您可以在要求主體中指定新工作表的屬性，所有屬性皆為選填。如果提供的標題與現有工作表相同，系統會顯示錯誤訊息。

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [{
      "addSheet": {
          "properties": {
            "title": "Expenses",
            "sheetType": "GRID",
            "gridProperties": {
              "rowCount": 50,
              "columnCount": 10
            }
          }
      }
  }],
}

變更工作表標題和大小

透過 Sheets API v3，您可以更新工作表標題和大小；Sheets API v4 也提供這項功能，但還可用於更新其他工作表屬性。請注意，縮減工作表大小可能會導致系統刪除裁剪儲存格中的資料，且不會事先警告。

v3 API

如要變更工作表的標題或大小，請先擷取工作表動態消息，然後找出所需的工作表項目，其中包含 edit 網址。更新工作表的中繼資料，並以 PUT 要求的主體形式傳送至編輯網址。例如：

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>

v4 API

如要更新大小、標題和其他工作表屬性，請在 spreadsheets.batchUpdate 方法中提出 updateSheetProperties 要求。POST 要求主體應包含要變更的屬性，且 fields 參數應明確列出這些屬性 (如要更新所有屬性，請使用 fields:"*" 做為列出所有屬性的簡寫)。舉例來說，下列程式碼指定應更新指定 ID 的工作表之工作表標題和大小屬性：

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)"
     }
   }
  ],
}

如要擷取工作表的 sheetId，請使用試算表 spreadsheets.get 方法。

刪除工作表

這兩個 API 都能從指定試算表中移除工作表。

v3 API

如要刪除工作表，請先擷取工作表動態消息，然後在目標工作表項目的 edit 網址上傳送 DELETE 要求。

DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

v4 API

如要刪除工作表，請在 spreadsheets.batchUpdate 方法中提出 DeleteSheet 要求。POST 要求主體應只包含要刪除工作表的 sheetId。例如：

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

如要擷取個別工作表的 sheetId，請使用試算表 spreadsheets.get 方法。

擷取資料列資料

資料列清單動態饋給是 Sheets API 第 3 版提供的兩種方法之一，可存取試算表儲存格中的資料 (另一種是儲存格動態饋給)。資料列動態饋給適用於常見的試算表作業 (逐列讀取、附加資料列、排序)，但由於會做出某些假設，因此不適合用於部分工作。具體來說，清單動態饋給會假設空白列是動態饋給終止符，且必要標題位於試算表的第一列。

相較之下，Sheets API v4 不會使用特定列的存取方法。而是使用 A1 標記參照所需特定範圍，藉此存取試算表儲存格資料。範圍可以是儲存格區塊、整列、整欄或整張工作表。API 也可以存取不相連的儲存格集。

v3 API

如要判斷特定工作表的清單型動態消息網址，請擷取工作表動態消息，然後在感興趣的工作表項目中找出清單動態消息網址。

如要擷取以清單為基礎的動態饋給，請使用適當的授權標頭，將 GET 要求傳送至清單動態饋給網址。例如：

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

這項要求的相關回應會包含對應特定資料列的項目等。個別儲存格會參照 (必要) 工作表標題列中提供的名稱。舉例來說，以下是單列項目：

<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>

根據預設，清單動態消息中傳回的資料列會依資料列順序傳回。 Sheets API v3 提供查詢參數，可變更排序順序。

反向排序：

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true

依特定資料欄排序：

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
             ?orderby=column:lastname

透過 Sheets API v3，您也可以使用結構化查詢 (以資料欄標題為參照)，篩選特定資料列：

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

v4 API

使用 Sheets API 第 4 版時，可以透過 spreadsheets.values.get 或 spreadsheets.values.batchGet 方法，依範圍擷取資料列。舉例來說，下列程式碼會傳回「Sheet1」中的所有資料列：

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1

這項要求的回應結構類似於：

{
  "range": "Sheet1",
  "majorDimension": "ROWS",
  "values": [["Name", "Hours", "Items", "IPM"],
             ["Bingley", "10", "2", "0.0033"],
             ["Darcy", "14", "6", "0.0071"]]
}

擷取整列、整欄或整張工作表時，回應中不會包含結尾的空白儲存格。

Sheets API v4 沒有與 Sheets API v3 提供的資料列順序查詢參數對應的項目。反向排序很簡單，只要以反向順序處理傳回的 values 陣列即可。讀取作業不支援依資料欄排序，但可以先使用 SortRange 要求排序工作表中的資料，然後再讀取。

目前 Sheets API v4 沒有與 Sheets API v3 結構化查詢直接對應的功能。不過，您可以在應用程式中擷取相關資料，並視需要進行排序。

新增資料列

您可以使用任一 API，將新的資料列新增至試算表。

v3 API

如要判斷特定工作表的清單型動態消息網址，請擷取工作表動態消息，然後在感興趣的工作表項目中找出貼文網址。

如要新增資料列，請使用適當的授權標頭，對貼文網址傳送 POST 要求。例如：

POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

POST 要求的本文應包含要新增的資料列項目，並以欄標題參照個別儲存格：

<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>

新資料列會附加在指定工作表的結尾。

v4 API

您可以使用 Sheets API v4 的 spreadsheets.values.append 方法附加資料列。以下範例會在試算表「Sheet1」中，最後一個表格下方寫入新資料列。

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

此外，您也可以在 spreadsheets.batchUpdate 中使用 AppendCells 要求，透過 Sheets API v4 附加具有特定屬性和格式的儲存格。

使用新資料編輯列

這兩個 API 都允許使用新值更新列資料。

v3 API

如要編輯資料列，請檢查清單動態饋給，找出要更新的資料列項目。視需要更新該項目的內容。請務必確認您使用的項目 ID 值與現有項目的 ID 完全相符。

更新項目後，請使用適當的授權標頭，將項目做為要求主體，透過 PUT 要求傳送至該列項目提供的 edit 網址。例如：

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>

v4 API

使用 Sheets API v4 時，您可以透過要編輯的列的 A1 標記，發出 spreadsheets.values.update 要求來覆寫該列，藉此編輯列。指定的範圍只需要參照資料列中的第一個儲存格；API 會根據要求提供的資料推斷要更新的儲存格。如果您改為指定多儲存格範圍，提供的值必須符合該範圍，否則 API 會傳回錯誤。

以下範例要求和要求主體會將資料新增至「Sheet1」的第四列：

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

您也可以使用 spreadsheet.values.batchUpdate 方法更新資料列資料；如果您要更新多個資料列或儲存格，使用這個方法會更有效率。

此外，您也可以在 spreadsheets.batchUpdate 中使用 UpdateCells 或 RepeatCell 要求，透過 Sheets API 第 4 版編輯儲存格屬性和格式。

刪除資料列

這兩個 API 都支援刪除資料列。刪除的資料列會從試算表中移除，下方的資料列則會向上移動一列。

v3 API

如要刪除資料列，請先從清單動態饋給中擷取要刪除的資料列，然後將 DELETE 要求傳送至資料列項目中提供的 edit 網址。這個網址與更新資料列時使用的網址相同。

DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version

如要確保不會刪除自您擷取資料後，由其他用戶端變更的資料列，請加入含有原始資料列 ETag 值的 HTTP If-Match 標頭。您可以檢查項目元素的 gd:etag 屬性，判斷原始資料列的 ETag 值。

如要刪除資料列，無論是否有人在您擷取資料列後更新過，請使用 If-Match: *，且不要加入 ETag。 (在本例中，您不需要先擷取資料列，再刪除資料列)。

v4 API

如要使用 Google Sheets API 第 4 版刪除資料列，請使用 spreadsheet.batchUpdate 方法呼叫，並使用 DeleteDimension 要求。這項要求也可用於移除資料欄，開發人員可選擇只移除部分資料列或資料欄。舉例來說，以下程式碼會移除指定 ID 的試算表第 6 列 (列索引從零開始，startIndex 包含在內，endIndex 則不包含在內)：

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [
    {
      "deleteDimension": {
        "range": {
          "sheetId": sheetId,
          "dimension": "ROWS",
          "startIndex": 5,
          "endIndex": 6
        }
      }
    }
  ],
}

您可以使用 spreadsheet.get 方法擷取工作表的 sheetId。

擷取儲存格資料

透過 Sheets API v3，您可以取得儲存在試算表中的所有資料，並以基本方式存取這些資料。如要取得讀取權限，儲存格動態饋給可提供整份試算表內容，或一組查詢參數定義的試算表儲存格範圍，但只能以單一區塊的形式提供，如要擷取不相連的範圍，必須使用額外的 GET 要求。

透過 Sheets API 第 4 版，您可以從試算表擷取任何一組儲存格資料 (包括多個不相交的範圍)。Sheets API v3 只能傳回儲存格內容做為輸入值 (如同使用者透過鍵盤輸入的值) 和/或公式的輸出內容 (如果是數值)；Sheets API v4 則可完整存取值、公式、格式、超連結、資料驗證和其他屬性。

v3 API

如要判斷特定工作表的儲存格式動態消息網址，請檢查工作表動態消息，並在感興趣的工作表項目中找出儲存格動態消息網址。

如要擷取以儲存格為準的動態饋給，請使用適當的授權標頭，將 GET 要求傳送至儲存格動態饋給網址。例如：

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

儲存格是使用列號和欄號參照。如要擷取特定範圍，可以使用 max-row、min-row、max-col 和 min-col 查詢參數。舉例來說，以下會擷取第 4 欄 (D) 中從第 2 列開始的所有儲存格：

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
             ?min-row=2&min-col=4&max-col=4

Sheets API 第 3 版會傳回擷取儲存格的 inputValue，也就是使用者在 Google 試算表使用者介面中輸入的值，用來操控儲存格。inputValue 可以是常值或公式。API 有時也會傳回 numericValue，例如公式產生數字時。舉例來說，回應可能包含結構類似下列項目的儲存格項目：

<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>

v4 API

如要擷取儲存格資料，請分別針對感興趣的範圍呼叫 spreadsheets.values.get 或 spreadsheets.values.batchGet 方法。舉例來說，下列公式會以欄優先順序，傳回「Sheet2」中從第 2 列開始的 D 欄儲存格，並傳回輸入的公式 (省略結尾的空白儲存格)：

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA

這項要求的結構與下列要求類似：

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
      {"range": "Sheet2!D2:D",
       "majorDimension": "COLUMNS",
       "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
      }]
}

如果您打算擷取多個儲存格資料範圍，使用 spreadsheet.values.batchGet 會更有效率。如要存取格式等儲存格屬性，請使用 spreadsheet.get 方法。

編輯儲存格

透過 Sheets API v3，您可以向儲存格動態饋給發出 PUT 指令，並將修改後的儲存格項目做為要求內文，藉此編輯儲存格內容。

相較之下，Sheets API 第 4 版提供 spreadsheets.values.update 和 spreadsheets.values.batchUpdate 方法，可變更儲存格內容。

v3 API

如要編輯單一儲存格的內容，請先在儲存格動態饋給中找出該儲存格的項目。項目包含編輯網址。更新項目，反映您希望儲存格擁有的內容，然後發出 PUT 要求至編輯網址，並將更新後的儲存格項目做為要求主體。舉例來說，下列指令會更新儲存格 D2 (R2C4)，使其包含 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>

v4 API

如要在 Sheets API v4 中編輯單一儲存格，可以使用 spreadsheets.values.update 方法。這個方法需要 ValueInputOption 查詢參數，用於指定輸入資料的處理方式，是視為在 Google 試算表使用者介面中輸入 (USER_ENTERED)，還是不進行剖析並直接採用 (RAW)。舉例來說，下列程式碼會使用公式更新 D2 儲存格：

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED

{"values": [["=SUM(A1:B6)"]]}

如要編輯多個儲存格，請使用 spreadsheets.values.batchUpdate 方法，在單一要求中發出這些編輯作業。

透過批次要求編輯多個儲存格

這兩項 API 都提供方法，可透過單一 (批次) 要求變更多個儲存格的內容。批次要求參照的儲存格不一定要位於連續範圍內。

如果批次中的一或多個儲存格編輯作業失敗，Sheets API v3 仍允許其他作業成功。不過，如果批次更新中有任何一項失敗，Sheets API v4 就會傳回錯誤，且不會套用任何更新。

v3 API

如要編輯多個儲存格，請先擷取工作表的儲存格動態饋給。項目中包含批次網址。將POST要求傳送至這個網址，並附上要求主體，說明要更新的儲存格和新的儲存格內容。POST 要求和要求主體的結構類似於下列項目：

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>

batch:id 欄位應可明確識別批次中的要求。如要編輯儲存格，batch:operation 欄位應為 update。gs:cell 依據列和欄編號識別儲存格，並提供要插入的新資料。id 包含要更新的儲存格完整網址。 link 必須具備 href 屬性，其中包含儲存格 ID 的完整路徑。每個項目都必須填寫所有欄位。

v4 API

透過 Sheets API 第 4 版的 spreadsheets.values.batchUpdate 方法，即可批次編輯儲存格值。

如要編輯多個儲存格，請發出 POST 要求，並在要求主體中指定資料變更。例如：

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"]]
       }
  ]
}

如果指定單一儲存格做為範圍，系統會從該儲存格開始，將所有提供的值寫入試算表，做為左上角座標。如果改為指定多儲存格範圍，您提供的值必須完全符合該範圍，否則 API 會傳回錯誤。

從 Sheets API 第 3 版進行遷移 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

標記法和術語

授權要求

v3 API

v4 API

顯示設定

v3 API

v4 API

預測值

v3 API

v4 API

建立試算表

v3 API

v4 API

列出已驗證使用者的試算表

v3 API

v4 API

擷取試算表中繼資料

v3 API

v4 API

在試算表中新增工作表

v3 API

v4 API

變更工作表標題和大小

v3 API

v4 API

刪除工作表

v3 API

v4 API

擷取資料列資料

v3 API

v4 API

新增資料列

v3 API

v4 API

使用新資料編輯列

v3 API

v4 API

刪除資料列

v3 API

v4 API

擷取儲存格資料

v3 API

v4 API

編輯儲存格

v3 API

v4 API

透過批次要求編輯多個儲存格

v3 API

v4 API

從 Sheets API 第 3 版進行遷移