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

本文介绍了如何使用 Management API 来管理非抽样报告。

简介

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

通过此 API,您可以:

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

开始之前

本指南说明了如何使用以下编程语言来访问 Google Analytics(分析)API:
  • Java
  • Python
  • PHP

  • 请阅读客户端库页面,查看与 Management API 配合使用的编程语言客户端库的完整列表。
  • 请阅读参考指南,了解如何在没有客户端库的情况下访问该 API

每个客户端库提供单个 Analytics 服务对象来访问所有的 Management API 数据。要创建服务对象,您通常需要完成以下步骤:

  1. Google Developers Console 中注册您的应用。
  2. 授予访问 Google Analytics(分析)数据的权限。
  3. 创建一个 Analytics 服务对象。

如果您未能完成上述步骤,请停止操作,并阅读 Google Analytics(分析)API 入门教程。该教程将为您详细介绍构建 Google Analytics(分析)API 应用的最初几个步骤。完成这些步骤后,您就可以使用本指南执行实际任务了。

以下代码段从第 3 步(创建一个 Analytics 服务对象)继续,包含一个用来存储已获授权的服务对象的变量。

Java

Analytics analytics = // Read Hello Analytics Tutorial for details.

Python

analytics = # Read Hello Analytics Tutorial for details.

PHP

$client = // Read Hello Analytics Tutorial for details.

// Return results as objects.
$client->setUseObjects(true);

$analytics = new apiAnalyticsService($client);

PHP 库会将所有 API 结果作为一个关联数组来返回。要返回真正的对象,您可以调用客户端 useObject 方法,如上例所示。

创建了 Analytics 服务对象后,您就可以对 Management API 发出请求了。

注意:同一个 Analytics 服务对象也可以用来访问 Core Reporting API

获取非抽样报告的数据

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

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

使用 Google Drive / Google Cloud Storage API

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

身份验证

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

限制

以下限制适用于非抽样报告的创建。

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

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

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

使用情形

非抽样报告和 Core Reporting API

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

此使用情形的操作流程如下:

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

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 字段示例:

Java


"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 的限制和配额,查看适用于创建非抽样报告的限制与配额的完整列表。

代码示例

“非抽样报告”资源让您可以列出、获取和插入授权用户的非抽样报告。要使用其中的任意一种方法,您首先需要创建一个 Analytics 服务对象,如开始之前部分所述。

要查看代码示例,了解如何使用“非抽样报告资源,请访问下面的方法参考:

  • list — 列出用户有访问权限的非抽样报告。
  • get — 获取用户有访问权限的非抽样报告。
  • insert — 创建新的非抽样报告。