“非抽样报告”开发者指南

利用 Google Analytics(分析)Management API,您可以通过编程方式生成非抽样报告。

简介

非抽样报告指的是利用非抽样数据生成的 Google Analytics(分析)报告。非抽样报告目前仅面向 Google Analytics Premium 用户提供。

通过此 API,您可以:

  • 获取有关您现有的所有非抽样报告的配置信息。 生成一次性的非抽样报告。
  • 查看非抽样报告的处理状态。
  • 在完成处理之后获得非抽样报告的数据文件的链接。
  • 删除非抽样报告。

获取非抽样报告的数据

当您创建非抽样报告时,可能要经过一段时间后才能下载报告。非抽样报告的 status 字段指出是否已完成对该报告的处理。如果状态已标记为 COMPLETED,您可以使用 downloadType 和相应的下载详细信息字段获取包含报告数据的文件。例如:

不要使用连续的高频次轮询来查看报告状态,因为这样做的话您的每日配额可能很快就会耗尽。查看非抽样报告的状态时,在各个请求之间应该要有一定的间歇。

使用 Google Drive / Google Cloud Storage API

根据您的文件要传送到哪里(Google 云端硬盘或 Google 云端存储),您将获得该文件的相应链接。通过该链接,您可以使用 Drive API 或 Cloud Storage API 下载文件。有关如何提取文件的更多详情,请参阅 Google Drive APIGoogle Cloud Storage API 文档。

例如,如果您的非抽样报告保存在 Google 云端硬盘中,则可以对相关文件的资源网址发出未授权的 HTTP GET 请求,并在其中加入查询参数 alt=media

GET /drive/v2/files/XXXXXX?alt=media
Host: www.googleapis.com
Content-length: 0
Authorization: Bearer ya29.AHESVbXTUv5mHMo3RYfmS1YJonjzzdTOFZwvyOAUVhrs

其中,XXXXXX 代表非抽样报告 driveDownloadDetails.documentId

身份验证

如果您计划将“非抽样报告”与 DriveCloud Storage API 结合使用,以便进行文件下载,您在请求 OAuth 2.0 令牌时需要包含该 API 的相应验证范围(以及 Google Analytics(分析)API 验证范围)。这样您就可以对两个 API 都使用相同的验证令牌。

删除非抽样报告

您可以删除定期生成的非抽样报告或已完成的非抽样报告,但是在生成报告的短暂过程中内调用 delete 会导致出错。删除非抽样报告只是从您的 Google Analytics(分析)数据视图(配置文件)中移除相应的资源,保存在 Google 云端硬盘或 Google 云端存储中的已导出数据将被保留。

限制

以下限制适用于生成非抽样报告:

  • 您只可以指定 4 个维度。
  • 某些报告数据类型不受支持,例如 AdWords 数据
  • 不支持系统认为费用太高的查询。

如果您的请求被系统判定为花费过高,创建操作将返回错误以及相应的消息。如果发生这种情况,您可以:

  • 减少所请求的维度。
  • 将查询分拆成几个日期范围较小的查询,然后将生成的报告拼合起来。

使用情形

非抽样报告和 Core Reporting API

如果您使用 Core Reporting API 来获取报告数据,并且其中包含抽样数据,那么您可以针对同一查询生成非抽样报告:

  1. 发出一个 Core Reporting API 请求。
  2. 在响应中,查看 containsSampledData 属性以了解数据是否经过抽样。
  3. 如果属性被设为 true,您可以利用同一响应中的 query 和 profileInfo 字段来创建一个针对非抽样报告的请求。

Core Reporting API 响应中的 query 字段示例:

"query": {
  "start-date": "2011-01-01",
  "end-date": "2011-01-31",
  "ids": "ga:1234",
  "dimensions": "ga:browser",
  "metrics": [
  "ga:visits"
  ],
  "filters": "ga:country==US",
  "start-index": 1,
  "max-results": 1000
}

Core Reporting API 响应中的 profileInfo 字段示例:

"profileInfo": {
  "profileId": "1234",
  "accountId": "12345",
  "webPropertyId": "UA-12345-1",
  "internalWebPropertyId": "11254",
  "profileName": "Name of the profile",
  "tableId": "ga:1234"
}

下面的例子介绍了如何从 Core Reporting API 响应中生成非抽样报告:

Java

// Make a Core Reporting API call.
GaData reportingApiData = v3.data().ga().get(...).execute();

// Check if the response is sampled.
if (reportingApiData.getContainsSampledData()) {

  // Use the “query” object to construct an unsampled report object.
  Query query = reportingApiData.getQuery();
  UnsampledReport report = new UnsampledReport()
      .setDimensions(query.getDimensions())
      .setMetrics(Joiner.on(',').join(query.getMetrics()))
      .setStartDate(startDate)
      .setEndDate(endDate)
      .setSegment(query.getSegment())
      .setFilters(query.getFilters())
      .setTitle(“My unsampled report”);

  // Use “profileInfo” to create an InsertRequest for creating an
  // unsampled report.
  ProfileInfo profileInfo = reportingApiData.getProfileInfo();
  Insert insertRequest = analytics.management().unsampledReports()
  .insert(profileInfo.getAccountId(),
          profileInfo.getWebPropertyId(),
          profileInfo.getProfileId(),
          report);
  UnsampledReport createdReport = insertRequest.execute();
}

拼合多个日期的非抽样数据

您可以通过组合或拼合多个日期的报告,来获取某个日期范围的非抽样数据。当非抽样数据请求过于庞大时,这种做法非常有用。这种情况下,您可以将请求分拆成多个日期范围较短的请求,然后将返回的结果组合起来。

配额政策

请参阅配置和报告 API 的限制和配额,查看适用于生成非抽样报告的限制与配额的完整列表。