开发者指南

本文介绍了如何使用 Real Time Reporting API 获取 Google Analytics(分析)数据。

简介

利用 Real Time Reporting API,您可以针对媒体资源当前发生的活动生成报告。要访问实时数据,您需要创建指定以下内容的查询:数据视图(配置文件)及至少一个指标。您也可以提供更多查询参数(例如,维度和过滤条件)对查询进行细化。此查询将会发送给 Real Time Reporting API,然后 Real Time Reporting API 会以表格形式返回相关数据。

如果您刚开始使用该 API,请参阅 Real Time Reporting API 概览,简要了解 Real Time Reporting API 及其提供的数据。

前提条件

在使用 Real Time Reporting API 获取 Google Analytics(分析)数据前:

  • 请参阅客户端库页面,查看与该 API 配合使用的编程语言专用客户端库的完整列表。
  • 阅读参考指南,了解如何仅使用 API(不使用客户端库)获取 Google Analytics(分析)数据。

每个客户端库均会提供一个可以访问所有 Real Time Reporting API 数据的分析服务对象。要创建服务对象,请执行以下操作:

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

如果您未能完成上述步骤,请停止操作,并阅读 Hello Google Analytics(分析)API 入门教程,该教程将为您详细介绍构建 Google Analytics(分析)API 应用的最初几个步骤。之后您就可以了解如何使用 API 获取 Google Analytics(分析)数据。

使用 Real Time Reporting API

要使用 Real Time Reporting API,应用需要:

  1. 查询 Real Time Reporting API。
  2. 处理 API 响应。

查询 Real Time Reporting API

分析服务对象提供了创建 Real Time Reporting API 查询的方法。有关查询参数和 API 可用数据的详细信息,请阅读:

当您定义完查询后,可以调用 execute 方法,将该查询发送给 Google Analytics(分析)服务器。

处理 API 响应

如果对 Real Time Reporting API 的查询成功,API 会返回所请求的数据,作为实时数据资源的一部分。有关 API 响应结构和格式的详情,请参阅 Real Time Reporting API 参考

如果出现任何错误,则 API 会返回特定的状态代码和一条说明错误的消息。所有应用均应捕捉并处理错误。有关错误及建议的重试措施的详尽列表,请参阅错误响应

代码示例

实时数据:get 页的示例部分包含各种编程语言的示例代码,用于查询 Real Time Reporting API 并处理 API 响应。

查询限制

以下是 Real Time API 查询的限制:

  • 如果 rt:activeUsers 指标随以下维度过滤条件一起包含在查询中,则仅支持 AND 运算符和等式匹配类型 (==)。
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    由于 rt:activeUsers 指标只检索当前网站的活动用户数,请勿将 rt:minutesAgort:activeUsers 一起使用。也就是说,rt:activeUsers 意味着 rt:minutesAgo 是 0。

  • 不支持指标过滤条件。
  • 不支持 fields 参数。

配额管理

限制和配额中所述,Real Time Reporting API 与其他 Google Analytics(分析)API 共享 API 每日配额。如果您以较短的周期对 Real Time Reporting API 进行轮询,则很快就会达到每日配额上限。如果发生这种情况,来自其他 Google Analytics(分析)API 的请求也会失效,直至配额重新刷新后才会恢复有效。

很快会用尽配额的一些典型做法包括:

  • 您每天通过多个实时信息中心,以非常短的周期查询单个 Google Analytics(分析)数据视图(配置文件)的数据。
  • 您拥有一个用户众多的媒体资源,并且实现了一个实时小部件。每次向用户显示该小部件时,您都会直接查询 Google Analytics(分析),而不使用缓存。

为最大限度减少配额用量并高效地管理配额:

  • 实现服务器端缓存。当多个用户请求相同的实时数据时,您应返回缓存的响应,而不要针对每个用户请求直接查询 Real Time Reporting API。然后,按照合理的刷新周期(防止超出每日配额上限),使用最新的实时数据定期刷新缓存。
  • 通过指定其他维度,然后在服务器端或客户端解析响应,将多个查询合并在一起。
  • 加大请求实时数据的时间间隔。

示例:计算刷新周期

如果您希望定期请求实时数据,应根据您的预期配额用量,选择合理的刷新周期。

例如,一个 Google Analytics(分析)数据视图(配置文件)的每日配额上限为 10000 次请求/天。在一天里,如果您希望针对一个数据视图(配置文件),向 Core Reporting API 发出 6000 次查询,那么对于该数据视图(配置文件),您还剩余 4000 次请求的配额。

假设您决定使用 Real Time Reporting API 实现 3 个实时信息中心,它们全天对同一数据视图(配置文件)的实时数据进行查询。每个信息中心每天大约可进行 1333 次查询(4000 次查询/3 个信息中心)。一天有 86400 秒。也就是说,每个信息中心的刷新周期必须大于 65 秒 (86400/1333),这样该数据视图(配置文件)的每日总请求数才能低于每日 4000 次这一上限。