除了儲存格內含的值資料外,試算表還包含許多其他類型的資料,例如:
- 尺寸
- 儲存格格式和框線
- 已命名範圍
- 受保護的範圍
- 條件式格式設定
這些只是眾多資料類型中的一小部分,可用於控制試算表的外觀和運作方式。spreadsheets.batchUpdate
方法可讓您更新任何試算表詳細資料。變更會分批處理,因此如果其中一項要求失敗,系統就不會寫入其他 (可能相依的) 變更。
本頁面說明如何使用 spreadsheets.batchUpdate
方法的基本概念。如要讀取及寫入儲存格值資料,也可以使用「讀取及寫入儲存格值」一文所述的 spreadsheets.values
資源。
作業類別
spreadsheets.batchUpdate
支援的特定作業可歸類為下列幾種:
類別 | 說明 |
---|---|
新增 (和複製) | 新增物件 (有時會以舊物件為基礎,如複製要求)。 |
更新 (和設定) | 更新物件的特定屬性,通常會保留舊屬性 (而 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
變數,在試算表中尋找並取代儲存格值。