google-analytics-data-api-basics

Google Analytics Data API の使い方

Google Analytics Data API v1beta を使用すると、Google Analytics のレポートデータにプログラムからアクセスできます。カスタマイズしたダッシュボードの構築、レポート作成ワークフローの自動化、Google Analytics データのエンタープライズアプリケーションへの統合が可能です。

Cloud CLI を使用した API の有効化

API 呼び出しを行う前に、Google Cloud プロジェクトで Google Analytics Data API が有効になっていることを確認してください。

gcloud が見つからない場合は、これらのコマンドを実行する前に、Google Cloud CLI をインストールするようユーザーに案内してください。

1. API を有効にする： Cloud CLI（gcloud）を使用して analyticsdata.googleapis.com を有効にします。

   gcloud services enable analyticsdata.googleapis.com --quiet
   

   理由：API を有効にすると、Google Analytics レポートの実行に必要なクォータと権限が Cloud プロジェクトに割り当てられます。

2. API が有効になっていることを確認する：

   gcloud services list --enabled --filter="analyticsdata.googleapis.com"
   

認証

API リクエストを認証するには、アプリケーションのデフォルト認証情報（ADC）を生成し、アカウントに必要なスコープを付与する必要があります。ターミナルで次のコマンドを実行してください。

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

理由：これにより、必要な Cloud Platform と Google Analytics の読み取り専用スコープを使って、ローカル環境に ADC が設定されます。クライアントライブラリはこれを使ってリクエストを自動的に認証できます。

Data API レポートの作成（v1beta）

レポートを作成するには、公式の Google Analytics Data クライアントライブラリを使用します。安定性を確保し、最新の Google Analytics レポート機能を利用するため、常に API の v1beta バージョンを優先してください。

重要

エージェントへの必須指示： ユーザーが特定のプログラミング言語を選択または指定した場合は、以下に記載されている references/ 内の対応するクライアントライブラリ設定ガイドを読んでください。

対応クライアントライブラリ

Python

Python 用の Google Analytics Data API クライアントライブラリをインストールまたは設定する必要がある場合は、セットアップガイドを読んでください。

• Python インストールリファレンス (パッケージ： google-analytics-data)

Java

Java 用の Google Analytics Data API クライアントライブラリをインストールまたは設定する必要がある場合は、セットアップガイドを読んでください。

• Java インストールリファレンス (アーティファクト： com.google.cloud:google-cloud-analytics-data)

PHP

PHP 用の Google Analytics Data API クライアントライブラリをインストールまたは設定する必要がある場合は、セットアップガイドを読んでください。

• PHP インストールリファレンス (パッケージ： google/analytics-data)

Node.js

Node.js 用の Google Analytics Data API クライアントライブラリをインストールまたは設定する必要がある場合は、セットアップガイドを読んでください。

• Node.js インストールリファレンス (パッケージ： @google-analytics/data)

Go

Go 用の Google Analytics Data API クライアントライブラリをインストールまたは設定する必要がある場合は、セットアップガイドを読んでください。

• Go インストールリファレンス (パッケージ： cloud.google.com/go/analytics/data/apiv1beta)

.NET

.NET / C# 用の Google Analytics Data API クライアントライブラリをインストールまたは設定する必要がある場合は、セットアップガイドを読んでください。

• .NET インストールリファレンス (パッケージ： Google.Analytics.Data.V1Beta)

Ruby

Ruby 用の Google Analytics Data API クライアントライブラリをインストールまたは設定する必要がある場合は、セットアップガイドを読んでください。

• Ruby インストールリファレンス (Gem： google-analytics-data-v1beta)

メモ

その他のリソース： Java、PHP、Node.js、.NET、Python、REST を使った Data API 呼び出しの追加例や、サービスアカウント認証のヒントについては、公式の Data API クイックスタートを参照してください。

Python クイックスタート

1. クライアントライブラリをインストールします：

   pip install google-analytics-data
   

   pip が利用できない場合は、クライアントライブラリをインストールする前に pip をインストールするようユーザーに案内してください。

2. レポートリクエストを実行します： 以下は、Google Analytics プロパティに対して、 都市と日付ごとにグループ化したアクティブユーザー数とセッション数をクエリする完全な例です。 YOUR-PROPERTY-ID を、実際の Google Analytics プロパティ ID（例： 1234567）に置き換えてください。

   from google.analytics.data_v1beta import BetaAnalyticsDataClient
   from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest
   
   def sample_run_report(property_id: str):
       # クライアントを初期化します。
       # 環境で Application Default Credentials（ADC）が設定されていることを前提とします。
       client = BetaAnalyticsDataClient()
   
       request = RunReportRequest(
           property=f"properties/{property_id}",
           dimensions=[
               Dimension(name="city"),
               Dimension(name="date")
           ],
           metrics=[
               Metric(name="activeUsers"),
               Metric(name="sessions")
           ],
           date_ranges=[
               DateRange(start_date="2026-05-01", end_date="today")
           ],
       )
   
       response = client.run_report(request)
   
       print(f"プロパティ {property_id} のレポート結果：")
       for row in response.rows:
           print(
               f"都市：{row.dimension_values[0].value}, "
               f"日付：{row.dimension_values[1].value}, "
               f"アクティブユーザー数：{row.metric_values[0].value}, "
               f"セッション数：{row.metric_values[1].value}"
           )
   
   if __name__ == "__main__":
       sample_run_report("YOUR-PROPERTY-ID")
   

   理由：BetaAnalyticsDataClient と RunReportRequest を使用すると、 v1beta エンドポイントとの互換性が確保され、型付きのリクエスト検証が行われます。

指標とディメンションのスキーマ

RunReportRequest を作成するときは、ディメンションと指標に有効な API 名を使用する必要があります。 利用可能なフィールドの完全かつ正式な一覧については、公式の Data API スキーマのドキュメント を参照してください。

よく使用されるディメンション

ディメンションは、データのカテゴリ属性を表します。

• city：ユーザーの町または都市。
• country：ユーザーの国。
• date：イベントの日付。形式は YYYYMMDD です。
• deviceCategory：モバイルデバイスのカテゴリ（例：デスクトップ、モバイル、 タブレット）。
• eventName：発生したイベントの名前。
• pageTitle：ウェブページのタイトル。

よく使用される指標

指標は、定量的な測定値を表します。

• activeUsers：アクティブユーザーの数。
• eventCount：イベントの合計数。
• sessions：セッションの合計数。
• screenPageViews：閲覧されたアプリ画面またはウェブページの数。
• totalRevenue：購入、サブスクリプション、広告による総収益。

指標とディメンションの互換性チェック

一部のディメンションと指標は、同じレポートリクエストで一緒にクエリできません。 互換性のないフィールドに関する INVALID_ARGUMENT エラーが発生した場合は、 フィールドの組み合わせを確認してください。Data API スキーマにプログラムからアクセスするには、 getMetadata() を使用します。レポートを実行する前に、特定のディメンションと指標の組み合わせの 互換性をプログラムから確認するには、checkCompatibility() メソッドを使用してください。

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import CheckCompatibilityRequest, Compatibility, Dimension, Metric

def sample_check_compatibility(property_id: str):
    client = BetaAnalyticsDataClient()

    # Define the dimensions and metrics you want to query together.
    # For example, checking if 'itemName' (an e-commerce dimension)
    # is compatible with 'activeUsers' and 'totalRevenue'.
    request = CheckCompatibilityRequest(
        property=f"properties/{property_id}",
        dimensions=[
            Dimension(name="itemName"),
            Dimension(name="date")
        ],
        metrics=[
            Metric(name="activeUsers"),
            Metric(name="totalRevenue")
        ],
    )
    response = client.check_compatibility(request)

    print(f"Compatibility check for property {property_id}:")
    for dim in response.dimension_compatibilities:
        is_compatible = dim.compatibility == Compatibility.COMPATIBLE
        print(f"Dimension '{dim.dimension_metadata.api_name}' is compatible: {is_compatible}")

    for metric in response.metric_compatibilities:
        is_compatible = metric.compatibility == Compatibility.COMPATIBLE
        print(f"Metric '{metric.metric_metadata.api_name}' is compatible: {is_compatible}")

if __name__ == "__main__":
    sample_check_compatibility("YOUR-PROPERTY-ID")