このドキュメントでは、複数の 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 } }