除了所含儲存格的值資料以外,試算表還包含許多其他類型的資料,例如:
- 尺寸
- 儲存格格式和框線
- 已命名範圍
- 受保護的範圍
- 條件式格式設定
以上是控制試算表外觀和作業的眾多資料。spreadsheets.batchUpdate
方法可讓您更新任何試算表詳細資料。變更會按批次分組,因此如果一個要求失敗,系統就不會寫入任何其他 (可能相依) 的變更。
本頁說明使用 spreadsheets.batchUpdate
方法的基本概念。如果您需要讀取及寫入儲存格值資料,也可以使用「讀取及寫入儲存格值」一文所述的 spreadsheets.values
資源。
作業類別
spreadsheets.batchUpdate
支援的特定作業可分組為以下廣泛類別:
類別 | 說明 |
---|---|
Add (和 Duplicate) | 新增物件 (或以舊物件為基礎,例如「重複要求」)。 |
Update (和「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
變數尋找並取代試算表中的儲存格值。