バッチ リクエスト

このドキュメントでは、複数の API 呼び出しをバッチ処理して、 クライアントが確立する必要がある接続の数です。バッチ処理を行うと、ネットワークのラウンド トリップを減らし、スループットを増やすことで、アプリケーションの効率を高めることができます。

概要

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

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

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

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

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

  • 各バッチ リクエスト(すべてのサブリクエストを含む)は、1 つの API としてカウントされます。 使用量上限に対するリクエスト。
  • バッチ リクエストは 1 回認証されます。この単一の認証が リクエスト内のすべてのバッチ アップデート オブジェクトに保持されます。
  • サーバーは、サブリクエストを 使用します。後のサブリクエストは、セッション中に実行されたアクションに依存する 以前のサブリクエストを実行します。たとえば、同じバッチ リクエストで、 既存のドキュメントにテキストを挿入してスタイルを設定する。

バッチ リクエストの詳細

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

各リクエストは、適用前に検証されます。バッチ内のすべてのサブリクエスト アトミックに適用されます。つまり、いずれかのリクエストが有効でない場合、 更新全体が失敗し、更新中にすべての依存関係(潜在的に 適用されます。

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

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

バッチ リクエストの形式

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

バッチ レスポンスの形式

バッチ リクエストのレスポンス形式は、 リクエスト形式に従って処理します。サーバーのレスポンスには、リクエストに対する 1 つの レスポンス オブジェクト。

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

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

リクエスト

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

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

  • 「Hello」という単語を更新します。使用 UpdateTextStyleRequeststartIndexendIndex は、フォーマットされたテキストの range を定義します。 選択します

  • textStyle を使用して、フォント スタイルを太字に、色を青に設定します。 応答します。

  • WriteControl の使用 フィールドを使用して、書き込みリクエストの実行方法を制御できます。詳細情報 詳細については、Terraform を使用した状態の整合性の確立、 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_IDREQUIRED_REVISION_ID を以下に置き換えます。 書き込みリクエストが送信されたドキュメントのタブ ID とリビジョン ID 適用されます。

レスポンス

この例のバッチ レスポンスは、各サブリクエストがどのように 適用されました。また、 InsertTextRequest または UpdateTextStyleRequest 配列のインデックス値 [0] と [1] は 使用できます。バッチ リクエストには WriteControl オブジェクトが表示されます。 リクエストがどのように実行されたかを示します。

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