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

バッチリクエスト

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

概要

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

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

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

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

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

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

バッチリクエストの詳細

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

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

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

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

バッチリクエストの形式

リクエストは、ネストされた複数のサブリクエストを含む単一の JSON リクエストで、1 つの必須プロパティ requests を持ちます。リクエストは、個々のリクエストの配列として構成されます。各リクエストは 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
   }
}

バッチ リクエスト

概要