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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

はじめに

Metadata API は、Google アナリティクスの Reporting 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 については後述します。ただし、ユーザー認証を必要とする他の API を アプリケーションで呼び出す場合は、OAuth 2.0 認証情報が必要となります。

      詳細については、OAuth 2.0 ドキュメントをご覧ください。

    • API キー: OAuth 2.0 トークンを提供しない場合は、API キーを送信する必要があります。キーによりプロジェクトが識別され、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: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 属性を使用して、指定したバージョンの Reporting API で列を使用できるかどうかを確認します。たとえば、次の関数を呼び出して、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 を使用する

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