Metadata API - 开发者指南

本文介绍与使用 Metadata API 访问 Google Analytics(分析)列的列表和属性相关的重要概念。

简介

Metadata API 用于返回 Google Analytics(分析)报告 API 提供的列(例如维度和指标)的列表及属性。如果您刚开始使用该 API,请参阅 Metadata API 概览,简要了解 Metadata API。

开始之前

所有 Google Analytics(分析)API 的访问方式都基本相同。在开始使用 Metadata API 之前,您应该:

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

每个客户端库均提供一个可以访问所有 Metadata API 数据的 Google Analytics(分析)服务对象。要创建与 Metadata API 配合使用的服务对象,您通常需要完成以下步骤:

  1. Google API 控制台中注册您的应用。
  2. 创建一个 Google Analytics(分析)服务对象,并设置 API 密钥

注册和 API 密钥

您的应用需要在每次向 Google Analytics(分析)API 发出请求时标识自身的身份,即在每个请求中附上 API 密钥

获取和使用 API 密钥

要获取 API 密钥,您需要按以下步骤操作:

  1. 打开 API 控制台中的“凭据”页面
  2. 此 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,并且可能具有设置为替代列 IdreplacedBy 属性。

以下代码段展示如何使用 replacedBy 属性获取替代列的 Id:

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

列名称

uiName 属性是 Google Analytics(分析)用户界面(例如网络界面)中使用的维度名称或指标名称。

以下代码段展示如何获取列的 UI 名称:

function getColumnName(column) {
  return column.attributes.uiName;
}

模板化列

模块化列包含带数字索引的维度或指标,例如 ga:goalXXStartsga:dimensionXXga:metricXX 等等。模块化列具有定义索引范围的 minTemplateIndexmaxTemplateIndex 属性。

以下代码段展示如何检查某个列是否为模块化列:

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 状态(如果您的缓存版本为最新)。