スプレッドシートには、セルに含まれる値データ以外にも、次のような多くの種類のデータが含まれます。
- ディメンション
- セルの形式と枠線
- 名前付き範囲
- 保護されている範囲
- 条件付き書式
これらは、スプレッドシートの外観と操作を制御する多くの種類のデータの一部です。spreadsheets.batchUpdate
メソッドを使用すると、これらのスプレッドシートの詳細を更新できます。変更はバッチにグループ化されるため、1 つのリクエストが失敗した場合、他の(依存している可能性のある)変更は書き込まれません。
このページでは、spreadsheets.batchUpdate
メソッドの基本的な使い方について説明します。セル値データの読み取りと書き込みが必要な場合は、セル値の読み取りと書き込みで説明されている spreadsheets.values
リソースも使用できます。
オペレーションのカテゴリ
spreadsheets.batchUpdate
でサポートされている特定のオペレーションは、次の大きなカテゴリに分類できます。
カテゴリ | 説明 |
---|---|
[Add](および [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
変数を使用して、スプレッドシート内のセル値を検出して置換します。