從 Sheets API 第 3 版進行遷移

如果現有的應用程式是在 Google Sheets API v3 上部署,可遷移至 Google Sheets API v4。v4 版本以 JSON 為基礎,且更容易使用 並提供大量新功能 。

本頁將為舊版 Sheets API v3 指令和其 功能。製圖主要著重於 spreadsheets.values 收集,可直接讀取及寫入儲存格。 其他設定 (例如新增工作表或更新工作表屬性) 試算表集合。 請注意,v4 API 的 JSON 結構無法與 第 3 版中使用的 XML 結構。

如要進一步瞭解 Sheets v4 API 提供的資源,請參閱 API 參考資料

標記法與條款

第 3 版 API 將特定試算表內的工作表稱為「工作表」。 這相當於「試算表」一詞。與 v4 API 所使用的相同

使用 API 時,通常會要求您指定試算表 ID 開啟試算表此外,這些發布商通常會需要 工作表。這些值會顯示為 API 端點的一部分 網址、查詢參數,或做為要求主體的一部分在這個頁面中, 預留位置 spreadsheetIdsheetId 參照的試算表和工作表 ID。使用方法時 以這些位置的實際編號取代。

第 3 版 API 也會指派 ID 給使用其 清單動態饋給; 這部分會以 rowId 預留位置表示。

授權要求

您的應用程式執行時,會要求使用者授予特定權限。 應用程式中指定的權限會決定其需要的權限。

第 3 版 API

Sheets API v3 只能以單一授權範圍運作:

https://spreadsheets.google.com/feeds

這是 Google Cloud 的別名

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

任一範圍格式可以使用。

第 4 版 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 中,「visibility」一詞是指 以及特定試算表的可用性

第 3 版 API

Sheets API v3 會在其端點直接表示瀏覽權限。public 試算表已設為「發布到網路」因此可由 API 不需授權,但 private 試算表需要 驗證。您可在端點端點 試算表 ID:

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

第 4 版 API

新的 Sheets API v4 版本沒有明確的瀏覽權限宣告, API 呼叫是透過試算表 ID 進行。如果應用程式沒有 存取指定試算表的權限,系統會傳回錯誤。其他情況 呼叫繼續進行。

投影

Sheets API 第 3 版會使用「投影」一詞來指稱一組資料 特定 API 呼叫所傳回的傳回資訊,可以是全部或固定子集 在 API 中定義的Sheets API 第 4 版未使用投影功能。相反地 可讓您進一步控制要傳回哪些資料。

第 3 版 API

Sheets API v3 只提供兩種投影設定。full 投影會傳回所有可用資訊,而 basic 會傳回一個 (適用於工作表、清單和儲存格動態饋給) 的小型資料子集。 就像瀏覽權限一樣,必須在 API 端點中指定投影 (在顯示設定之後):

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

basic 投影所提供的一小部分資料有價值 ,提升程式碼的效率,但無法自訂

第 4 版 API

雖然 Sheets API v4 可傳回完整的資料集,但不會定義固定值 子集類似於 Sheets API v3 的 basic 瀏覽權限設定。 試算表中的方法 收集限制,透過使用 fields 查詢參數。

舉例來說,以下查詢只會傳回所有 幾個工作表:

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

建立試算表

第 3 版 API

Sheets API 第 3 版不提供建立新試算表的方式。 請改用 Drive API Files.create 方法即可建立新試算表檔案。這需要用到 宣告 https://www.googleapis.com/auth/drive 範圍。

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

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

第 3 版 API

Sheets API v3 動態饋給可讓應用程式擷取 已驗證使用者可存取的試算表試算表動態饋給 是:

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

第 4 版 API

Sheets 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 方法,列出使用者的所有試算表 需要受限制的範圍。

擷取工作表中繼資料

Sheets API v3 提供用於存取工作表中繼資料的動態饋給 (可透過瀏覽器存取列與儲存格資料) 個別動態饋給)。中繼資料包括工作表標題和 大小資訊

Sheets 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 方法可用來取得工作表屬性和其他中繼資料 的功能。如果您只有 如要讀取工作表屬性,請設定 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

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>

第 4 版 API

如要新增工作表,請 AddSheet spreadsheets.batchUpdate 中的要求 方法。做為要求主體的一部分,您可以指定 可以在新工作表中操作所有屬性均為選用屬性。提供 現有工作表所使用的標題。

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

如要更新大小、標題和其他工作表屬性, updateSheetProperties 要求 (在 spreadsheets.batchUpdate 方法。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 都可以移除特定試算表中的工作表。

第 3 版 API

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

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

第 4 版 API

如要刪除工作表,請在 DeleteSheet 要求 (在 spreadsheets.batchUpdate 方法。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 也能存取不連貫的儲存格組合。

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

根據預設,清單動態饋給傳回的資料列會依序傳回。 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

第 4 版 API

在 Sheets API v4 中,使用者可以使用 spreadsheets.values.getspreadsheets.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 沒有相應的資料列排序查詢功能 參數。反向排序十分重要;簡單 依序處理傳回的 values 陣列。「依資料欄排序」不是 支援讀取功能,但您仍可以排序工作表中的資料 (使用 SortRange) 讀取資料

Sheets API v4 版目前無法提供與 Sheets 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

在 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 還可讓您附加 屬性和格式設定 AppendCells 要求 spreadsheets.batchUpdate.

編輯包含新資料的資料列

這兩種 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

在 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 還可讓您編輯儲存格屬性,以及 套用儲存格格式設定 UpdateCellsRepeatCell 要求 spreadsheets.batchUpdate.

刪除資料列

這兩種 API 都支援刪除資料列。刪除的列會從 工作表和下方的列就會向上推。

第 3 版 API

如要刪除資料列,請先從 清單動態饋給 然後傳送 DELETE 要求至該列項目提供的 edit 網址。 這就是用於更新資料列的網址。

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

如果想確保沒有刪除已變更的資料列 時,請將 HTTP if-Match 標頭 ,其中包含原始資料列的 ETag 值。您可以決定 檢查該項目元素的 gd:etag 屬性,藉此找出資料列的 ETag 值。

您想要刪除該列 (無論有其他人是否更新) 否則就使用 if-Match: * 且不要加入 ETag。 (在此情況下,您不必擷取該資料列,即可將其刪除)。

第 4 版 API

透過 Sheets API v4 刪除資料列,將由 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
        }
      }
    }
  ],
}

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

擷取儲存格資料

Sheets API v3 版提供儲存格動態饋給,可讓您基本存取儲存於 試算表。為了取得讀取權限,儲存格動態饋給可提供整張工作表 或特定查詢參數定義的工作表儲存格範圍 但只當做單一區塊,因此必須擷取互連範圍 分別使用額外的 GET 要求。

Sheets API v4 可以從工作表擷取任何一組儲存格資料 (包括 多個不連續的範圍)。Sheets API 第 3 版只會傳回以下格式的儲存格內容: 輸入值 (就像使用者在鍵盤中輸入) 和/或 公式 (如果是數字);Sheets API v4 可授予值的完整存取權 公式、格式、超連結、資料驗證和其他屬性。

第 3 版 API

如要判斷特定工作表的儲存格資料動態饋給網址,請檢查 工作表動態饋給 ,在感興趣的工作表項目中找到儲存格資訊提供網址。

如要擷取儲存格式動態饋給,請傳送 GET 要求至儲存格動態饋給網址。 使用適當的授權標頭。例如:

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

可以使用列號和欄號參照儲存格。擷取單一 您可以使用 max-rowmin-rowmax-colmin-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 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.getspreadsheets.values.batchGet 方法。舉例來說, 後面會傳回「Sheet2」欄 D 中的儲存格 (從第 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 方法。

編輯儲存格

Sheets API 第 3 版發出 PUT 指令,即可編輯儲存格內容, 儲存格動態饋給和已修改的儲存格項目做為要求主體。

相較之下,Sheets API 第 4 版則提供 spreadsheets.values.updatespreadsheets.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

在 Sheets 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 程式庫。

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

這兩種 API 都能讓您變更多個儲存格的內容。 使用單一 (批次) 要求傳送批次要求所參照的儲存格如下: 不需要在連續範圍內

如果批次中一或多個儲存格編輯作業失敗,Sheet 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」欄位應為 updategs:cell 依據列和欄編號識別儲存格,並提供新的資料 插入文字id 包含要更新儲存格的完整網址。 linkhref 屬性必須包含 儲存格 ID每個項目都必須填寫上述所有欄位。

第 4 版 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 會傳回錯誤。