本文介绍与使用 Metadata API 访问 Google Analytics(分析)列的列表和属性相关的重要概念。
简介
Metadata API 用于返回 Google Analytics(分析)报告 API 提供的列(例如维度和指标)的列表及属性。如果您刚开始使用该 API,请参阅 Metadata API 概览,简要了解 Metadata API。
开始之前
所有 Google Analytics(分析)API 的访问方式都基本相同。在开始使用 Metadata API 之前,您应该:
每个客户端库均提供一个可以访问所有 Metadata API 数据的 Google Analytics(分析)服务对象。要创建与 Metadata API 配合使用的服务对象,您通常需要完成以下步骤:
- 在 Google API 控制台中注册您的应用。
- 创建一个 Google Analytics(分析)服务对象,并设置 API 密钥。
注册和 API 密钥
您的应用需要在每次向 Google Analytics(分析)API 发出请求时标识自身的身份,即在每个请求中附上 API 密钥。
获取和使用 API 密钥
要获取 API 密钥,您需要按以下步骤操作:
- 打开 API 控制台中的“凭据”页面。
- 此 API 支持两种类型的凭据。创建适合您的项目的凭据:
-
OAuth 2.0:如果您的应用请求用户私密数据,则必须随请求一道发送 OAuth 2.0 令牌。要获得令牌,您的应用应先发送客户端 ID,可能的话,还要发送客户端密钥。您可以为网络应用、服务帐号或已安装应用生成 OAuth 2.0 凭据。
注意:由于此 API 没有任何方法需要 OAuth 2.0 授权,因此您可能只需要获取 API 密钥,如下所述。但是,如果您的应用调用需要用户授权的其他 API,那么您仍然需要 OAuth 2.0 凭据。
详细信息,请参阅 OAuth 2.0 文档。
-
API 密钥:未提供 OAuth 2.0 令牌的请求必须发送 API 密钥。该密钥用于标识您的项目,并提供 API 访问权限、配额和报告。
API 支持多种类型的 API 密钥限制条件。如果您需要的 API 密钥尚未存在,请在控制台中创建 API 密钥,方法是:点击创建凭据 > API 密钥。您可以先对密钥设定相关限制,然后再在实际工作环境中使用密钥,方法是:点击限制密钥,然后选择限制条件之一。
-
为保障 API 密钥的安全,请遵循安全使用 API 密钥的最佳做法。
在您获得 API 密钥后,您的应用便可将查询参数 key=yourAPIKey
添加到所有请求网址中。
API 密钥可以安全地嵌入网址中;不需要进行任何编码。
下面的代码段展示了如何为各种不同的客户端库设置 API 密钥。
Java
import com.google.api.client.json.jackson2.JacksonFactory; import com.google.api.client.http.javanet.NetHttpTransport; import com.google.api.services.analytics.Analytics; import com.google.api.services.analytics.AnalyticsRequestInitializer; public class ApiKeySample { private static final String API_KEY = "YOUR API KEY"; public static void main(String[] args) { NetHttpTransport netHttpTransport = new NetHttpTransport(); JacksonFactory jacksonFactory = new JacksonFactory(); // Set the API Key AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY); // Build the Analytics Service object Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null) .setAnalyticsRequestInitializer(analyticsInitializer) .setApplicationName("ApiKeySample") .build(); // Start coding cool things. } }
Python
from apiclient.discovery import build API_KEY = 'YOUR API KEY' def main(argv): # Set the API Key and build the Analytics service object. service = build('analytics', 'v3', developerKey=API_KEY) # Start coding cool things.
PHP
require_once 'google-api-php-client/src/Google_Client.php'; require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php'; const API_KEY = 'YOUR API KEY' $client = new Google_Client(); // Set the API Key $client->setDeveloperKey($API_KEY); // Build the Analytics Service object. $analytics = new google_AnalyticsService($client); // Start coding cool things.
JavaScript
<!-- Method 1: Using the Google APIs Client Library for JavaScript --> <script> var apiKey = 'YOUR API KEY'; function handleClientLoad() { gapi.client.setApiKey(apiKey); gapi.client.load('analytics', 'v3', makeRequest); } function makeRequest() { // Start coding cool things. } </script> <script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script> <!-- Method 2: Using REST and callback parameter --> <script> function render() { // Place your awesome code here. } </script> <!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. --> <script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>
列属性
Metadata API 响应包含一个列出所有有效列属性的 attributeNames
属性。每列都含有一个 attributes
属性,该属性包含适用于该列的一个属性子集。
下表列出了所有有效的属性:
使用情形
Metadata API 可用于处理以下应用示例:
弃用的列
如果某个列(例如某个维度或指标)现已弃用,则其 status
属性将设置为 DEPRECATED
。
以下代码段展示如何使用 status
属性检查列是否已弃用:
function isDeprecated(column) { return column.attributes.status == 'DEPRECATED'; }
如果某个列已重命名/移除,则其 status
属性将设置为 DEPRECATED
,并且可能具有设置为替代列 Id
的 replacedBy
属性。
以下代码段展示如何使用 replacedBy
属性获取替代列的 Id:
function getReplacementId(column) { return column.attributes.replacedBy; }
列名称
uiName
属性是 Google Analytics(分析)用户界面(例如网络界面)中使用的维度名称或指标名称。
以下代码段展示如何获取列的 UI 名称:
function getColumnName(column) { return column.attributes.uiName; }
模板化列
模块化列包含带数字索引的维度或指标,例如 ga:goalXXStarts
、ga:dimensionXX
、ga:metricXX
等等。模块化列具有定义索引范围的 minTemplateIndex
和 maxTemplateIndex
属性。
以下代码段展示如何检查某个列是否为模块化列:
function isTemplatized(column) { return !!column.attributes.minTemplateIndex || !!column.attributes.maxTemplateIndex; }
以下代码段展示如何为模块化列获取有效 ID 的列表:
function getTemplatizedIdList(column) { var columnIdList = []; var columnId = column.id; if (isTemplatized(column)) { minIndex = parseInt(column.attributes.minTemplateIndex); maxIndex = parseInt(column.attributes.maxTemplateIndex); for (var i = minIndex; i <= maxIndex; i++) { columnIdList.push(columnId.replace('XX', i)); } } return columnIdList; }
计算列
通过对其他的列进行计算而得到的列将具有 calculation
属性。例如,ga:percentNewSessions
的计算结果为 ga:newSessions / ga:sessions
。
以下示例展示如何检查某个列是否为计算列,以及如何获取列的计算结果:xample shows how to check if a column is calculated and how to retrieve the calculation for a column:
function isCalculated(column) { return !!column.attributes.calculation; } function getCalculation(column) { return column.attributes.calculation; }
列和细分
利用 allowedInSegments
属性,您可以验证是否可以在细分查询参数中使用某个列。
以下示例展示如何确定是否可以在细分中使用某个列:
function isAllowedInSegments(column) { return !!column.attributes.allowedInSegments; }
在 API 版本中添加
使用 addedInApiVersion
属性来检查某个列是否可以用在指定版本的 reporting API 中。例如,可调用下面的函数来验证此列可以用在 Core Reporting API V3 中:
function isAllowedInV3(column) { return column.attributes.addedInApiVersion < 4; }
ETag
每个 Metadata API 响应中都包含有 ETag。ETag 是一种标识符,可用于对 Metadata API 响应进行缓存和更新。这种标识符非常重要,因为列(例如维度和指标)数据可能会长期保持不变,而且在可以使用缓存数据时进行不必要的请求和更新是非常低效的。
如果您存储了一个列集合的 ETag,则主要可以通过两种方式来使用该 ETag:检查缓存的 Metadata API 响应是否为最新,以及将其加入 Metadata API 请求中。
检查缓存的响应
如果在比较 Metadata API 响应返回的 ETag 值时,发现其与缓存资源的 ETag 相同,则缓存版本为最新。如果两个 ETag 不相同,则应更新您的应用,并使用最新的响应刷新缓存。
如果您只想提取 Metadata API 的 ETag 值,则应在发出请求时,将 fields 查询参数设置为 etag
。查看示例。
将 ETag 与 API 请求配合使用
如果您有列集合的缓存版本,则可以通过设置 If-None-Match
HTTP 标头字段,将该缓存版本的 ETag 值加入到 Metadata API 请求中。Metadata API 将检查 ETag 值,并在响应中提供相关资源的更新版本及 200 OK
HTTP 状态,或者在空响应中提供 304 Not
Modified
状态(如果您的缓存版本为最新)。