报告任务基础知识

借助报告任务，您可以启动长时间运行的异步请求，以创建包含 Google Analytics（分析）事件数据的自定义报告。

通过此请求生成的报告任务资源可用于访问对您的 Google Analytics（分析）媒体资源拥有读取权限的所有用户的自定义报告。

自定义报告在准备就绪后的 72 小时内可供使用。此时间段过后，系统会自动删除相应的报告任务资源及其内容。

创建报告任务

Google Analytics（分析）Data API v1 使用异步方法来创建报告任务。首先，需要向 reportTasks.create 方法发出请求，以创建报告任务。然后，使用 reportTasks.query 方法检索生成的自定义报告。

此外，您还可以使用 reportTasks.get 检索有关特定报告任务的配置元数据，并使用 reportTasks.list 列出媒体资源的所有报告任务。

选择一个举报实体

Data API v1 的所有方法都需要在网址请求路径中以 properties/GA4_PROPERTY_ID 的形式指定 Google Analytics（分析）4 媒体资源标识符，例如：

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks

该报告是根据指定 Google Analytics（分析）4 媒体资源中收集的 Google Analytics（分析）事件数据生成的。

如果您使用的是 Data API 客户端库之一，则无需手动操作请求网址路径。大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA4_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"
  }
}