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

バッチリクエスト

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

概要

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

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

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

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

バッチ更新を使用する際に考慮すべきその他の項目を以下に示します。

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

バッチリクエストの詳細

バッチリクエストは、複数のサブリクエストを含む 1 つの batchUpdate メソッド呼び出しで構成されます。たとえば、プレゼンテーションを追加してからフォーマットします。

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

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

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

バッチリクエストの形式

リクエストは、複数のネストされたサブリクエストを含む単一の JSON リクエストです。必須のプロパティは 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
   }
}

バッチ リクエスト コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要