批量处理 Google Analytics(分析)API 请求

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

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

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

概览

客户建立的每个 HTTP 连接都会在一定程度上占用系统开销。Google Analytics(分析)API 支持批处理,允许您的客户将多个 API 调用放在单个 HTTP 请求中。

在以下示例情况下,建议您使用批处理:

  • 更新用户权限。就提升性能和获取配额奖励方面来说,通过批量请求来更新用户权限的好处尤为显著。有关详情,请参阅用户权限开发者指南
  • 您的移动报告应用可能会处于离线状态,您需要在应用恢复在线后发出一组数据请求。
  • 您有一个服务帐号应用,该应用需要定期创建多个报告。
  • 您需要创建一组自定义维度或自定义指标,并希望仅发出一个 HTTP 请求。

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

单个批量请求中的调用次数上限为 1000 次。如果需要发出更多调用,请使用多个批量请求。

注意:Google Analytics(分析)API 的批处理系统使用的语法与 OData 批处理系统相同,但语义不同。

详细了解批处理

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

注意:凡是集中进行批处理的一组 n 个请求,均将按 n 个请求(而不是一个请求)计入使用量限额。因为系统会在处理前将该批处理请求拆分为一组请求。

批量请求的格式

批量请求是使用 multipart/mixed 内容类型的标准 HTTP 请求,其中包含多个 Google Analytics(分析)API 调用。在主 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- 字符串,如下例所示。

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

示例

以下示例显示了使用 Google Analytics(分析)API 进行批量请求的方法。

批量请求示例

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary

POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68

{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary

POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67

{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

批量响应示例

此响应对应于上一节中的示例请求。

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

客户端库

请使用以下客户端库指南来了解如何使用特定语言实现批量处理:

批处理和 Google Analytics(分析)配额

虽然批量请求可以为您节省构建多个 HTTP 请求的开销,但批量请求中的每个 Google Analytics(分析)API 请求仍会计入您的每日项目配额。默认情况下,每个项目每日最多可以发出 50000 次请求,使用批量请求不能帮助您解决配额不够用的问题。

除了批量用户权限写入(删除、插入、更新)请求之外,所有的限额仍然适用。例如,对 Core Reporting API 的限制为每个数据视图(配置文件)10 次并发请求;如果配额不够用,使用批量请求并不能解决此问题。

Management API 写入请求Provisioning API 写入请求的限制均为每个帐号 ID 每秒 1.5 次查询。因此,对这些写入请求进行批处理可能不会提高性能。