バッチ リクエスト

ここでは、複数の API 呼び出しを一括して行い、クライアント側の HTTP 接続の回数を減らす方法について説明します。バッチ処理を行うと、ネットワークのラウンド トリップを減らし、スループットを増やすことで、アプリケーションの効率を高めることができます。

概要

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

複数のリクエストは常にバッチで処理することをおすすめします。バッチ処理を使用できる状況の例をいくつか示します。

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

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

バッチ アップデートを使用する際に考慮すべきその他の項目は次のとおりです。

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

バッチ リクエストの詳細

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

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

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

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

バッチ リクエストの形式

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

バッチ レスポンスの形式

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

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

例

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

リクエスト

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

  • InsertTextRequest を使用して、既存のドキュメントの先頭に「Hello World」というテキストを挿入します。インデックス location は 1 です。

  • UpdateTextStyleRequest を使用して「Hello」という単語を更新します。startIndex と endIndex は、セグメント内の書式設定されたテキストの range を定義します。

  • textStyle を使用して、「Hello」という単語のフォントのスタイルを太字に、色を青に設定します。

  • WriteControl フィールドを使用すると、書き込みリクエストの実行方法を制御できます。詳細については、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`
}