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

バッチリクエスト

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

概要

クライアントが接続するたびに、一定量のオーバーヘッドが発生します。Google Slides API はバッチ処理をサポートしているため、クライアントは複数のリクエストオブジェクト（それぞれが実行するリクエストの種類を指定）を 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
   }
}

バッチ リクエスト

概要