このドキュメントでは、spreadsheets リソースで spreadsheets.batchUpdate メソッドを使用する基本的な方法について説明します。
スプレッドシートには、セルに含まれる値データ以外にも、次のようなさまざまな種類のデータが含まれています。
- サイズ
- セルの形式と枠線
- 名前付き範囲
- 保護されている範囲
- 条件付き書式
スプレッドシートの表示と動作を制御するデータには、さまざまな種類があります。spreadsheets.batchUpdate メソッドを使用すると、これらのスプレッドシートの詳細を更新できます。変更はバッチでグループ化されるため、1 つのリクエストが失敗した場合、他の(依存関係がある可能性のある)変更は書き込まれません。
セル値データを読み書きする必要がある場合は、セル値の読み取りと書き込みで説明されているように、spreadsheets.values リソースを使用することもできます。
オペレーション タイプ
spreadsheets.batchUpdate メソッドでサポートされている特定のオペレーションは、次の大まかなオペレーション タイプに分類できます。
| カテゴリ | 説明 |
|---|---|
| 追加(および複製) | 新しいオブジェクトを追加します(重複リクエストのように、古いオブジェクトに基づくこともあります)。 |
| 更新(および設定) | オブジェクトの特定のプロパティを更新します。通常、古いプロパティはそのまま残します(Set リクエストは以前のデータを上書きします)。 |
| 削除 | オブジェクトを削除する。 |
これらのカテゴリは、次のセクションで特定のオペレーションの動作を説明するために使用されます。
バッチ アップデート オペレーション
spreadsheets.batchUpdate メソッドは、1 つ以上の Request オブジェクトを受け取って動作します。各オブジェクトは、実行するリクエストの単一の種類を指定します。次の表に、バッチ アップデート リクエストのタイプをリソース オブジェクトとオペレーション タイプ別に示します。
データ操作リクエスト
データを操作するユーザー アクションを模倣する追加のリクエストもあります。
| リクエスト | 説明 |
|---|---|
AutoFillRequest |
既存のデータに基づいて、より多くのデータを自動的に入力します。 |
CopyPasteRequest |
ある領域からデータをコピーして別の領域に貼り付けます。 |
CutPasteRequest |
ある領域のデータを切り取って別の領域に貼り付けます。 |
DeleteDuplicatesRequest |
セル範囲の指定された列に重複した値を含む行を削除します。 |
FindReplaceRequest |
テキストを検索して、別のテキストに置き換えます。 |
PasteDataRequest |
データをシートに貼り付けます(HTML または区切り文字)。 |
RandomizeRangeRequest |
範囲内の行の順序をランダム化します。 |
SortRangeRequest |
範囲内のデータを並べ替えます。 |
TextToColumnsRequest |
テキストの列を複数のテキストの列に変換します。 |
TrimWhitespaceRequest |
セルから空白文字(スペース、タブ、改行など)を削除します。 |
Google スプレッドシートのセル数と行数の上限について詳しくは、Google ドライブに保管可能なファイルをご覧ください。
フィールド マスクを使用して特定のフィールドを更新する
多くの更新リクエストには FieldMask が必要です。フィールド マスクは、オブジェクト内のどのフィールドを更新し、他のすべてのフィールドを変更しないままにするかを示すために使用されるフィールドのカンマ区切りリストです。フィールド マスクを使用すると、リクエストで指定されていないフィールドが誤って上書きされるのを防ぐことができます。
フィールド マスクの詳細については、フィールド マスクを使用して更新するをご覧ください。
次のコードサンプルは、UpdateSpreadsheetPropertiesRequest を使用してスプレッドシートのタイトルのみを更新する方法を示しています。
リクエスト
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
リクエストの本文
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}TITLE は、スプレッドシートの新しいタイトルに置き換えます。
バッチ アップデート レスポンス
スプレッドシートを更新する際、一部のリクエストはレスポンスを返すことがあります。これらは配列で返され、各レスポンスは対応するリクエストと同じインデックスを占有します。リクエストによってはレスポンスがないものもあり、その場合はレスポンスが空になります。
通常、「追加」リクエストには、追加されたオブジェクトの ID などの情報を返すレスポンスがあります。サポートされているレスポンスの一覧については、Responses をご覧ください。
コードサンプル: スプレッドシートをバッチ アップデートする
次のコードサンプルは、これらのアクションを実行する方法を示しています。
title変数を使用してスプレッドシートのタイトルを更新します。find変数とreplacement変数を使用して、スプレッドシート内のセル値を検索して置換します。