バッチ リクエスト

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

概要

クライアントが確立する各接続には、ある程度のオーバーヘッドが発生します。Google ドキュメント API はバッチ処理をサポートしているため、クライアントは複数のリクエスト オブジェクト（それぞれが実行する単一タイプのリクエストを指定）を 1 つのバッチ リクエストに配置できます。バッチ リクエストを使用すると、複数のサブ リクエストを 1 回のサーバー呼び出しに結合し、1 回のレスポンスを取得することで、パフォーマンスを向上させることができます。

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

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

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

バッチ更新を使用する際に考慮すべきその他の項目を以下に示します。

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

バッチ リクエストの詳細

バッチ リクエストは、複数のサブ リクエストを含む 1 つの batchUpdate メソッド呼び出しで構成されます。たとえば、ドキュメントを追加してからフォーマットします。

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

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

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

バッチ リクエストの形式

リクエストは、複数のネストされたサブリクエストを含む単一の JSON リクエストです。必須のプロパティは 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,
               "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`
}