Metadata API - デベロッパー ガイド

このドキュメントでは、Metadata API を使用して Google アナリティクスの列の一覧と属性にアクセスする方法についての重要な概念について説明します。

はじめに

Metadata API は、Google アナリティクス Reprting API で使用される列(ディメンションと指標)とその属性の一覧を返します。API を初めて使用する方は、Metadata API の概説について Metadata API の概要をご覧ください。

準備

Google アナリティクス API はすべて、同じ方法でアクセスできます。Metadata API を使用する前に、以下の準備をしてください。

  • API で利用可能なすべてのプログラミング言語ごとのクライアント ライブラリの一覧を、クライアント ライブラリ ページで確認します。
  • API インターフェースと、クライアント ライブラリを使わずにデータにアクセスする方法についてリファレンス ガイドで確認します。

各クライアント ライブラリでは、すべての Metadata API データにアクセスするための 1 つの Analytics サービス オブジェクトを提供します。Metadata API で 使用するサービス オブジェクトを作成するには、通常、次の手順 に従います。

  1. お使いのアプリケーションを Google API コンソールで登録します。
  2. Analytics サービス オブジェクトを作成し、API キー を設定します。

登録と API キー

アプリケーションは、アナリティクス API にリクエストを送信するたびに身元を証明する必要があるため、各リクエストに API キーを含めます。

API キーの取得と使用

API キーを取得するには:

  1. API コンソールで [認証情報] ページ を開きます。
  2. この API では、2 種類の認証情報がサポートされています。 自分のプロジェクトに必要な、いずれかの認証情報を作成します。
    • 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 キーを作成すると、アプリケーションではすべてのリクエスト URL の末尾にクエリ パラメータ key=yourAPIKey を追加できます。

API キーは URL に安全に埋め込むことができます。エンコーディングは不要です。

以下のコード スニペットでは、各クライアント ライブラリごとに 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 アナリティクスのユーザー インターフェース(管理画面など)で使用される、ディメンションまたは指標の名前です。

次のスニペットで、列の UI 名を取得する方法を示します。

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

テンプレート化された列

テンプレート化された列には、インデックス番号が付いたディメンションまたは指標が含まれます。たとえば、ga:goalXXStartsga:dimensionXXga: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:percentNewSessionsga: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 バージョンで追加

指定されたバージョンの Reporting API で列が使用可能かどうかを確認 するには、addedInApiVersion 属性を使用します。たとえば、 Core Reporting API V3 で列が使用可能かどうかを確認するには、 以下の関数を呼び出します。

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

ETag

ETag はすべての Metadata API レスポンスに含まれます。ETag は Metadata API レスポンスのキャッシュと更新に使用できる識別子です。これは重要です。なぜなら、列(ディメンションと指標)のデータは長期間変更せずに維持できるため、キャッシュされたデータを使用できる場合に不要なリクエストや更新を行うのは非効率的だからです。

列コレクションの ETag を格納すると、ETag は、主にキャッシュされた Metadata API レスポンスが最新の状態であるかどうかを確認するため、また、Metadata API リクエストの一部に含めるために使用されます。

キャッシュされたレスポンスを確認する

キャッシュされたリソースの ETag が、Metadata API レスポンスから返された ETag 値と同じ場合、キャッシュされたバージョンは最新です。ETag 値が同じではない場合は、アプリケーションを更新し、最新のレスポンスでキャッシュを更新してください。

Metadata API から ETag 値のみを取得したい場合は、リクエストを行う際に、fields クエリ パラメータを etag に設定します。例をご覧ください

API リクエストで ETag を使用する

列コレクションのキャッシュされたバージョンを保持している場合は、HTTP の If-None-Match ヘッダー フィールドを設定することで、その ETag 値を Metadata API リクエストに含めることができます。Metadata API は、ETag 値を確認し、リソースの更新されたバージョンと 200 OK の HTTP ステータスを含む応答を返すか、キャッシュされたバージョンが最新の場合は 304 Not Modified の HTTP ステータスを含む空の応答を返します。