除了儲存格中的值資料外,試算表還包含許多其他類型的資料,例如:
- 尺寸
- 儲存格格式和框線
- 已命名範圍
- 受保護的範圍
- 條件式格式設定
控制試算表的外觀和作業的多種資料類型。spreadsheets.batchUpdate
方法可讓您更新任何這些試算表詳細資料。系統會將變更分組為批次,因此若其中一個要求失敗,系統就不會寫入任何其他 (可能依附) 的變更。
本頁說明使用 spreadsheets.batchUpdate
方法的基本概念。如果需要讀取及寫入儲存格值資料,您也可以使用讀取及寫入儲存格值中所述的 spreadsheets.values
資源。
作業類別
spreadsheets.batchUpdate
支援的特定作業可分為以下廣泛類別:
類別 | 說明 |
---|---|
新增 (並「複製」) | 新增物件 (有時以舊物件為基礎,就像重複要求一樣)。 |
更新 (和 Set) | 更新物件的特定屬性,通常保留舊屬性 (而 Set 要求會覆寫先前的資料)。 |
刪除 | 移除物件。 |
下一節會使用這些類別來說明特定作業的行為。
批次更新作業
spreadsheets.batchUpdate
方法的運作方式是採用一或多個 Request 物件,每個物件都指定要執行單一要求種類。要求種類有很多種以下為不同類別的要求類型細分資料。
此外,還有一些會模擬使用者動作用以操控資料的要求:
- AutoFillRequest
- CutPasteRequest
- CopyPasteRequest
- FindReplaceRequest
- PasteDataRequest
- TextToColumnsRequest
- SortRangeRequest
限制
如要進一步瞭解 Google 試算表的儲存格與資料列限制,請參閱「可存放在 Google 雲端硬碟的檔案」一文。
欄位遮罩
許多「更新」要求都需要欄位遮罩。這些是以半形逗號分隔的欄位清單,僅更新物件中的特定欄位,其他欄位則維持不變。*
的欄位遮罩就像萬用字元,是指定訊息中所有欄位的簡寫 (如果未在要求中指定欄位值,欄位可能會還原為預設狀態)。如要進一步瞭解欄位遮罩,請參閱「使用欄位遮罩」一文。
以下範例使用 UpdateSpreadsheetPropertiesRequest
只更新試算表的標題:
要求:
POST .../v4/spreadsheets/spreadsheetId:batchUpdate
要求主體:
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}
以試算表的新標題取代 TITLE。
回應
更新試算表時,某些要求可能會傳回回應。這些引數會以陣列傳回,且每個回應都佔用與對應要求相同的索引。有些要求沒有回應,而這些要求為空白。
一般來說,「新增」要求包含會傳回資訊的回應,例如新增物件的 ID。如需支援回應的清單,請參閱「回應」。
範例
以下程式碼範例會執行這些動作:
- 使用
title
變數更新試算表的標題。 - 使用
find
和replacement
變數尋找並取代試算表中的儲存格值。