このドキュメントでは、複数の API 呼び出しをバッチ処理して、 クライアントが確立する必要がある接続の数です。バッチ処理では、アプリケーションの ネットワークのラウンドトリップを減らして スループットを向上できます
概要
クライアントで接続を行うたびに、ある程度のオーバーヘッドが発生します。 Google Sheets API はバッチ処理をサポートしており、これによりクライアントは複数の リクエスト オブジェクト。各オブジェクトは、実行するリクエストの種類を 1 つ指定し、 単一のバッチ リクエストにまとめることができます。バッチ リクエストは次の処理によってパフォーマンスを向上させます。 複数のサブリクエストをサーバーへの 1 回の呼び出しにまとめ、 返すことができます
常に複数のリクエストをバッチ処理することをおすすめします。以下に例を示します。 バッチ処理を使用できる状況の例:
- API を使い始めたばかりで、アップロードするデータが大量にあります。
- メタデータや、フォーマットなどのプロパティを複数の 説明します。
- 多くのオブジェクトを削除する必要がある。
制限、承認、依存関係に関する考慮事項
バッチ更新を採用する際に考慮すべきその他の項目は次のとおりです。
- 各バッチ リクエスト(すべてのサブリクエストを含む)は、1 つの API としてカウントされます。 使用量上限に対するリクエスト。
- バッチ リクエストは 1 回認証されます。この単一の認証が リクエスト内のすべてのバッチ アップデート オブジェクトに保持されます。
- サーバーは、サブリクエストを 使用します。後のサブリクエストは、セッション中に実行されたアクションに依存する 以前のサブリクエストを実行します。たとえば、同じバッチ リクエストで、 既存のドキュメントにテキストを挿入してスタイルを設定する。
バッチ リクエストの詳細
バッチ リクエストは 1 回の batchUpdate
メソッド呼び出しで構成されます。
スプレッドシートの追加や書式設定など、複数のサブリクエストを持つことができます。
各リクエストは、適用前に検証されます。バッチ内のすべてのサブリクエスト アトミックに適用されます。つまり、いずれかのリクエストが有効でない場合、 アップデート全体が失敗し、アップデートに 適用されます。
一部のリクエストでは、適用されたリクエストに関する情報がレスポンスとして返されます。 たとえば、オブジェクトを追加するすべてのバッチ アップデート リクエストはレスポンスを返すので、 新しく追加されたオブジェクトのメタデータ(ID や できます。
このアプローチでは、1 つの API で Google ドキュメント全体を作成できます。 複数のサブリクエストを含むバッチ アップデート リクエストを作成できます。
バッチ リクエストの形式
リクエストは、単一の JSON リクエストで、
1 つの必須プロパティ requests
を持つネストされたサブリクエスト。「
個々のリクエストの配列として構成されます。各リクエストで使用する
リクエスト オブジェクトを表し、そのプロパティを格納する JSON。
バッチ レスポンスの形式
バッチ リクエストのレスポンス形式は、 リクエスト形式に従って処理します。サーバーのレスポンスには、リクエストに対する 1 つの レスポンス オブジェクト。
メインの JSON オブジェクトのプロパティは replies
という名前です。回答
は配列として返され、各リクエストに対する各レスポンスは
対応するリクエストと同じインデックス順序になります。一部のリクエストには、
その配列インデックスのレスポンスが空になります。
例
次の例は、Sheets API でのバッチ処理の使用方法を示しています。
リクエスト
このバッチ リクエストの例では、次の処理を行います。
AddSheetRequest
を使用して、sheetId
が 12345 の既存のスプレッドシートにシートを追加します。UpdateCellsRequest
を使用して、セル A1 から始まるデータを新しいシートに追加します。- 新しいシートに
namedRange
またはフィルタ表示を追加します。
リクエストにシート ID を追加すると、ユーザーは同じ API 呼び出しの他のサブリクエストのシート ID を使用できます。これにより、書き込み / 読み取り / 書き込みのサイクルが回避されるため、パフォーマンスが向上します。
さまざまなカテゴリに分類されたバッチ アップデート リクエストの種類の一覧については、バッチ アップデート オペレーションの表をご覧ください。
{ "requests":[ { "addSheet":{ "properties":{ "sheetId":123456 } } }, { "updateCells":{ "start":{ "sheetId":123456 }, "rows":[ { "values":[ { "userEnteredValue":{ "stringValue":"hello" } } ] }, { "values":[ { "userEnteredValue":{ "stringValue":"world" } } ] } ], "fields":"userEnteredValue" } }, { "addNamedRange":{ "namedRange":{ "name":"newRange", "range":{ "sheetId":123456, "endRowIndex":2 } } } } ] }
レスポンス
この例のバッチ レスポンスは、バッチ リクエスト内の各サブリクエストがどのように適用されたかに関する情報を示しています。UpdateCellsRequest
にはレスポンスが含まれていないため、配列 [1] のインデックス値は空の中かっこで囲まれています。
"replies":[ { "addSheet":{ "properties":{ "sheetId":123456, "title":"Sheet3", "index":2, "sheetType":"GRID", "gridProperties":{ "rowCount":1000, "columnCount":26 } } } }, { }, { "addNamedRange":{ "namedRange":{ "namedRangeId":"2104325079", "name":"newRange", "range":{ "sheetId":123456, "startRowIndex":0, "endRowIndex":2, "startColumnIndex":0, "endColumnIndex":26 } } } } ]