报告任务基础知识

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

通过此请求生成的报告任务资源可用于访问 对您的 Google Analytics 拥有读取权限的所有用户创建的自定义报告 属性。

自定义报告在生成后 72 小时内可用。在此之后 相应的报告任务资源及其内容将被 自动删除

创建报告任务

Google Analytics Data API v1 使用异步方法 创建报告任务。首先，向 reportTasks.create 方法的必要性。然后， reportTasks.query 方法检索生成的自定义报告。

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

选择举报实体

Data API v1 的所有方法都需要 Google Analytics 媒体资源标识符 在网址请求路径内指定，格式为 properties/GA_PROPERTY_ID，例如：

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

报告是根据 Google Analytics 事件生成的 在指定 Google Analytics 媒体资源中收集的数据。

如果您使用的是某个 Data API 客户端库， 因此无需手动处理请求网址路径 大多数 API 客户端都会提供一个 property 参数，该参数需要 字符串，格式为 properties/GA_PROPERTY_ID。 如需查看示例，请参阅快速入门指南 使用客户端库的方法

请求创建报告任务

要创建报告任务，请调用 reportTasks.create 方法使用 ReportTask 对象。以下是必填参数：

报告任务创建请求示例：

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 方法。

使用报告任务名称（例如 properties/1234567/reportTasks/123） 从 reportTasks.create 回复中收到了说明， 举报任务。

示例：

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"
  }
}