本文說明使用 Metadata API 存取 Google Analytics (分析) 資料欄清單和屬性的重要概念。
簡介
Metadata API 會傳回在 Google Analytics (分析) 報表 API 中公開的資料欄 (例如維度和指標) 清單及其屬性。如果您是第一次使用 API，請參閱 Metadata API 總覽，瞭解 Metadata API。
事前準備
所有 Google Analytics (分析) API 的存取方式都很類似。開始使用 Metadata API 之前，請先完成下列事項：
每個用戶端程式庫都提供一個數據分析服務物件，方便您存取所有 Metadata API 資料。如要建立與 Metadata API 搭配使用的服務物件，通常必須完成下列步驟：
- 在 Google API 控制台中註冊應用程式。
- 建立 Analytics (分析) 服務物件並設定 API 金鑰。
註冊和 API 金鑰
您的應用程式每次傳送要求至 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。
以下範例說明如何檢查資料欄是否計算完成，以及如何擷取資料欄的計算：
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 第 3 版中使用：
function isAllowedInV3(column) {
return column.attributes.addedInApiVersion < 4;
}
ETag
每個 Metadata API 回應都包含 ETag。ETag 是可用於快取及更新 Metadata API 回應的 ID。這點非常重要，因為欄 (即維度和指標) 資料長時間保持不變，且在使用快取資料時，無法做出不必要的要求和更新。
如果您儲存了 資料欄集合的 ETag，則主要可透過以下 2 種方式使用：檢查快取的 Metadata API 回應是否為最新狀態，並將該回應納入中繼資料 API 要求中。
檢查快取回應
如果您比較 Metadata API 回應傳回的 ETag 值，且此值相當於快取資源的 ETag，就表示快取版本為最新版本。如果 ETag 不相同，請更新應用程式，並使用最新的回應重新整理快取。
如果只想從 Metadata API 擷取 ETag 值，請在提出要求時將「fields」
查詢參數設為 etag。
查看範例。
搭配使用 ETag 與 API 要求
如有資料欄集合的快取版本，則可設定 If-None-Match HTTP 標頭欄位，將其 ETag 值加入中繼資料 API 要求中。Metadata API 會檢查 ETag 值，並以更新後的資源版本及 200 OK HTTP 狀態做出回應，如果您的快取版本為最新版本，則會傳回含有 304 Not
Modified 狀態的空白回應。