批处理解决方案 HTTP REST API 批量处理

如何进行批处理请求（Batch Requests）

Vano

2023-04-09

原文标题：Batch requests
原文链接：https://developers.google.com/drive/api/guides/performance#batch-requests
来源：Google Workspace

Google Developers 博客上宣布，一种特定的批处理方法是 Global HTTP Batch 端点 (www.googleapis.com/batch) 已于 2020 年 8 月 12 日关闭。其他批处理方法仍然有效，如本页其余部分所述。如果你的代码使用全局 HTTP 批处理端点，请参阅博客文章以获取有关转换为使用其他方法的说明，例如特定于 API 的 HTTP 批处理端点 (www.googleapis.com/batch/API/VERSION)。

本文展示了如何将 API 调用批量化，以减少客户需要进行的 HTTP 连接的数量。

本文档是关于通过发送 HTTP 请求来进行批处理请求的。如果你使用 Google 客户端库来进行批处理请求，请参阅客户端库的文档。

概述

客户端建立的每个 HTTP 连接都会产生一定的开销。Google Drive API 支持批处理，允许客户端将多个 API 调用放入单个 HTTP 请求中。

你可能想要使用批处理的情况示例：

检索大量文件的元数据。
大量更新元数据或属性。
更改大量文件的权限，例如添加新的用户或组。
首次或长时间离线后同步本地客户端数据。

在每种情况下，你都可以将每个调用组合成一个单独的 HTTP 请求，而不是单独发送每个调用。所有的内部请求必须发往相同的 Google API。

在一个批处理请求中最多只能调用100次。如果你需要进行更多的调用，请使用多个批处理请求。

注意：

● Google Drive API 的批处理系统使用的语法与 OData 批处理系统相同，但语义不同。

● 调用次数超过100次的批量请求可能会导致错误。

● 每个内部请求的 URL 长度有8000字符的限制。

● 目前，Google Drive 不支持媒体的批处理操作，无论是上传还是下载。

批处理详情

批处理请求由多个 API 调用组合成一个 HTTP 请求，可以发送到 API 探索文档中指定的 batchPath。默认路径是/batch/api_name/api_version。本节详细描述了批处理的语法；稍后将提供一个示例。

注意：批处理在一起的一组 N 个请求将作为 N 个请求计入你的使用限制，而不是作为一个请求。批处理请求在处理前会被拆成一组请求。

批处理请求的格式

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

每个部分都以其自己的Content-Type: application/http HTTP header 开始。它还有一个可选的Content-ID header。然而，部分 header 信息只是用来标记部分的开始，它们与嵌套请求是分开的。在服务器将批处理请求解包为单独的请求后，部分 header 就被忽略了。

每个部分的 body 本身就是一个完整的 HTTP 请求，有它自己的 verb、URL、header 和 body。HTTP 请求只能包含 URL 的路径部分；批处理请求中不允许使用完整的 URL。

外部批处理请求的 HTTP header，除了Content-header，如Content-Type，适用于批处理中的每个请求。如果你在外部请求和单个调用中都指定了一个 HTTP header，那么单个调用 header 的值会覆盖外部批处理请求 header 的值。单个调用的 header 只适用于该调用。

例如，如果你为特定调用提供了一个授权 header，那么该 header 只适用于该调用。如果你为外部请求提供了一个授权 header，那么这个 header 将应用于所有的单个调用，除非它们用自己的授权 header 来覆盖它。

当服务器收到批处理请求时，它会将外部请求的查询参数和 header（如适用）应用于每个部分，然后将每个部分当作一个单独的 HTTP 请求。

对批处理请求的响应

服务器的响应是具有multipart/mixed内容类型的单个标准 HTTP 响应；每个部分是对批处理请求中的一个请求的响应，与请求顺序相同。

与请求中的部分一样，每个响应部分都包含一个完整的 HTTP 响应，包括状态代码、header 和 body。和请求中的部分一样，每个响应部分前面都有一个Content-Typeheader，标记着这部分的开始。

如果请求的给定部分有一个Content-IDheader，则响应的相应部分应具有一个匹配的Content-IDheader，其原始值前面带有字符串response-，如下面的例子中所示。

注意：服务器可能以任何顺序执行你的调用。不要指望它们会按照你指定的顺序执行。如果你想确保两个调用按给定的顺序发生，则不能在单个请求中发送它们；相反，应单独发送第一个调用，然后等待第一个调用的响应，再发送第二个调用。

示例

以下示例展示了如何使用 Google Drive API 进行批处理。

批处理请求示例

POST https://www.googleapis.com/batch/drive/v3
Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip)
Content-Type: multipart/mixed; boundary=END_OF_PART
Content-Length: 963



--END_OF_PART
Content-Length: 337
Content-Type: application/http
content-id: 1
content-transfer-encoding: binary



POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id
Authorization: Bearer authorization_token
Content-Length: 70
Content-Type: application/json; charset=UTF-8



{
  "emailAddress":"example@appsrocks.com",
  "role":"writer",
  "type":"user"
}
--END_OF_PART
Content-Length: 353
Content-Type: application/http
content-id: 2
content-transfer-encoding: binary



POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false
Authorization: Bearer authorization_token
Content-Length: 58
Content-Type: application/json; charset=UTF-8



{
   "domain":"appsrocks.com",
   "role":"reader",
   "type":"domain"
}
--END_OF_PART--

批处理响应示例

这是对上一节中的示例请求的响应。

HTTP/1.1 200 OK
Alt-Svc: quic=":443"; p="1"; ma=604800
Server: GSE
Alternate-Protocol: 443:quic,p=1
X-Frame-Options: SAMEORIGIN
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
Date: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Vary: X-Origin
Vary: Origin
Expires: Fri, 13 Nov 2015 19:28:59 GMT



--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35



{
 "id": "12218244892818058021i"
}



--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-2



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35



{
 "id": "04109509152946699072k"
}


--batch_6VIxXCQbJoQ_AATxy_GgFUk--

从请求中返回特定字段

默认情况下，服务器会发回一组特定于所用方法的默认资源字段。例如，files.list 方法可能只返回id、name和mimeType。这些字段可能不是你需要的确切字段。如果需要返回其他字段，请参阅返回文件的特定字段。

关于批量处理，请看：

概述