スプレッドシートには、セル内の値データ以外にも、次のようなさまざまな種類のデータが含まれています。
- 表示サイズ
- セルの書式と枠線
- 名前付き範囲
- 保護されている範囲
- 条件付き書式
これらは、スプレッドシートの外観と操作を制御する多くの種類のデータの一部です。spreadsheets.batchUpdate
メソッドを使用すると、これらのスプレッドシートの詳細を更新できます。変更はバッチにグループ化されるため、1 つのリクエストが失敗した場合、他の変更(依存している可能性がある)は書き込まれません。
このページでは、spreadsheets.batchUpdate
メソッドの基本的な使い方について説明します。セル値データの読み取りと書き込みが必要な場合は、セル値の読み取りと書き込みで説明されている spreadsheets.values
リソースを使用することもできます。
オペレーションのカテゴリ
spreadsheets.batchUpdate
でサポートされている特定のオペレーションは、次の大きなカテゴリに分類できます。
カテゴリ | 説明 |
---|---|
Add(および Duplicate) | 新しいオブジェクトを追加します(Duplicate リクエストのように、古いオブジェクトに基づく場合もあります)。 |
Update(および Set) | オブジェクトの特定のプロパティを更新する。通常、古いプロパティはそのまま残す(Set リクエストでは以前のデータが上書きされる)。 |
削除 | オブジェクトを削除する。 |
次のセクションでは、これらのカテゴリを使用して、特定のオペレーションの動作について説明します。
バッチ アップデート オペレーション
spreadsheets.batchUpdate
メソッドは、1 つ以上の Request オブジェクトを受け取ることで機能します。各オブジェクトは、実行するリクエストの種類を 1 つ指定します。さまざまなリクエストがあります。ここでは リクエストの種類をカテゴリ別に
分類しています
他にも、データ操作のユーザー アクションを模倣したリクエストがいくつかあります。
- 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
変数を使用して、スプレッドシート内のセル値を検索して置換します。