このドキュメントでは、複数の API 呼び出しをバッチ処理して、 クライアントが確立する必要がある接続の数です。バッチ処理では、アプリケーションの ネットワークのラウンドトリップを減らして スループットを向上できます
概要
クライアントで接続を行うたびに、ある程度のオーバーヘッドが発生します。 Google Docs API ではバッチ処理がサポートされており、クライアントが複数の リクエスト オブジェクト。各オブジェクトは、実行するリクエストの種類を 1 つ指定し、 単一のバッチ リクエストにまとめることができます。バッチ リクエストは次の処理によってパフォーマンスを向上させます。 複数のサブリクエストをサーバーへの 1 回の呼び出しにまとめ、 返すことができます
常に複数のリクエストをバッチ処理することをおすすめします。以下に例を示します。 バッチ処理を使用できる状況の例:
- API を使い始めたばかりで、アップロードするデータが大量にあります。
- メタデータや、フォーマットなどのプロパティを複数の 説明します。
- 多くのオブジェクトを削除する必要がある。
制限、承認、依存関係に関する考慮事項
バッチ更新を採用する際に考慮すべきその他の項目は次のとおりです。
- 各バッチ リクエスト(すべてのサブリクエストを含む)は、1 つの API としてカウントされます。 使用量上限に対するリクエスト。
- バッチ リクエストは 1 回認証されます。この単一の認証が リクエスト内のすべてのバッチ アップデート オブジェクトに対して適用されます。
- サーバーは、サブリクエストを 使用します。後のサブリクエストは、セッション中に実行されたアクションに依存する 以前のサブリクエストを実行します。たとえば、同じバッチ リクエストで、 既存のドキュメントにテキストを挿入してスタイルを設定する。
バッチ リクエストの詳細
バッチ リクエストは 1 回の batchUpdate
メソッド呼び出しで構成されます。
ドキュメントの追加や書式設定など、複数のサブリクエストを持つことができます。
各リクエストは、適用前に検証されます。バッチ内のすべてのサブリクエスト アトミックに適用されます。つまり、いずれかのリクエストが有効でない場合、 アップデート全体が失敗し、アップデートに 適用されます。
一部のリクエストでは、適用されたリクエストに関する情報がレスポンスとして返されます。 たとえば、オブジェクトを追加するすべてのバッチ アップデート リクエストはレスポンスを返すので、 新しく追加されたオブジェクトのメタデータ(ID や できます。
このアプローチでは、1 つの API で Google ドキュメント全体を作成できます。 バッチ アップデート リクエストを実行できます。
バッチ リクエストの形式
リクエストは、単一の JSON リクエストで、
1 つの必須プロパティ requests
を持つネストされたサブリクエスト。「
個々のリクエストの配列として構成されます。各リクエストで使用する
リクエスト オブジェクトを表し、そのプロパティを格納する JSON。
バッチ レスポンスの形式
バッチ リクエストのレスポンス形式は、 リクエスト形式に従って処理します。サーバーのレスポンスには、リクエストに対する 1 つの レスポンス オブジェクト。
メインの JSON オブジェクトのプロパティは replies
という名前です。回答
は配列として返され、各リクエストに対する各レスポンスは
対応するリクエストと同じインデックス順序になります。一部のリクエストには、
その配列インデックスのレスポンスが空になります。
例
次のコードサンプルは、Docs API でのバッチ処理の使用を示しています。
リクエスト
このバッチ リクエストの例では、次の処理を行います。
「Hello World」と挿入する既存のドキュメントの先頭に、 インデックス
location
/1
、InsertTextRequest
。「Hello」という単語を更新します。使用
UpdateTextStyleRequest
。startIndex
とendIndex
は、フォーマットされたテキストのrange
を定義します。 選択しますtextStyle
を使用して、フォント スタイルを太字に、色を青に設定します。 応答します。WriteControl
の使用 フィールドを使用して、書き込みリクエストの実行方法を制御できます。詳細 詳細については、Terraform を使用した状態の整合性の確立、 WriteControl.
{ "requests":[ { "insertText":{ "location":{ "index":1, "tabId":TAB_ID }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
TAB_ID と REQUIRED_REVISION_ID を次に置き換えます。 書き込みリクエストが送信されたドキュメントのタブ ID とリビジョン ID 適用されます。
レスポンス
この例のバッチ レスポンスは、各サブリクエストがどのように
適用されました。また、
InsertTextRequest
または
UpdateTextStyleRequest
配列のインデックス値 [0] と [1] は
使用できます。バッチ リクエストには WriteControl
オブジェクトが表示されます。
リクエストがどのように実行されたかを示します。
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }