本文介绍了如何使用 Management API 来管理非抽样报告。
简介
非抽样报告指的是利用非抽样数据生成的 Google Analytics(分析)报告。非抽样报告目前仅面向 Google Analytics Premium 用户提供。
通过此 API,您可以:
- 获取有关您现有的所有非抽样报告的配置信息。
- 创建一次性的非抽样报告。
- 查看非抽样报告的处理状态。
- 在完成处理之后获得非抽样报告的数据文件的链接。
开始之前
- Java
- Python
- PHP
每个客户端库提供单个 Analytics
服务对象来访问所有的 Management API 数据。要创建服务对象,您通常需要完成以下步骤:
- 在 Google Developers Console 中注册您的应用。
- 授予访问 Google Analytics(分析)数据的权限。
- 创建一个
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
以及相应的下载详细信息的字段(即:cloudStorageDownloadDetails
或
driveDownloadDetails
)来获取包含报告数据的文件。
我们不使用连续的高频次轮询来查看报告状态,因为这样做的话您的每日配额可能很快就会耗尽。查看非抽样报告的状态时,在各个请求之间应该要有一定的间歇。
使用 Google Drive / Google Cloud Storage API
根据您的文件要传送到哪里(Google 云端硬盘或 Google 云端存储),您将获得该文件的相应链接。通过该链接,您可以使用 Drive API 或 Cloud Storage API 下载文件。有关如何提取文件的更多详情,请参阅 Google Drive API 或 Google Cloud Storage API 文档。
身份验证
如果您计划将“非抽样报告”与 Drive 或 Cloud Storage API 结合使用,以便进行文件下载,您在请求 OAuth 2.0 令牌时需要包含该 API 的相应验证范围(以及 Google Analytics(分析)API 验证范围)。这样您就对两个 API 都使用相同的验证令牌。
限制
以下限制适用于非抽样报告的创建。
- 您只可以指定 4 个维度。
- 某些报告数据类型不受支持,例如 AdWords 数据
- 不支持系统认为费用太高的查询。
如果您的请求被系统判定为花费过高,创建操作将返回错误以及相应的消息。如果发生这种情况,您可以:
- 减少所请求的维度。
- 将查询分拆成几个日期范围较小的查询,然后将生成的报告拼合起来。
使用情形
非抽样报告和 Core Reporting API
如果您使用 Core Reporting API 来获取报告数据,并且其中包含抽样数据,那么您可以针对同一查询创建非抽样报告。
此使用情形的操作流程如下:
- 发出一个 Core Reporting API 请求。
- 在响应中,查看
containsSampledData
属性以了解数据是否经过抽样。 - 如果属性被设为
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
字段示例:
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
服务对象,如开始之前部分所述。
要查看代码示例,了解如何使用“非抽样报告资源,请访问下面的方法参考: