このページは Cloud Translation API によって翻訳されました。

バッチリクエスト

このドキュメントでは、複数の API 呼び出しをバッチ処理して、クライアントからの接続数を減らす方法について説明します。バッチ処理を行うことで、ネットワークのラウンドトリップを減らし、スループットを向上させることで、アプリケーションの効率を改善できます。

概要

クライアントによる接続ごとに、ある程度のオーバーヘッドが発生します。Google ドキュメント API ではバッチ処理がサポートされており、クライアントで複数のリクエストオブジェクトを 1 つのバッチリクエストにまとめることができます。バッチリクエストでは、複数のサブリクエストをサーバーへの 1 回の呼び出しに結合して単一のレスポンスを取得することで、パフォーマンスを向上できます。

常に複数のリクエストをバッチ処理することをおすすめします。バッチ処理は次のような状況で使用できます。

API を使い始めたばかりで、アップロードするデータが大量にあります。
複数のオブジェクトのメタデータやプロパティ（書式設定など）を更新する必要がある場合。
多数のオブジェクトを削除する必要があります。

制限、認可、依存関係に関する考慮事項

一括更新を採用する際に考慮すべきその他の項目を次に示します。

すべてのサブリクエストを含む各バッチリクエストは、使用量上限に対して 1 つの API リクエストとしてカウントされます。
バッチリクエストは 1 回認証されます。この 1 回の認証は、リクエスト内のすべてのバッチアップデートオブジェクトに適用されます。
サーバーは、バッチリクエストに表示されているのと同じ順序でサブリクエストを処理します。後のサブリクエストは、前のサブリクエスト中に実行されたアクションによって異なる場合があります。たとえば、同じバッチリクエストでは、既存のドキュメントにテキストを挿入してからスタイルを設定できます。

バッチリクエストの詳細

バッチリクエストは、1 つの batchUpdate メソッド呼び出しと複数のサブリクエスト（ドキュメントの追加と書式設定など）で構成されます。

各リクエストは適用前に検証されます。バッチアップデート内のすべてのサブリクエストは、アトミックに適用されます。つまり、有効でないリクエストがあると、更新全体が失敗となり、依存する可能性のある変更は適用されません。

一部のリクエストでは、適用されたリクエストに関する情報を含むレスポンスが返されます。たとえば、オブジェクトを追加するすべてのバッチアップデートリクエストではレスポンスが返されます。これにより、新しく追加されたオブジェクトのメタデータ（ID やタイトルなど）にアクセスできます。

この方法では、1 つの API バッチアップデートリクエストで複数のサブリクエストを使用して、Google ドキュメント全体を作成できます。

バッチリクエストの形式

リクエストは、1 つの必須プロパティ requests を持つネストされた複数のサブリクエストを含む単一の JSON リクエストです。リクエストは、個々のリクエストの配列として構成されます。各リクエストは、JSON を使用してリクエストオブジェクトを表し、そのプロパティを格納します。

バッチレスポンスの形式

バッチリクエストのレスポンス形式は、リクエストの形式と類似しています。サーバーのレスポンスには、単一のレスポンスオブジェクトの完全なレスポンスが含まれます。

メインの JSON オブジェクトのプロパティは replies という名前です。レスポンスは配列で返され、1 つのリクエストに対する各レスポンスは、対応するリクエストと同じインデックス順を占有します。一部のリクエストにはレスポンスがなく、その配列インデックスのレスポンスが空になります。

例

次のコードサンプルは、Docs API でバッチ処理を使用する方法を示しています。

リクエスト

このバッチリクエストの例は、次の方法を示しています。

InsertTextRequest を使用して、既存のドキュメントの先頭に「Hello World」というテキストをインデックス location 1 で挿入します。
UpdateTextStyleRequest を使用して「Hello」という単語を更新します。startIndex と endIndex は、セグメント内の書式設定されたテキストの range を定義します。
textStyle を使用して、「Hello」という単語だけのフォントスタイルを太字に設定し、色を青色に設定します。
WriteControl フィールドを使用すると、書き込みリクエストの実行方法を制御できます。詳細については、WriteControl で状態の整合性を維持するをご覧ください。

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "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"
  }
}

REQUIRED_REVISION_ID は、書き込みリクエストが適用されるドキュメントのリビジョン ID に置き換えます。

レスポンス

次のバッチレスポンスの例には、バッチリクエスト内の各サブリクエストがどのように適用されたかに関する情報が表示されます。InsertTextRequest と UpdateTextStyleRequest のどちらもレスポンスが含まれていないため、[0] と [1] の配列のインデックス値は空の中かっこで構成されます。バッチリクエストには、リクエストの実行方法を示す WriteControl オブジェクトが表示されます。

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}

最良の結果を得るためのベストプラクティス

バッチ リクエスト

概要

制限、認可、依存関係に関する考慮事項

バッチ リクエストの詳細

バッチ リクエストの形式

バッチ レスポンスの形式

例