バッチ リクエスト

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

概要

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

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

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

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

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

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

バッチ リクエストの詳細

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

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

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

このアプローチでは、1 つの API バッチ更新リクエストと複数のサブリクエストを使用して、Google ドキュメント全体を構築できます。

バッチ リクエストの形式

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

バッチ レスポンスの形式

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

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

次の例は、Docs API によるバッチ処理の使用例です。

リクエスト

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

  • InsertTextRequest を使用して、インデックス Location を 1 として既存のドキュメントの先頭に「Hello World」というテキストを挿入します。
  • UpdateTextStyleRequest を使用して「Hello」という単語を更新します。startIndexendIndex は、セグメント内の書式設定されたテキストの range を定義します。
  • textStyle を使用して、フォント スタイルを太字に、色を青色に設定します。
{
   "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"
         }
      }
   ]
}

レスポンス

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

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