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

從 Sheets API 第 3 版進行遷移

如果您有以 Google Sheets API v3 為基礎的現有應用程式，可以遷移至 Google Sheets API v4。這個版本是基於 JSON，具有更容易使用的介面，並新增了 v3 版本無法提供的大量功能。

本頁面提供舊版 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 也會為使用清單動態饋給擷取的資料列指派 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 v3 會直接在端點中表示可見度。public 試算表已「發布至網際網路」，因此 API 無須授權即可存取，但 private 試算表則需要驗證。在工作表 ID 後方的端點中指定瀏覽權限：

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

v4 API

在新版 Sheets API v4 中，沒有明確的顯示設定聲明。使用試算表 ID 發出 API 呼叫。如果應用程式沒有存取指定試算表的權限，系統會傳回錯誤。否則，系統會繼續通話。

投影

Sheets API v3 使用「投影」一詞來指特定 API 呼叫傳回的資料集，包括所有資料或 API 中定義的固定子集。試算表 API 4 版不會使用投影，而是讓您進一步控管要傳回的資料。

v3 API

Sheets API v3 僅提供兩種投影設定。full 投影會傳回所有可用資訊，而 basic 則會傳回較小的固定資料子集 (適用於工作表、清單和儲存格動態饋給)。如同可見度，投影方式必須在 API 端點 (在可見度設定之後) 中指定：

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

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

v4 API

雖然 Google 試算表 API 4 版可以傳回完整資料集，但不會定義固定的子集，類似於 Google 試算表 API 3 版的 basic 可見度設定。試算表集合中的各個方法會透過使用 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 範圍。

試算表 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 選取試算表。

如果需要列出試算表，可以使用 mimeType 查詢，透過 Drive API Files.list 方法複製試算表：

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

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

擷取工作表中繼資料

試算表 API 第 3 版提供動態饋給，可存取特定試算表內含的試算表中繼資料 (資料列和儲存格資料則是透過個別動態饋給存取)。中繼資料包含工作表標題和大小資訊等資訊。

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 v3 提供的兩種方法之一，可用於存取試算表儲存格中的資料 (另一個方法是儲存格動態饋給)。資料列動態饋給旨在支援常見的試算表作業 (逐列讀取、附加資料列、排序)，但會做出特定假設，因此不適合用於某些工作。具體來說，清單動態饋給會假設空白資料列是動態饋給結束，且工作表第一列會顯示必要的標題。

相反地，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 第 3 版提供查詢參數，可用於變更該順序。

反向順序：

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 網址。例如：

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

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

編輯列以新增資料

這兩個 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 4 版時，您可以使用要編輯的資料列的 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 方法更新資料列資料；如果要更新多個資料列或儲存格，使用這個方法會更有效率。

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

刪除資料列

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

使用 Sheets API v4 刪除資料列時，系統會透過 spreadsheet.batchUpdate 方法呼叫，使用 DeleteDimension 要求來處理。這項要求也可用於移除資料欄，開發人員可以選擇只移除部分資料列或欄。舉例來說，以下程式碼會移除指定 ID 工作表的第 6 列 (列索引以 0 為基底，startIndex 包含 startIndex，endIndex 不包含 endIndex)：

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

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

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

擷取儲存格資料

試算表 API 3 版提供單元格動態饋給，可讓您存取儲存在試算表中的所有資料。在讀取存取權方面，儲存格動態饋給可提供整個工作表內容，或由一組查詢參數定義的區間範圍，但只能以單一區塊形式提供，如果要擷取不相交的區間，則必須使用額外的 GET 要求。

試算表 API 4.0 可從試算表擷取任何一組儲存格資料 (包括多個不相交的範圍)。Sheets API 第 3 版只能將儲存格內容做為輸入值 (使用者在鍵盤上輸入的值) 和/或公式的輸出內容 (如果是數值) 傳回；Sheets API 第 4 版則會授予對值、公式、格式、超連結、資料驗證和其他屬性的完全存取權。

v3 API

如要判斷特定工作表的儲存格動態饋給網址，請檢查工作表動態饋給，並在所需工作表項目中找出儲存格動態饋給網址。

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

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

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

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

Sheets API v3 會傳回擷取的儲存格 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 方法，即可擷取儲存格資料。例如，以下指令會以資料欄為主，從第 2 列開始傳回「工作表 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 第 3 版，你可以向儲存格動態饋給發出 PUT 指令，並將已修改的儲存格項目做為要求主體，藉此編輯儲存格內容。

相較之下，試算表 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

您可以使用 spreadsheets.values.update 方法，在 Sheets API v4 中編輯單一儲存格。這個方法需要 ValueInputOption 查詢參數，可指定系統是否將輸入資料視為已輸入 Google 試算表 UI (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 v4 可透過 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 會傳回錯誤。