リクエストのバッチ処理
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
ここでは、複数のバッチ API 呼び出しを行って、クライアント側の HTTP 接続の回数を減らす方法について説明します。
具体的には、1 件の HTTP リクエストを送信してバッチ リクエストを行う方法を取り上げます。Google クライアント ライブラリを使用してバッチ リクエストを行う場合は、クライアント ライブラリのドキュメントをご覧ください。
概要
クライアントで HTTP 接続を行うたびに、ある程度のオーバーヘッドが発生します。Gmail API はバッチ処理をサポートしているため、クライアントは複数の API 呼び出しを 1 つの HTTP リクエストにまとめることができます。
バッチ処理は次のような状況で使用します。
- API の使用を開始したばかりで、アップロードするデータが大量にある。
- アプリケーションがオフライン（インターネットに接続されていない状態）のときにユーザーがデータを変更したため、更新や削除の呼び出しを大量に送信してローカルデータとサーバー間で同期させる必要がある。
いずれの場合も、各呼び出しを個別に送信するのではなく、1 つの HTTP リクエストにまとめることができます。内部リクエストはすべて同じ Google API に送信する必要があります。
1 つのバッチ リクエストに含めることができる呼び出しの上限は 100 個です。これよりも多くの呼び出しを行う必要がある場合は、複数のバッチ リクエストを使用します。
注: Gmail API のバッチシステムは OData バッチ処理システムと同じ構文を使用しますが、セマンティクスは異なります。
注: バッチサイズが大きいほど、レート制限がトリガーされる可能性が高くなります。50 件を超えるリクエストを含むバッチを送信することはおすすめしません。
バッチ リクエストの詳細
バッチ リクエストは、複数の API 呼び出しを 1 つの HTTP リクエストにまとめたもので、API ディスカバリ ドキュメントで指定されている batchPath に送信できます。デフォルトのパスは /batch/api_name/api_version です。このセクションでは、バッチ リクエストの構文について詳しく説明し、最後に例を紹介します。
注: n 件のリクエストを 1 つにまとめたバッチ リクエストは、1 件のリクエストではなく n 件のリクエストとして使用量上限に加算されます。バッチ リクエストは、個々のリクエストに分割されてから処理されます。
バッチ リクエストは、複数の Gmail API 呼び出しを含んだ、multipart/mixed コンテンツ タイプを使用する単一の標準 HTTP リクエストです。そのメインの HTTP リクエスト内の各パーツには、ネストされた HTTP リクエストが含まれます。
各パーツはそれぞれ Content-Type: application/http という形式の HTTP ヘッダーで始まり、オプションの Content-ID ヘッダーを指定することもできます。ただし、パーツヘッダーはパーツの開始箇所を示すためだけに存在していて、ネストされたリクエストとは分かれています。サーバーがバッチ リクエストを別々のリクエストにアンラップした後、パーツヘッダーは無視されます。
各パーツのボディは、独自の動詞、URL、ヘッダー、ボディを含む完全な HTTP リクエストです。これらの HTTP リクエストには URL のパス部分のみを含める必要があり、完全な URL は、バッチ リクエストでは許可されていません。
外側のバッチ リクエストの HTTP ヘッダー（Content-Type などの Content- ヘッダー以外）はバッチ リクエスト内の各リクエストに適用されます。ある HTTP ヘッダーを外側のリクエストと個々の呼び出しの両方で指定した場合、個々の呼び出しのヘッダー値は外側のバッチ リクエストのヘッダー値を上書きします。個々の呼び出しのヘッダーはその呼び出しにのみ適用されます。
たとえば、ある呼び出しに Authorization ヘッダーを指定した場合、そのヘッダーはその呼び出しにのみ適用されます。Authorization ヘッダーを外側のリクエストに指定した場合、そのヘッダーはすべての呼び出しに適用されます。ただし、各呼び出しに独自の Authorization ヘッダーを指定している場合は各呼び出しの Authorization ヘッダーで上書きされます。
サーバーがバッチ リクエストを受信すると、外側のリクエストのクエリ パラメータとヘッダー（指定した場合）を各パーツに適用し、各パーツを個別の HTTP リクエストとして処理します。
バッチ リクエストへのレスポンス
サーバーのレスポンスは multipart/mixed コンテンツ タイプを使用した単一の標準 HTTP レスポンスです。各パーツはバッチ リクエスト内の個々のリクエストに対するレスポンスで、リクエストと同じ順序にネストされます。
レスポンスの各パーツは、リクエストのパーツと同様にステータス コード、ヘッダー、ボディを含む完全な HTTP レスポンスになっています。また、リクエストのパーツと同様に、レスポンスの各パーツはパーツの開始箇所を示す Content-Type ヘッダーから始まります。
リクエストのパーツに Content-ID ヘッダーがある場合、対応するレスポンスのパーツには、それに一致する Content-ID ヘッダーが指定されます。レスポンスのパーツのヘッダーは、以下の例に示すように、元の値の先頭に文字列 response- が付いた値となります。
注: サーバーはバッチ リクエスト内の呼び出しを順番どおりに処理するとは限りません。指定した順序で実行されると想定しないでください。2 つの呼び出しを特定の順序で実行したい場合は、1 つのバッチ リクエストで送信することはできません。代わりに、最初の呼び出しを送信してレスポンスが返ってきてから、2 番目の呼び出しを送信します。
例
Farm API という汎用的な（架空の）デモ API を使用したバッチ処理の例を次に示します。Gmail API にも同じ概念が適用されます。
バッチ リクエストの例
POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length
--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:12930812@barnyard.example.com>
GET /farm/v1/animals/pony
--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>
PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"
{
"animalName": "sheep",
"animalAge": "5"
"peltColor": "green",
}
--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:12930812@barnyard.example.com>
GET /farm/v1/animals
If-None-Match: "etag/animals"
--batch_foobarbaz--
バッチ レスポンスの例
これは、前のセクションのリクエスト例に対するレスポンスです。
HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@barnyard.example.com>
HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"
{
"kind": "farm#animal",
"etag": "etag/pony",
"selfLink": "/farm/v1/animals/pony",
"animalName": "pony",
"animalAge": 34,
"peltColor": "white"
}
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@barnyard.example.com>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"
{
"kind": "farm#animal",
"etag": "etag/sheep",
"selfLink": "/farm/v1/animals/sheep",
"animalName": "sheep",
"animalAge": 5,
"peltColor": "green"
}
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:12930812@barnyard.example.com>
HTTP/1.1 304 Not Modified
ETag: "etag/animals"
--batch_foobarbaz--
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-07-31 UTC。
[null,null,["最終更新日 2025-07-31 UTC。"],[],[],null,["# Batching Requests\n\nThis document shows how to batch API calls together to reduce the number of HTTP connections\nyour client has to make.\n\nThis document is specifically about making a batch request by sending an\nHTTP request. If, instead, you're using a Google client library to make a batch request, see the [client library's documentation](https://developers.google.com/api-client-library/).\n\nOverview\n--------\n\nEach HTTP connection your client makes results in a certain amount of overhead. The Gmail API supports batching, to allow your client to put several API calls into a single HTTP request.\n\nExamples of situations when you might want to use batching:\n\n- You've just started using the API and you have a lot of data to upload.\n- A user made changes to data while your application was offline (disconnected from the Internet), so your application needs to synchronize its local data with the server by sending a lot of updates and deletes.\n\nIn each case, instead of sending each call separately, you can group them together into a single HTTP request. All the inner requests must go to the same Google API.\n\nYou're limited to 100 calls in a single batch request. If you must make more calls than that, use multiple batch requests.\n\n**Note** : The batch system for the Gmail API uses the same syntax as the [OData batch processing](http://www.odata.org/documentation/odata-version-3-0/batch-processing/) system, but the semantics differ.\n\n\n**Note**: Larger batch sizes are likely to trigger rate\nlimiting. Sending batches larger than 50 requests is not recommended.\n\nBatch details\n-------------\n\nA batch request consists of multiple API calls combined into one HTTP request, which can be sent to the `batchPath` specified in the [API discovery document](https://developers.google.com/discovery/v1/reference/apis). The default path is `/batch/`\u003cvar translate=\"no\"\u003eapi_name\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eapi_version\u003c/var\u003e. This section describes the batch syntax in detail; later, there's an [example](#example).\n\n**Note** : A set of \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests batched together counts toward your usage limit as \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests, not as one request. The batch request is separated into a set of requests before processing.\n\n### Format of a batch request\n\nA batch request is a single standard HTTP request containing multiple Gmail API calls, using the `multipart/mixed` content type. Within that main HTTP request, each of the parts contains a nested HTTP request.\n\nEach part begins with its own `Content-Type: application/http` HTTP header. It can also have an optional `Content-ID` header. However, the part headers are just there to mark the beginning of the part; they're separate from the nested request. After the server unwraps the batch request into separate requests, the part headers are ignored.\n\nThe body of each part is a complete HTTP request, with its own verb, URL, headers, and body. The HTTP request must only contain the path portion of the URL; full URLs are not allowed in batch requests.\n\nThe HTTP headers for the outer batch request, except for the `Content-` headers such as `Content-Type`, apply to every request in the batch. If you specify a given HTTP header in both the outer request and an individual call, then the individual call header's value overrides the outer batch request header's value. The headers for an individual call apply only to that call.\n\nFor example, if you provide an Authorization header for a specific call, then that header applies only to that call. If you provide an Authorization header for the outer request, then that header applies to all of the individual calls unless they override it with Authorization headers of their own.\n\nWhen the server receives the batched request, it applies the outer request's query parameters and headers (as appropriate) to each part, and then treats each part as if it were a separate HTTP request.\n\n### Response to a batch request\n\nThe server's response is a single standard HTTP response with a `multipart/mixed` content type; each part is the response to one of the requests in the batched request, in the same order as the requests.\n\nLike the parts in the request, each response part contains a complete HTTP response, including a status code, headers, and body. And like the parts in the request, each response part is preceded by a `Content-Type` header that marks the beginning of the part.\n\nIf a given part of the request had a `Content-ID` header, then the corresponding part of the response has a matching `Content-ID` header, with the original value preceded by the string `response-`, as shown in the following example.\n\n**Note**: The server might perform your calls in any order. Don't count on their being executed in the order in which you specified them. If you want to ensure that two calls occur in a given order, you can't send them in a single request; instead, send the first one by itself, then wait for the response to the first one before sending the second one.\n\nExample\n-------\n\nThe following example shows the use of batching with a generic (fictional) demo API called the Farm API. However, the same concepts apply to the Gmail API.\n\n### Example batch request\n\n```\nPOST /batch/farm/v1 HTTP/1.1\nAuthorization: Bearer your_auth_token\nHost: www.googleapis.com\nContent-Type: multipart/mixed; boundary=batch_foobarbaz\nContent-Length: total_content_length\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem1:12930812@barnyard.example.com\u003e\n\nGET /farm/v1/animals/pony\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem2:12930812@barnyard.example.com\u003e\n\nPUT /farm/v1/animals/sheep\nContent-Type: application/json\nContent-Length: part_content_length\nIf-Match: \"etag/sheep\"\n\n{\n \"animalName\": \"sheep\",\n \"animalAge\": \"5\"\n \"peltColor\": \"green\",\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem3:12930812@barnyard.example.com\u003e\n\nGET /farm/v1/animals\nIf-None-Match: \"etag/animals\"\n\n--batch_foobarbaz--\n```\n\n### Example batch response\n\nThis is the response to the example request in the previous section. \n\n```\nHTTP/1.1 200\nContent-Length: response_total_content_length\nContent-Type: multipart/mixed; boundary=batch_foobarbaz\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item1:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 200 OK\nContent-Type application/json\nContent-Length: response_part_1_content_length\nETag: \"etag/pony\"\n\n{\n \"kind\": \"farm#animal\",\n \"etag\": \"etag/pony\",\n \"selfLink\": \"/farm/v1/animals/pony\",\n \"animalName\": \"pony\",\n \"animalAge\": 34,\n \"peltColor\": \"white\"\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item2:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 200 OK\nContent-Type: application/json\nContent-Length: response_part_2_content_length\nETag: \"etag/sheep\"\n\n{\n \"kind\": \"farm#animal\",\n \"etag\": \"etag/sheep\",\n \"selfLink\": \"/farm/v1/animals/sheep\",\n \"animalName\": \"sheep\",\n \"animalAge\": 5,\n \"peltColor\": \"green\"\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item3:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 304 Not Modified\nETag: \"etag/animals\"\n\n--batch_foobarbaz--\n```"]]
