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

バッチリクエスト

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

概要

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

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

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

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

一括更新を使用する際は、以下の点も考慮してください。

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

バッチリクエストの詳細

バッチリクエストは、1 つの batchUpdate メソッド呼び出しと複数のサブリクエスト（プレゼンテーションの追加と書式設定など）で構成されます。

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

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

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

バッチリクエストの形式

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

バッチレスポンスの形式

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

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

例

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

リクエスト

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

CreateSlideRequest メソッドを使用して、insertionIndex が 1 の presentations.pages リソースを既存のプレゼンテーションに追加します。
CreateShapeRequest メソッドを使用して、TEXT_BOX タイプの shapeType を新しいスライドに追加します。
InsertTextRequest メソッドを使用して、「Hello World」のテキストを新しいフィールドに挿入します。

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

レスポンス

このバッチレスポンスの例には、バッチリクエスト内の各サブリクエストがどのように適用されたかについての情報が表示されます。InsertTextRequest メソッドにはレスポンスが含まれていないため、[2] の配列のインデックス値は空の中かっこで構成されます。バッチリクエストでは、書き込みリクエストの実行状況を示す WriteControl プロパティが表示されます。

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}

バッチ リクエスト

概要