批处理请求

Google Developers 博文中宣布,全球 HTTP 批处理端点 (www.googleapis.com/batch) 将于 2019 年 3 月 25 日停止工作。请按照该博文中的说明,对相应的 API 端点 (www.googleapis.com/batch/api/version) 改用具有类似功能的批处理请求。

本文档介绍了如何对 API 调用进行批处理以减少客户端必须建立的 HTTP 连接数量。

本文档专门介绍了如何通过发送 HTTP 请求来发出批处理请求。如果您要使用某个 Google 客户端库来发出批处理请求,请参阅该客户端库的说明文档

概览

客户端建立的每个 HTTP 连接都会产生一定的开销。Google Compute Engine API 支持批处理,这样您的客户端就可以将多个 API 调用合为一个 HTTP 请求。

在以下示例情况下,您可能需要使用批处理:

  • 您刚开始使用该 API,并且需要上传大量数据。
  • 用户在应用离线(已断开与互联网的连接)时对数据进行了更改,因此您的应用需要通过发出大量更新和删除来将其本地数据与服务器同步。

在上述每种情况下,您都可以将这些调用组合成一个 HTTP 请求,而不是单独发送每个调用。请注意,所有内部请求都必须发送到同一 Google API。

单个批处理请求中可以包含的调用数量上限为 1000。如果需要进行更多调用,请使用多个批处理请求。

注意:Google Compute Engine API 的批处理系统使用的语法与 OData 批处理系统相同,但语义有所不同。

批处理详情

批处理请求由合并为一个 HTTP 请求的多个 API 调用构成,您可以将此请求发送到 API 发现文档中指定的 batchPath。默认路径是 /batch/api_name/api_version。本部分详细介绍了批处理语法,随后还会提供一个示例

注意:一组一起进行批处理的 n 个请求将按 n 个请求(而非一个请求)计入使用量限额。在执行批处理请求之前,系统会将其拆分为一组请求。

批处理请求的格式

批处理请求是一个包含多个 Google Compute Engine API 调用的标准 HTTP 请求,使用 multipart/mixed 内容类型。在此主 HTTP 请求中,每个部分都包含一个内嵌的 HTTP 请求。

每个部分都以其自身的 Content-Type: application/http HTTP 标头开头。此外,可能还有一个可选的 Content-ID 标头。不过,这些部分的标头仅用于标记各个部分的开头,与所嵌入的请求是相互独立的。在服务器将批处理请求拆分为多个单独请求之后,这些标头就会被忽略。

各个部分的正文本身是一个完整的 HTTP 请求,拥有自己的动词、网址、标头和正文。此 HTTP 请求必须仅包含网址的路径部分;在批处理请求中不允许使用完整的网址。

除了 Content- 标头(例如 Content-Type)以外,外部批处理请求的 HTTP 标头将应用于该批处理过程中的每个请求。如果您在外部请求和单个调用中都指定了特定的 HTTP 标头,则单个调用标头的值将替换外部批处理请求标头的值。另请注意,单个调用的标头仅应用于该调用本身。

例如,如果您为特定调用提供了 Authorization 标头,则该标头仅应用于该调用。如果您为外部请求提供了 Authorization 标头,则该标头将应用于所有的单个调用,除非单个调用将其替换为自身的 Authorization 标头。

当服务器收到批处理请求时,会将外部请求的查询参数和标头(如果适用)应用于各部分,然后将各部分视作单独的 HTTP 请求进行处理。

响应批处理请求

服务器的响应是一个标准的 HTTP 响应,使用 multipart/mixed 内容类型;其中的每个部分分别是对批处理请求中的一个请求的响应,其顺序与请求相同。

和请求中的各部分一样,各个响应部分都包含一个完整的 HTTP 响应,其中包含状态代码、标头和正文。同样和请求中的各部分一样,各响应部分均以 Content-Type 标头为前缀,用于标记各部分的开头。

如果请求的某个部分具有 Content-ID 标头,则响应的相应部分也会有相同的 Content-ID 标头,其格式为在原始值前面加上 response- 字符串,如下例所示。

注意:服务器可能会以任何顺序执行您的调用,因此不要预期这些调用将会以您指定的顺序执行。如果要确保两个调用以指定顺序执行,就不能在单个请求中发送这两个调用。正确的做法是,先单独发送第一个调用,等收到其响应之后再发送第二个。

示例

以下示例通过一个称为 Farm API 的通用(虚构)演示 API 展示了批处理的使用。不过,这些概念同样适用于 Google Compute Engine 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--
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Compute Engine 文档