报告任务基础知识
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
借助报告任务,您可以启动长时间运行的异步请求,以便根据 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
方法。以下是必填参数:
报告任务创建请求示例:
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"
}
}
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-07-26。
[null,null,["最后更新时间 (UTC):2025-07-26。"],[[["\u003cp\u003eReport tasks allow you to create customized, asynchronous reports of your Google Analytics event data, accessible to users with read access to your property.\u003c/p\u003e\n"],["\u003cp\u003eReports are available for 72 hours before automatic deletion, and are generated through a process involving \u003ccode\u003ereportTasks.create\u003c/code\u003e to initiate the task and \u003ccode\u003ereportTasks.query\u003c/code\u003e to retrieve the results.\u003c/p\u003e\n"],["\u003cp\u003eReport task status can be monitored using \u003ccode\u003ereportTasks.get\u003c/code\u003e to check for 'ACTIVE' state, indicating report readiness for retrieval via \u003ccode\u003ereportTasks.query\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eReport generation is based on the specified Google Analytics property, requiring its identifier in the request path or as a \u003ccode\u003eproperty\u003c/code\u003e parameter when using client libraries.\u003c/p\u003e\n"]]],["Report Tasks in the Google Analytics Data API v1 allow asynchronous creation of customized reports. Initiate this with `reportTasks.create`, specifying the `ReportDefinition`. Use the returned Report Task name to check the readiness state with `reportTasks.get` or list all tasks with `reportTasks.list`. Once ready (`ACTIVE` state), retrieve the report via `reportTasks.query`. Reports, generated based on specified GA property data, are accessible for 72 hours, and all methods require the GA property ID.\n"],null,["# Report Tasks Fundamentals\n\nUsing report tasks, you can start a long-running asynchronous request to create\na customized report of your Google Analytics event data.\n\nThe Report Task resource generated from this request can be used to access\ncustomized reports by all users with read access to your Google Analytics\nproperty.\n\nA customized report will be available for 72 hours after it is ready. After this\nperiod, the corresponding report task resource and its contents will be\nautomatically deleted.\n| **Note:** Report Tasks are available in the [v1alpha](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks) version of the Data API.\n\nCreate a Report Task\n--------------------\n\nThe Google Analytics Data API v1 uses an asynchronous approach to\ncreate Report Tasks. First, a request to the\n[`reportTasks.create`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create)\nmethod is necessary to create a Report Task. Then, the\n[`reportTasks.query`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/query)\nmethod is used to retrieve the generated customized report.\n\nIn addition, you can use\n[`reportTasks.get`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/get)\nto retrieve configuration metadata about a specific Report Task and\n[`reportTasks.list`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/list)\nto list all Report Tasks for a property.\n\n### Select a reporting entity\n\nAll methods of the Data API v1 require the\n[Google Analytics property identifier](/analytics/devguides/reporting/data/v1/property-id)\nto be specified inside a URL request path in the form of\n`properties/GA_PROPERTY_ID`, such as: \n\n POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks\n\nThe report is generated based on the Google Analytics event\ndata collected in the specified Google Analytics property.\n\nIf you are using one of the [Data API client libraries](/analytics/devguides/reporting/data/v1/client-libraries),\nthere is no need to manipulate the request URL path manually.\nMost API clients provide a `property` parameter that expects a\nstring in the form of `properties/GA_PROPERTY_ID`.\nSee [Quick start guide](/analytics/devguides/reporting/data/v1/quickstart-client-libraries) for examples\nof using the client libraries.\n\n### Request the Report Task creation\n\nTo create a Report Task, call the\n[`reportTasks.create`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create)\nmethod using the\n[`ReportTask`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#ReportTask)\nobject in a request. The following parameters are required:\n\n- [`reportDefinition`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#%20ReportDefinition) field which describes the definition of a customized report. This parameter's structure is similar to the report definition used by [Core Reporting methods](/analytics/devguides/reporting/data/v1/basics).\n\nExample Report Task creation request: \n\n### HTTP Request\n\n POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks\n {\n \"reportDefinition\": {\n \"dateRanges\": [{ \"startDate\": \"\u003cvar translate=\"no\"\u003e2024-05-01\"\u003c/var\u003e\", \"endDate\": \"\u003cvar translate=\"no\"\u003e2024-05-15\u003c/var\u003e\" }],\n \"dimensions\": [{ \"name\": \"country\" }],\n \"metrics\": [{ \"name\": \"activeUsers\" }]\n }\n }\n\nA response of the `reportTasks.create` method contains the Report\nTask name in the `name` field (such as\n`properties/1234567/reportTasks/123`), which can be used in\nsubsequent queries to obtain the status of a Report Task and retrieve the\nresulting report. \n\n### HTTP Response\n\n {\n \"response\": {\n \"@type\": \"type.googleapis.com/google.analytics.data.v1alpha.ReportTask\",\n \"name\": \"properties/1234567/reportTasks/123\",\n \"reportDefinition\": {\n \"dimensions\": [\n {\n \"name\": \"country\"\n }\n ],\n \"metrics\": [\n {\n \"name\": \"activeUsers\"\n }\n ],\n \"dateRanges\": [\n {\n \"startDate\": \"2024-05-01\",\n \"endDate\": \"2024-05-15\"\n }\n ]\n },\n \"reportMetadata\": {\n \"state\": \"CREATING\",\n \"beginCreatingTime\": \"2024-05-16T00:00:01.133612336Z\"\n }\n }\n }\n\n### Get the Report Task readiness state\n\nIt may take several minutes to generate a report after the\n[`reportTasks.create`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create)\ncall. You can obtain the readiness state for an Report Task by calling the\n[`reportTasks.get`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/get)\nmethod.\n\nUse the Report Task name (such as `properties/1234567/reportTasks/123`)\nyou received from a `reportTasks.create` response to specify the\nReport Task.\n\nExample: \n\n### HTTP Request\n\n GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123\n\nThe readiness status for an Report Task is returned in the\n[`state`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#ReportTask.FIELDS.state)\nfield of a response. Once the report generation is complete,\nthe state of a Report Task changes from `CREATING` to `ACTIVE`.\n\nThe [`reportMetadata`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#ReportTask.FIELDS.reportMetadata)\nfield contains the high level information about the generated report, such as\nthe rows count and the amount of quota tokens charged. \n\n### HTTP Response\n\n {\n \"reportDefinition\": {\n \"dimensions\": [\n {\n \"name\": \"country\"\n }\n ],\n \"metrics\": [\n {\n \"name\": \"activeUsers\"\n }\n ],\n \"dateRanges\": [\n {\n \"startDate\": \"2024-05-01\",\n \"endDate\": \"2024-05-15\"\n }\n ]\n },\n \"reportMetadata\": {\n \"state\": \"ACTIVE\",\n \"beginCreatingTime\": \"2024-05-16T00:00:01.133612336Z\",\n \"creationQuotaTokensCharged\": 6,\n \"taskRowCount\": 167,\n \"errorMessage\": \"\",\n \"totalRowCount\": 167\n }\n }\n\nYou can obtain the state of all Report Tasks by calling the\n[`reportTasks.list`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/list)\nmethod.\n\n### Retrieve the generated report\n\nOnce the Report Task created using the\n[`reportTasks.create`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create)\nmethod is generated, call the\n[`reportTasks.query`](/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/query)\nmethod and specify the Report Task name\n(such as `properties/1234567/reportTasks/123`). \n\n### HTTP Request\n\n POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query\n\nIf the Report Task is ready, a response containing generated report is returned: \n\n### HTTP Response\n\n {\n \"dimensionHeaders\": [\n {\n \"name\": \"country\"\n }\n ],\n \"metricHeaders\": [\n {\n \"name\": \"activeUsers\",\n \"type\": \"TYPE_INTEGER\"\n }\n ],\n \"rows\": [\n\n ...\n\n ],\n \"rowCount\": 167,\n \"metadata\": {\n \"currencyCode\": \"USD\",\n \"timeZone\": \"America/Los_Angeles\"\n }\n }"]]