バッチ リクエスト
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
このドキュメントでは、複数の API 呼び出しを一括して行い、クライアント側の接続の回数を減らす方法について説明します。バッチ処理により、ネットワークの往復回数を減らし、スループットを増やすことで、アプリケーションの効率を向上させることができます。
概要
クライアントが確立する各接続には、ある程度のオーバーヘッドが発生します。Google スライド API はバッチ処理をサポートしています。これにより、クライアントは複数のリクエスト オブジェクト（それぞれが実行する単一タイプのリクエストを指定）を 1 つのバッチ リクエストに配置できます。バッチ リクエストを使用すると、複数のサブ リクエストを 1 回のサーバー呼び出しに結合し、1 回のレスポンスを取得することで、パフォーマンスを向上させることができます。
複数のリクエストを常にまとめてバッチ処理することをおすすめします。バッチ処理を使用できる状況の例を以下に示します。
-
API の使用を開始したばかりで、アップロードするデータが大量にある。
-
複数のオブジェクトのメタデータやプロパティ（書式設定など）を更新する必要がある。
- 多くのオブジェクトを削除する必要がある。
上限、承認、依存関係に関する考慮事項
バッチ更新を使用する際に考慮すべきその他の項目を以下に示します。
-
すべてのサブ リクエストを含む各バッチ リクエストは、使用量上限に対して 1 つの API リクエストとしてカウントされます。
-
バッチ リクエストは 1 回認証されます。この単一の認証は、リクエスト内のすべてのバッチ更新オブジェクトに適用されます。
-
サーバーは、バッチ リクエストに表示されている順序でサブ リクエストを処理します。後者のサブリクエストは、前のサブリクエストで実行されたアクションに依存する場合があります。たとえば、同じバッチ リクエストで、既存のドキュメントにテキストを挿入してスタイルを設定できます。
バッチ リクエストの詳細
バッチ リクエストは、複数のサブ リクエストを含む 1 つの batchUpdate メソッド呼び出しで構成されます。たとえば、プレゼンテーションを追加してからフォーマットします。
各リクエストは、適用される前に検証されます。バッチ更新内のすべてのサブ リクエストはアトミックに適用されます。つまり、リクエストが無効な場合、更新全体が失敗し、（依存関係がある可能性のある）変更は適用されません。
リクエストによっては、適用されたリクエストに関する情報を含むレスポンスが返されます。たとえば、オブジェクトを追加するすべてのバッチ更新リクエストはレスポンスを返すため、ID やタイトルなど、新しく追加されたオブジェクトのメタデータにアクセスできます。
この方法では、複数のサブ リクエストを含む 1 つの API バッチ更新リクエストを使用して、Google ドキュメント全体を作成できます。
リクエストは、複数のネストされたサブリクエストを含む単一の JSON リクエストです。必須のプロパティは requests です。リクエストは、個々のリクエストの配列で構築されます。各リクエストは、JSON を使用してリクエスト オブジェクトを表し、そのプロパティを含みます。
バッチ リクエストのレスポンスの形式は、リクエストの形式と似ています。サーバーのレスポンスには、単一のレスポンス オブジェクトの完全な返信が含まれます。
メインの JSON オブジェクトのプロパティの名前は replies です。レスポンスは配列で返されます。各リクエストに対するレスポンスは、対応するリクエストと同じインデックス順で配置されます。リクエストによってはレスポンスがないものもあり、その配列インデックスのレスポンスは空になります。
例
次のコードサンプルは、Slides API でのバッチ処理の使用を示しています。
リクエスト
このバッチ リクエストの例は、次の方法を示しています。
{
"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
}
}
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-08-29 UTC。
[null,null,["最終更新日 2025-08-29 UTC。"],[],[],null,["# Batch requests\n\nThis document shows how to batch API calls together to reduce the number of\nconnections your client has to make. Batching can improve an application's\nefficiency by decreasing network round trips and increasing throughput.\n\nOverview\n--------\n\n\nEach connection your client makes results in a certain amount of overhead.\nThe Google Slides API supports batching to let your client place multiple\nrequest objects, each one specifying a single type of request to perform,\ninto a single batch request. A batch request can boost performance by\ncombining multiple subrequests into a single call to the server, retrieving\na single response back.\n\n\nWe encourage users to always batch multiple requests together. Here are some\nexamples of situations where you can use batching:\n\n- You've just started using the API and you have lots of data to upload.\n- You need to update metadata or properties, such as formatting, on multiple objects.\n- You need to delete many objects.\n\nLimits, authorization, \\& dependency considerations\n---------------------------------------------------\n\nHere's a list of other items to consider when employing batch updating:\n\n- Each batch request, including all subrequests, is counted as one API request toward your [usage limit](/workspace/slides/api/limits).\n- A batch request is authenticated once. This single authentication applies to all batch update objects in the request.\n- The server processes the subrequests in the same order they appear in the batch request. Latter subrequests can depend on actions taken during earlier subrequests. For example, in the same batch request, users can insert text into an existing document and then style it.\n\nBatch details\n-------------\n\n\nA batch request consists of one [batchUpdate](/workspace/slides/api/reference/rest/v1/presentations/batchUpdate) method call\nwith multiple subrequests to, for example, add and then format a presentation.\n\n\nEach request is validated before being applied. All subrequests in the batch\nupdate are applied atomically. That is, if any request is not valid then the\nentire update is unsuccessful and none of the (potentially dependent)\nchanges are applied.\n\n\nSome requests provide responses with information about the applied requests.\nFor example, all batch update requests to add objects return responses so\nyou can access the metadata of the newly added object, such as the ID or\ntitle.\n\n\nWith this approach, you can build an entire Google document using one API\nbatch update request with multiple subrequests.\n\n### Format of a batch request\n\n\nA [request](/workspace/slides/api/reference/rest/v1/presentations/request) is a single JSON request containing multiple,\nnested subrequests with one required property: `requests`. The\nrequests are constructed in an array of individual requests. Each request uses\nJSON to represent the request object and to contain its properties.\n\n### Format of a batch response\n\n\nThe [response](/workspace/slides/api/reference/rest/v1/presentations/response) format for a batch request is similar to the\nrequest format. The server's response contains a complete reply of the single\nresponse object.\n\n\nThe main JSON object's property is named `replies`. The responses\nare returned in an array, with each response to one of the requests occupying\nthe same index order as the corresponding request. Some requests don't have\nresponses and the response at that array index is empty.\n\nExample\n-------\n\nThe following code sample shows the use of batching with the\nSlides API.\n\n### Request\n\nThis example batch request demonstrates how to:\n\n- Add a\n [`presentations.pages`](/workspace/slides/api/reference/rest/v1/presentations.pages)\n resource to an existing presentation, with an `insertionIndex` of `1`, using\n the\n [`CreateSlideRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#createsliderequest)\n method.\n\n- Add a `shapeType` of type `TEXT_BOX` to the new slide using the\n [`CreateShapeRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#createshaperequest)\n method.\n\n- Insert \"Hello World\" text into the new field using the\n [`InsertTextRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#inserttextrequest)\n method.\n\n```scdoc\n{\n \"requests\":[\n {\n \"createSlide\":{\n \"insertionIndex\":1,\n \"objectId\":\"newSlide\"\n }\n },\n {\n \"createShape\":{\n \"elementProperties\":{\n \"pageObjectId\":\"newSlide\",\n \"size\":{\n \"height\":{\n \"magnitude\":50,\n \"unit\":\"PT\"\n },\n \"width\":{\n \"magnitude\":200,\n \"unit\":\"PT\"\n }\n }\n },\n \"shapeType\":\"TEXT_BOX\",\n \"objectId\":\"newTextBox\"\n }\n },\n {\n \"insertText\":{\n \"objectId\":\"newTextBox\",\n \"text\":\"Hello World\"\n }\n }\n ]\n}\n```\n\n### Response\n\nThis example batch response displays information on how each subrequest within\nthe batch request was applied. Note the\n[`InsertTextRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#inserttextrequest)\nmethod doesn't contain a response so the index value of the array at \\[2\\]\nconsists of empty curly braces. The batch request does display the\n[`WriteControl`](/workspace/slides/api/reference/rest/v1/presentations/batchUpdate#writecontrol)\nproperty, which shows how the write requests were executed. \n\n```scdoc\n{\n \"requiredRevisionId\": ID\n \"presentationId\": \"\",\n \"replies\":[\n {\n \"createSlide\":{\n \"objectId\":\"newSlide\"\n }\n },\n {\n \"createShape\":{\n \"objectId\":\"newTextBox\"\n }\n },\n {\n \n }\n ],\n \"writeControl\":{\n \"requiredRevisionId\": REVISION_ID\n }\n}\n```"]]
