发送批量请求
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本文档介绍了如何对 API 调用进行批处理以减少客户端必须建立的 HTTP 连接数量。
本文档专门介绍了如何通过发送 HTTP 请求来发出批处理请求。如果您要使用某个 Google 客户端库来发出批处理请求，请参阅该客户端库的说明文档。
概览
客户端建立的每个 HTTP 连接都会产生一定的开销。Enterprise License Manager API 支持批处理，这样您的客户端就可以将多个 API 调用组合为一个 HTTP 请求。
在以下示例情况下，您可能需要使用批处理：
- 您刚开始使用该 API，并且需要上传大量数据。
- 用户在应用离线（已断开与互联网的连接）时对数据进行了更改，因此您的应用需要通过发出大量更新和删除请求来将其本地数据与服务器同步。
在上述每种情况下，您都可以将这些调用组合成一个 HTTP 请求，而不是单独发送每个调用。请注意，所有内部请求都必须发送到同一 Google API。
单个批量请求最多可以包含 1000 次调用。如果必须进行更多次调用，请使用多个批量请求。
注意：Enterprise License Manager API 的批处理系统使用的语法与 OData 批处理系统相同，但语义有所不同。
批量详情
批量请求就是将多个 API 调用进行合并而形成的一个 HTTP 请求，您可以将此请求发送到 API 发现文档中指定的 batchPath。默认路径为 /batch/api_name/api_version。本部分详细介绍了批处理语法，随后还会提供一个示例。
注意：一组一起进行批处理的 n 个请求将按 n 个请求（而非一个请求）计入用量限额。在处理之前，系统会将批量请求拆分为一组请求。
批量请求是一个包含多个 Enterprise License Manager API 调用的标准 HTTP 请求，使用 multipart/mixed 内容类型。在此主 HTTP 请求中，每个部分都包含一个内嵌的 HTTP 请求。
各个部分都以其自身的 Content-Type: application/http 标头开头。您还可以选择添加一个 Content-ID 标头。不过，每个部分的标头仅用于标记该部分的开头，而与嵌套请求无关。在服务器将批量请求拆分为多个单独请求之后，每个部分的标头就会被忽略。
各个部分的正文是一个完整的 HTTP 请求，各自有专用的动词、网址、标头和正文。此 HTTP 请求必须仅包含网址的路径部分；不允许在批量请求中使用完整的网址。
外部批量请求的 HTTP 标头应用于批次中的每个请求，但 Content-Type 之类的 Content- 标头除外。如果您在外部请求和个别调用中都指定了特定的 HTTP 标头，则个别调用标头的值将替换外部批量请求标头的值。另请注意，单个调用的标头仅应用于该调用本身。
例如，如果您为特定调用提供了 Authorization 标头，则该标头仅应用于该调用。如果您为外部请求提供了 Authorization 标头，则该标头将应用于所有的单个调用，除非单个调用将其替换为自身的 Authorization 标头。
当服务器收到批处理请求时，会将外部请求的查询参数和标头（如果适用）应用于各部分，然后将各部分视作单独的 HTTP 请求进行处理。
对批量请求的响应
服务器的响应是一个标准的 HTTP 响应，使用 multipart/mixed 内容类型；其中的每个部分分别是对批量请求中一个请求的响应，且顺序与这些请求相同。
和请求中的各部分一样，响应中的各部分都包含一个完整的 HTTP 响应，其中包括状态代码、标头和正文。此外，和请求中的各部分一样，响应中的各部分均以 Content-Type 标头为前缀，用于标记各部分的开头。
如果请求的某个特定部分具有 Content-ID 标头，则响应的对应部分也会有相同的 Content-ID 标头，其格式为在原始值前面加上 response- 字符串，如下例所示。
注意：服务器可能会以任何顺序执行您的调用，因此不要预期这些调用将会以您指定的顺序执行。如果要确保两个调用以指定顺序执行，就不能在单个请求中发送这两个调用。正确的做法是，先单独发送第一个调用，等收到其响应之后再发送第二个。
示例
以下示例展示了如何将批处理与名为 Farm API 的通用（虚构）演示 API 结合使用。不过，这些思路也同样适用于 Enterprise License Manager 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 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-04。
[null,null,["最后更新时间 (UTC)：2025-08-04。"],[],[],null,["# Send batch 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 Enterprise License Manager 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 Enterprise License Manager 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 Enterprise License Manager 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 Enterprise License Manager 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```"]]
