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

バッチリクエスト

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

概要

クライアントで接続を行うたびに、ある程度のオーバーヘッドが発生します。Google Docs API では、クライアントが複数のリクエストオブジェクト（実行するリクエストの種類を 1 つ指定）を 1 つのバッチリクエストに配置できるように、バッチ処理がサポートされています。バッチリクエストでは、複数のサブリクエストをサーバーへの 1 回の呼び出しに結合し、レスポンスを 1 つ取得することで、パフォーマンスを向上できます。

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

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

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

バッチ更新を採用する際に考慮すべきその他の項目は次のとおりです。

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

バッチリクエストの詳細

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

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

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

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

バッチリクエストの形式

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

バッチレスポンスの形式

バッチリクエストのレスポンス形式は、リクエスト形式と同様です。サーバーのレスポンスには、単一のレスポンスオブジェクトの完全な返信が含まれます。

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

例

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

リクエスト

このバッチリクエストの例では、次の処理を行います。

InsertTextRequest を使用して、インデックス location が 1 の既存のドキュメントの先頭に「Hello World」というテキストを挿入します。
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`
}

おすすめの方法

バッチ リクエスト

概要

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

バッチ リクエストの詳細

バッチ リクエストの形式

バッチ レスポンスの形式

例