リクエストのバッチ処理
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
ここでは、複数のバッチ API 呼び出しを行って、クライアント側の HTTP 接続の回数を減らす方法について説明します。
具体的には、1 件の HTTP リクエストを送信してバッチ リクエストを行う方法を取り上げます。Google クライアント ライブラリを使用してバッチ リクエストを行う場合は、クライアント ライブラリのドキュメントをご覧ください。
概要
クライアントで HTTP 接続を行うたびに、ある程度のオーバーヘッドが発生します。People API はバッチ処理をサポートしているため、クライアントは複数の API 呼び出しを 1 つの HTTP リクエストにまとめることができます。
バッチ処理は次のような状況で使用します。
- API の使用を開始したばかりで、アップロードするデータが大量にある。
- アプリケーションがオフライン（インターネットに接続されていない状態）のときにユーザーがデータを変更したため、更新や削除の呼び出しを大量に送信してローカルデータとサーバー間で同期させる必要がある。
いずれの場合も、各呼び出しを個別に送信するのではなく、1 つの HTTP リクエストにまとめることができます。内部リクエストはすべて同じ Google API に送信する必要があります。
1 つのバッチ リクエストに含めることができる呼び出しの上限は 1,000 個です。これ以上の呼び出しを行う必要がある場合は、バッチ リクエストを複数使用します。
注: People API のバッチシステムは OData バッチ処理システムと同じ構文を使用しますが、セマンティクスは異なります。
バッチ リクエストの詳細
バッチ リクエストは、複数の API 呼び出しを 1 つの HTTP リクエストにまとめたもので、API ディスカバリ ドキュメントで指定されている batchPath に送信できます。デフォルトのパスは /batch/api_name/api_version です。このセクションでは、バッチ リクエストの構文について詳しく説明し、最後に例を紹介します。
注: n 件のリクエストを 1 つにまとめたバッチ リクエストは、1 件のリクエストではなく n 件のリクエストとして使用量上限に加算されます。バッチ リクエストは、個々のリクエストに分割されてから処理されます。
バッチ リクエストは multipart/mixed コンテンツ タイプを使用した単一の標準 HTTP リクエストで、複数の People API 呼び出しから構成されます。そのメインの 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 番目の呼び出しを送信します。
例
次の例は、People API でバッチ処理を使用する方法を示しています。
バッチ リクエストの例
POST /batch HTTP/1.1
accept-encoding: gzip, deflate
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary="batch_people"
Content-Length: total_content_length
--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1
POST /v1/people:createContact HTTP/1.1
Content-Type: application/json
Content-Length: part_content_length
Accept: application/json
{
"names": [{ "givenName": "John", "familyName": "Doe" }]
}
--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2
GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1
Accept: application/json
--batch_people--
バッチ レスポンスの例
これは、前のセクションのリクエスト例に対するレスポンスです。
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Date: Tue, 22 Jan 2020 18:56:00 GMT
Expires: Tue, 22 Jan 2020 18:56:00 GMT
Cache-Control: private
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"resourceName": "people/c11111111111111",
"etag": "1111",
"names": [{ "givenName": "John", "familyName": "Doe" }]
}
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-2
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"resourceName": "people/c123456789012345",
"etag": "1234",
"emailAddresses": [{ "value": "jane.doe@gmail.com" }]
}
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-08-29 UTC。
[null,null,["最終更新日 2025-08-29 UTC。"],[[["\u003cp\u003eBatching in the People API allows combining multiple API calls into a single HTTP request to reduce overhead.\u003c/p\u003e\n"],["\u003cp\u003eUse batching for scenarios like initial data uploads or synchronizing offline changes.\u003c/p\u003e\n"],["\u003cp\u003eA batch request uses the \u003ccode\u003emultipart/mixed\u003c/code\u003e content type and nests individual API calls as parts.\u003c/p\u003e\n"],["\u003cp\u003eThe server processes each part of the batch request as a separate HTTP request, but the order of execution isn't guaranteed.\u003c/p\u003e\n"],["\u003cp\u003eThe batch response is also \u003ccode\u003emultipart/mixed\u003c/code\u003e, with each part corresponding to the response of an individual call in the request.\u003c/p\u003e\n"]]],["Batching API calls consolidates multiple requests into a single HTTP request, reducing overhead. This method is useful for initial data uploads or synchronizing offline data. A batch request, limited to 1000 calls, uses `multipart/mixed` and contains nested HTTP requests. Each part has `Content-Type: application/http` header, with the body as a complete HTTP request (path portion only). The server returns a `multipart/mixed` response with individual HTTP responses. Outer request headers apply to all, but individual call headers can override them.\n"],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 People 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 1000 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 People 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\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 People 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 the People API.\n\n### Example batch request\n\n```\nPOST /batch HTTP/1.1\naccept-encoding: gzip, deflate\nAuthorization: Bearer your_auth_token\nContent-Type: multipart/mixed; boundary=\"batch_people\"\nContent-Length: total_content_length\n\n--batch_people\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: 1\n\nPOST /v1/people:createContact HTTP/1.1\nContent-Type: application/json\nContent-Length: \u003cvar translate=\"no\"\u003epart_content_length\u003c/var\u003e\nAccept: application/json\n{\n \"names\": [{ \"givenName\": \"John\", \"familyName\": \"Doe\" }]\n}\n\n--batch_people\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: 2\n\nGET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1\nAccept: application/json\n--batch_people--\n\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 OK\nContent-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nDate: Tue, 22 Jan 2020 18:56:00 GMT\nExpires: Tue, 22 Jan 2020 18:56:00 GMT\nCache-Control: private\n\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nContent-Type: application/http\nContent-ID: response-1\n\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=UTF-8\n{\n \"resourceName\": \"people/c11111111111111\",\n \"etag\": \"1111\",\n \"names\": [{ \"givenName\": \"John\", \"familyName\": \"Doe\" }]\n}\n\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nContent-Type: application/http\nContent-ID: response-2\n\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=UTF-8\n{\n \"resourceName\": \"people/c123456789012345\",\n \"etag\": \"1234\",\n \"emailAddresses\": [{ \"value\": \"jane.doe@gmail.com\" }]\n}\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--\n\n```"]]
