本文介绍与使用 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
,并且其 replacedBy
属性可能会设置为替换列的 Id
。
以下代码段展示了如何使用 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 标头字段,在 Metadata API 请求中包含其 ETag 值。Metadata API 将检查 eSIM 卡值,并在响应时提供资源的更新版本和 200 OK
HTTP 状态,或者以 304 Not
Modified
状态响应空响应(如果您的缓存版本为最新)。