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

從 Sheets API 第 3 版進行遷移

如果您已有以 GoogleSheet API v3 為基礎的應用程式，可遷移至 GoogleSheet API v4。v4 版本以 JSON 為基礎，具有較易使用的介面，並且加入了 v3 版本所沒有的大量功能。

本頁提供舊版 Sheet API v3 指令及其在 Sheet API v4 中同等作業之間的對應關係。對應主要著重於 spreadsheets.values 集合，提供直接儲存格讀取和寫入功能。試算表集合會處理其他層面，例如新增工作表或更新工作表屬性。請注意，v4 API 的 JSON 結構與第 3 版中使用的 XML 結構無法回溯相容。

如要進一步瞭解 Sheet v4 API 提供的資源，請參閱 API 參考資料。

標記與條款

第 3 版 API 將特定試算表中的工作表稱為「工作表」。這就等於 v4 API 使用的「sheet」。

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

v3 API 也會指派 ID 給使用其清單動態饋給擷取的資料列；在本頁中，此 ID 會以 rowId 預留位置表示。

授權要求

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

第 3 版 API

Sheet API v3 是以單一授權範圍運作：

https://spreadsheets.google.com/feeds

做為別名

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

這兩種範圍格式都可使用。

第 4 版 API

Sheet 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 中，「visibility」一詞是指特定試算表的可用性。

第 3 版 API

Sheet API v3 可直接在其端點中表示顯示設定。public 試算表已「發布到網路」，因此可在未授權的情況下透過 API 存取，而 private 試算表則需要驗證。是在試算表 ID 後方的端點中指定的瀏覽權限：

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

第 4 版 API

在新版試算表 API v4 中，使用者並未明確宣告瀏覽權限。系統會使用試算表 ID 發出 API 呼叫。如果應用程式沒有存取指定試算表的權限，系統會傳回錯誤。否則，呼叫會繼續執行。

投影

「投影」一詞代表特定 API 呼叫所傳回的資料集，可以是所有 API 呼叫，或 API 中定義的固定子集。Sheet API v4 並不使用投影，但可讓您進一步控管要傳回哪些資料。

第 3 版 API

試算表 API 第 3 版只能使用兩種投影設定。full 投影會傳回所有可用資訊，basic 則會傳回較小且固定的資料子集 (適用於工作表、清單和儲存格動態饋給)。如同瀏覽權限，您必須在 API 端點 (在瀏覽權限設定之後) 指定投影：

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

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

第 4 版 API

雖然試算表 API v4 可以傳回完整的資料集，但並未定義與 Sheets API v3 中 basic 瀏覽權限設定類似的固定子集合。試算表集合中的方法會限制使用欄位查詢參數傳回的資料量。

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

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

建立試算表

第 3 版 API

試算表 API 第 3 版不提供建立新試算表的方法，您可以使用 Drive API Files.create 方法建立新的試算表檔案。這需要應用程式宣告 https://www.googleapis.com/auth/drive 範圍。

第 4 版 API

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

除此之外，Sheet API 第 4 版提供 spreadsheets.create 方法，還可以選擇性地新增工作表、設定試算表和工作表屬性，以及新增已命名範圍。舉例來說，以下程式碼會建立新的試算表並命名為「NewTitle」：

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

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

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

第 3 版 API

透過 Sheet API v3 動態饋給，應用程式可以擷取已驗證使用者可存取的所有試算表清單。試算表動態饋給端點如下：

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

第 4 版 API

試算表 API 第 4 版不提供這項特定作業。建議您遷移應用程式，以便將 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 方法列出使用者的所有試算表時，您必須要有「受限制」的範圍。

擷取工作表中繼資料

試算表 API 第 3 版提供動態饋給，以存取指定試算表所含的工作表中繼資料 (列與儲存格資料可透過不同的動態饋給存取)。中繼資料包含工作表標題和大小資訊等資訊。

Sheet API v4 spreadsheets.get 方法提供這項資訊與許多其他內容的存取權。

第 3 版 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>

第 4 版 API

spreadsheets.get 方法可用於取得工作表屬性和其他中繼資料，這遠比使用試算表 API 第 3 版所能取得的更多。如果只想讀取工作表屬性，請將 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 皆可讓您在現有試算表中加入新的試算表。

第 3 版 API

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

第 4 版 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
            }
          }
      }
  }],
}

變更工作表標題和大小

使用 Sheet API v3 時，您也可以更新工作表標題和大小；透過 Sheet API 第 4 版，您也可以這麼做，但也可用於更新其他工作表屬性。請注意，縮小工作表大小可能會導致裁剪儲存格中的資料在未事先警告的情況下遭到刪除。

第 3 版 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>

第 4 版 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 方法。

刪除工作表

兩者皆能移除指定試算表中的工作表。

第 3 版 API

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

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

第 4 版 API

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

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

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

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

擷取資料列資料

清單列動態饋給是試算表 API 第 3 版提供的兩種方法之一 (另一個是儲存格動態饋給)，是存取試算表儲存格內資料的方法之一。資料列動態饋給主要用於支援常見的試算表作業 (依資料列讀取、附加資料列、排序)，但會做出某些假設，導致其不適合執行某些工作。具體來說，清單動態饋給會假設空白列是動態饋給終止項目，且工作表的第一列含有必要標題。

相較之下，Sheets API 第 4 版不會使用特定資料列的存取方法。如要存取工作表儲存格資料，請改用 A1 標記法參照所需的特定範圍。範圍可以是儲存格區塊、整個資料列、整個資料欄或整個工作表。這個 API 也可存取不交集的儲存格集。

第 3 版 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>

根據預設，清單動態饋給傳回的資料列會按照資料列順序傳回。 Sheet 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

Sheet API v3 也可讓您透過結構化查詢 (依欄標題參照) 篩選特定資料列：

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

第 4 版 API

在 Sheet API v4 中，可運用 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"]]
}

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

Sheet API v4 沒有與 Sheet API v3 提供的資料列順序查詢參數相等，反向順序並不重要，只會反向處理傳回的 values 陣列。讀取作業不支援依資料欄排序，但您可以使用 SortRange 要求排序工作表中的資料，然後讀取資料。

Sheet API v4 目前對於試算表 API v3 結構化查詢沒有直接對等項目。不過，您可以在應用程式中擷取相關資料，並視需要在應用程式中進行排序。

新增資料列

您可以使用任一 API 在工作表中新增一列資料。

第 3 版 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>

系統會在指定工作表的結尾附加新的列。

第 4 版 API

在 Sheet 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 都允許更新資料列資料與新的值。

第 3 版 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>

第 4 版 API

使用 Sheet 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 方法更新資料列資料；如要進行多個資料列或儲存格更新，使用這個方法會比較有效率。

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

刪除資料列

這兩個 API 都支援刪除資料列。刪除的資料列會從試算表中移除，而下方的資料列會往上推。

第 3 版 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。(在這種情況下，您不需要先擷取資料列再刪除該資料列)。

第 4 版 API

使用試算表 API v4 刪除資料列時，是由 spreadsheet.batchUpdate 方法呼叫處理，並使用 DeleteDimension 要求。這項要求也可用於移除資料欄，以及開發人員，選擇只移除部分資料列或資料欄。例如，下列指令會移除具有指定 ID 的工作表第 6 列 (資料列索引從零開始，其中 startIndex 含首尾)：

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 v4 可以從工作表擷取任何一組儲存格資料 (包括多個不交集的範圍)。試算表 API v3 只能將儲存格內容回傳為輸入值 (就像使用者在鍵盤輸入時一樣)，和/或公式的輸出內容 (如數字)；Sheets API v4 授予值、公式、格式、超連結、資料驗證及其他屬性的完整存取權。

第 3 版 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

試算表 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>

第 4 版 API

針對所需的範圍或範圍呼叫 spreadsheets.values.get 或 spreadsheets.values.batchGet 方法，藉此擷取儲存格資料。例如，下列指令會傳回 D 欄「Sheet2」的儲存格 (從第 2 列開始，以資料欄主要順序開始)，然後傳回輸入的公式 (省略結尾的空白儲存格)：

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 方法。

編輯儲存格

透過 Sheet API 第 3 版，您可以對儲存格動態饋給發出 PUT 指令，並將修改後的儲存格項目做為要求主體，藉此編輯儲存格內容。

相較之下，Sheets API 第 4 版提供 spreadsheets.values.update 和 spreadsheets.values.batchUpdate 方法。

第 3 版 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>

第 4 版 API

在 Sheet API 第 4 版中，您可以透過 spreadsheets.values.update 方法編輯單一儲存格。這個方法需要 ValueInputOption 查詢參數，指定輸入資料會視為輸入在試算表 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 會傳回錯誤，在這種情況下不會套用任何更新。

第 3 版 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 的完整路徑。每個項目都必須填寫這些欄位。

第 4 版 API

試算表 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 會傳回錯誤。