借助报告任务,您可以启动长时间运行的异步请求,以便根据 Google Analytics 事件数据创建自定义报告。
通过此请求生成的“报告任务”资源可供所有拥有 Google Analytics 媒体资源读取权限的用户访问自定义报告。
自定义报告在生成后会在 72 小时内可用。在此期限过后,相应的报告任务资源及其内容将自动删除。
创建报告任务
Google Analytics Data API v1 使用异步方法创建报告任务。首先,您需要向 reportTasks.create
方法发出请求,才能创建报告任务。然后,使用 reportTasks.query
方法检索生成的自定义报告。
此外,您还可以使用 reportTasks.get
检索有关特定报告任务的配置元数据,并使用 reportTasks.list
列出媒体资源的所有报告任务。
选择报告实体
Data API v1 的所有方法都要求在网址请求路径中以 properties/GA_PROPERTY_ID
的形式指定 Google Analytics 媒体资源标识符,例如:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks
该报告是根据在指定 Google Analytics 媒体资源中收集的 Google Analytics 事件数据生成的。
如果您使用的是 Data API 客户端库之一,则无需手动操作请求网址路径。大多数 API 客户端都会提供一个 property
参数,该参数需要 properties/GA_PROPERTY_ID
形式的字符串。如需查看有关如何使用客户端库的示例,请参阅快速入门指南。
请求创建报告任务
如需创建报告任务,请在请求中使用 ReportTask
对象调用 reportTasks.create
方法。以下是必填参数:
reportDefinition
字段,用于描述自定义报告的定义。此参数的结构类似于核心报告方法使用的报告定义。
报告任务创建请求示例:
HTTP 请求
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
reportTasks.create
方法的响应包含 name
字段中的报告任务名称(例如 properties/1234567/reportTasks/123
),可在后续查询中用于获取报告任务的状态并检索生成的报告。
HTTP 响应
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
获取报告任务准备就绪状态
在 reportTasks.create
调用后,系统可能需要几分钟才能生成报告。您可以通过调用 reportTasks.get
方法来获取报告任务的准备就绪状态。
使用您从 reportTasks.create
响应收到的报告任务名称(例如 properties/1234567/reportTasks/123
)来指定报告任务。
示例:
HTTP 请求
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
报告任务的准备就绪状态会在响应的 state
字段中返回。报告生成完成后,报告任务的状态会从 CREATING
更改为 ACTIVE
。
reportMetadata
字段包含与生成的报告相关的概要信息,例如行数和消耗的配额令牌数量。
HTTP 响应
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
您可以通过调用 reportTasks.list
方法来获取所有报告任务的状态。
检索生成的报告
使用 reportTasks.create
方法生成报告任务后,调用 reportTasks.query
方法并指定报告任务名称(例如 properties/1234567/reportTasks/123
)。
HTTP 请求
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
如果报告任务已准备就绪,系统会返回包含生成的报告的响应:
HTTP 响应
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}