Metadata API - 開發人員指南

本文件說明使用 Metadata API 存取 Google Analytics (分析) 資料欄清單和屬性的重要概念。

簡介

中繼資料 API 會傳回 Google Analytics (分析) 報表 API 中顯示的屬性清單 (也就是維度和指標) 及其屬性。如果您是第一次使用 API,請參閱 Metadata API 總覽,瞭解 Metadata API 簡介。

事前準備

所有 Google Analytics (分析) API 的存取方式都很類似。開始使用 Metadata API 之前,請先完成下列事項:

  • 請參閱用戶端程式庫頁面,瞭解 API 適用的程式設計語言專屬用戶端程式庫完整清單。
  • 請參閱參考指南,進一步瞭解 API 介面,並在沒有用戶端程式庫的情況下存取資料。

每個用戶端程式庫都提供單一數據分析服務物件,以便存取所有 Metadata API 資料。如要建立與 Metadata API 搭配使用的服務物件,通常必須完成下列步驟:

  1. Google API 控制台中註冊應用程式。
  2. 建立 Analytics (分析) 服務物件,並設定 API 金鑰

註冊和 API 金鑰

每次傳送請求給 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,且該 replacedBy 屬性可能設為替代資料欄的 Id

下列程式碼片段說明如何使用 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

以下範例說明瞭如何檢查資料欄是否已計算,以及如何擷取資料欄的計算:

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

欄和區隔

allowedInSegments 屬性可讓您檢查區隔查詢參數中是否能使用某個資料欄。

以下範例說明瞭如何判定是否可在區隔中使用資料欄:

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

已新增至 API 版本

使用 addedInApiVersion 屬性來檢查某欄是否能用於指定版本的報表 API。舉例來說,請呼叫下列函式,確認是否能在 Core Reporting API V3 中使用該資料欄:

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

每個 Metadata API 回應中都包含 ETag。ETag 是一種 ID,可用於快取及更新 Metadata API 回應。這點非常重要,因為資料欄 (即維度和指標) 資料會長時間保留不變,因此如果使用快取資料,就必須進行不必要的請求和更新。

如果您儲存資料欄集合的 ETag,主要可以透過 2 種方式使用:檢查快取 Metadata API 回應是否符合現況,以及是否納入中繼資料 API 要求中。

檢查快取回應

如果您比較從中繼資料 API 回應傳回的 ETag 值,且與快取資源的 ETag 相同,則快取版本就會是最新版本。如果 ETag 不相同,請更新應用程式,並使用最新的回應重新整理快取。

如果您只想從 Metadata API 擷取 ETag 值,請在提出要求時將 fields 查詢參數設為 etag參閲範例

搭配使用 API 要求和 ETag

如果您有資料欄集合的快取版本,則可設定 If-None-Match HTTP 標頭欄位,在中繼資料中繼資料要求中加入其 ETag 值。Metadata API 會檢查 ETag 值,並使用快取版本和 200 OK HTTP 狀態做出回應,如果快取版本為最新版本,則傳回空白回應為 304 Not Modified 狀態。