標準のユニバーサルアナリティクス（UA）プロパティでは、2023 年 7 月 1 日をもってデータの処理が停止されました。UA 360 プロパティでは、2024 年 7 月 1 日をもってデータの処理が停止されます。また、Google アナリティクス 4 への移行に伴い、一部の UA 360 の機能はその前にサポート終了となります。Data API を使用して、GA4 プロパティのレポート機能にアクセスします。

このページは Cloud Translation API によって翻訳されました。

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 で使用するサービスオブジェクトを作成するには、通常、次の手順に従います。

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

登録と API キー

アプリケーションは、アナリティクス API にリクエストを送信するたびに、リクエストに API キーを含めることによって、自身を識別する必要があります。

API キーの取得と使用

API キーを取得するには:

API コンソールで [認証情報] ページを開きます。
この 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 キーを安全に使用するためのおすすめの方法に従ってください。

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 プロパティがあります。

次の表は、有効なすべての属性の一覧です。

** appUiName 属性は非推奨です。 appUiName 属性を使用しているコードをすべて削除し、uiName 属性のみを使用する必要があります。属性の削除について詳しくは、データのサポート終了ポリシーをご覧ください。

ユースケース

Metadata API は、次のような場合に活用できます。

サポートが終了した列
列名
テンプレート化された列
計算列
列とセグメント
API バージョン
ETag

廃止される列

列（ディメンションまたは指標）が非推奨になった場合、その status 属性は DEPRECATED に設定されます。

注: アプリケーションでは、Reporting API クエリで DEPRECATED 列を確認し、使用を停止する必要があります。置換用の列が利用可能な場合は、それを使用する必要があります。DEPRECATED 列はサポート終了期間が終了すると Reporting API と Metadata API から削除され、これらの列に対するクエリではエラーが返されます。

次のスニペットは、status 属性を使用して、列が非推奨かどうかをチェックする方法を示しています。

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

列の名前変更または削除が行われると、その status 属性は DEPRECATED に設定され、replacedBy 属性が置換列の Id に設定される場合があります。

次のスニペットは、replacedBy 属性を使用して置換列の ID を取得する方法を示しています。

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

列の名前

uiName 属性は、Google アナリティクスのユーザーインターフェース（ウェブインターフェースなど）で使用されるディメンションまたは指標の名前です。

appUiName 属性は非推奨になりました。appUiName 属性を使用しているコードをすべて削除し、uiName 属性のみを使用する必要があります。属性の削除について詳しくは、データのサポート終了ポリシーをご覧ください。

次のスニペットで、列の 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 バージョンで追加

指定したバージョンの 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 を使用する

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

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

はじめに

準備

登録と API キー

API キーの取得と使用

Java

Python

PHP

JavaScript

列の属性

ユースケース

廃止される列

列の名前

テンプレート化された列

計算列

列とセグメント

API バージョンで追加

ETag

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

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

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