Python Tips: Google Analytics Data API v1 に移行したい

2023/01/16

Google Analytics Reporting API を使用するコードを Google Analytics Data API v1 (beta) に移行する方法についてかんたんにまとめました。

おさらい

Google Analytics Universal Analytics とは

旧来の Google Analytics のこと。 2020 年 10 月まではデフォルトプロパティだったが、現在は後継の Google Analytics 4 がデフォルトになっている。 2023 年 7 月 1 日に新たなデータの処理を停止する予定。

About Universal Analytics - Analytics Help

Universal Analytics のタグには UA- から始まる「トラッキング ID 」が使用される（例: UA-1234567890-1 ）。以下「 UA 」。

Google Analytics 4 とは

2019 年に登場した新しい Google Analytics で UA の後継サービス。

A new way to unify app and website measurement in Google Analytics

Google Analytics 4 のタグには G- から始まる「測定 ID 」が使用される（例: G-A1A1A1A1A ）。以下「 GA4 」。

Google Analytics Reporting API とは

Google Analytics のデータを取得できる API 。 旧来の Universal Analytics 専用で、 GA4 には対応していない 。以下「 Reporting API 」。

Google Analytics Data API v1 とは

Reporting API と同じく Google Analytics のデータを取得できる API 。 新しい GA4 専用で、旧来の UA には対応していない 。記事執筆時点で beta 版まで出ているが正式版は出ていない。以下「 Data API v1 」。

対応関係

UA は Reporting API のみ、 GA4 は Data API v1 のみに対応している。

名称	Reporting API	Data API v1
Universal Analytics (UA)	○	×
Google Analytics 4 (GA4)	×	○

Universal Analytics will be going away - Analytics Help

新しい GA4 に対応しているのは Data API v1 だけなので、いま Reporting API を利用している企業や個人は Data API v1 に移行する必要があります。

前提

移行の前提として以下が完了しているものとします。

GA4 用の計測タグの設置
Google Cloud Platform （以下「 GCP 」）のプロジェクトの用意

動作確認時のバージョン

Python: 3.11.1
google-analytics-data: 0.16.0

Reporting API から Data API v1 への移行

公式ドキュメントの説明のとおりに作業を行います:

Analytics Data API Overview | Google Analytics Data API | Google Developers

Reporting API との利用面でのちがいは次のとおりです:

API	使用する ID	PyPI パッケージ
Reporting API	ビュー ID	`google-api-python-client` + `google-auth`
Data API v1	プロパティ ID	`google-analytics-data`

大まかな流れは次のとおりです:

Data API v1 を有効にする
Data API v1 をサービスアカウントで利用できるようにする
サービスアカウントを GA4 のプロパティに追加する
サービスアカウント credentials JSON ファイルをダウンロードする
必要なクライアントライブラリをインストールする
試しに API を叩く
必要なデータを取得するように調整する

以下順に説明します。

1. Data API v1 を有効にする

GCP コンソールで Data API v1 を有効にします。私の環境では GCP のメニューの次のところで設定できました:

日本語:

API とサービス → 有効な API とサービス → Google Analytics Data API

英語:

API & Services → Enabled APIs & services → Google Analytics Data API

API / サービスの詳細 – API とサービス | Google Cloud コンソール

もし Data API v1 を少し触ってみたいだけなら、公式ドキュメントの「 API Quickstart 」のページの「 Enable the Google Analytics Data API v1 」から進むと最初の数ステップを短縮できるらしいのでこれを利用するとよいかと思います:

API Quickstart | Google Analytics Data API | Google Developers

2. Data API v1 をサービスアカウントで利用できるようにする

Data API v1 を有効にしたら、続いてサービスアカウントをその利用者として追加します。具体的には、 GCP コンソールの Data API v1 の詳細ページの「認証情報」タブのところから実施します:

Google Analytics Data API 認証情報

既存のアカウントではなく新しいサービスアカウントを使いたい場合は先にサービスアカウントを作成してから Data API v1 の利用者として追加しましょう。

3. サービスアカウントを GA4 のプロパティに追加する

前のステップで Data API v1 の利用者として追加したサービスアカウントを、次は GA4 の方でプロパティのユーザーとして追加します。私の環境では Analytics 管理 UI から次のように辿ったところで行えました:

英語:

Admin → Property Access Management → Add users

Google Analytics Property access management

参考:

Add, edit, and delete users and user groups - Analytics Help

後で API を叩くときに GA4 のプロパティ ID が必要になるので、ここで管理画面を開いたついでにプロパティ ID （ 9 桁の数）をコピーして手元に控えておくと二度手間が防げます。私の環境では Analytics 管理 UI から次のように辿ったところで取得できました（プロパティ ID は他にも各所で表示されています）:

英語:

Admin → Property Settings → PROPERTY ID

4. サービスアカウント credentials JSON ファイルをダウンロードする

前のステップでユーザーとして設定したサービスアカウントの credentials JSON ファイルをダウンロードします。私の環境では GCP のダッシュボードから次のように辿ったところで行えました:

日本語:

IAM と管理 → サービスアカウント → （対象のサービスアカウントの詳細ページ） → キー → 鍵を追加 → 新しい鍵を作成

英語:

IAM & Admin → Service accounts → （対象のサービスアカウントの詳細ページ） → Keys → Add key → Create new key

ここは Reporting API と共通なのですでにダウンロードしてあれば改めてダウンロードする必要はありません。

5. 必要なクライアントライブラリをインストールする

PyPI パッケージ google-analytics-data をインストールします。

python -m pip install google-analytics-data

GitHub - googleapis/python-analytics-data

Reporting API のときは google-api-python-client と google-auth など複数のライブラリを指定してインストールする必要がありましたが、 Data API v1 の場合は google-analytics-data 1 つだけで OK です（ google-api-core や google-auth など必要なものは依存ライブラリとして自動的にインストールされます）。

6. 試しに API を叩く

ステップ 5 でダウンロードした credentials JSON ファイルとステップ 6 でインストールした google-analytics-data 、それとプロパティ ID を使って実際に API を叩きます。

次のサンプルは公式のサンプルを少し改変したものです。 CREDENTIALS_PATH と PROPERTY_ID の行を環境にあわせて適切なものに変更すれば動くはずです。私の環境では動きました。

from pathlib import Path

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    RunReportRequest,
    OrderBy,
)

# ここを変更してください:
CREDENTIALS_PATH = Path(__file__).resolve().parent / "credentials.json"
PROPERTY_ID = "123456789"


def main():
    sample_run_report(CREDENTIALS_PATH, PROPERTY_ID, 20)


def sample_run_report(credentials_path, property_id: str, limit: int):
    """Runs a simple report on a Google Analytics 4 property."""
    client = BetaAnalyticsDataClient.from_service_account_file(credentials_path)

    # セッション数の降順で過去 7 日間のページ別セッション数を取得する
    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[Dimension(name="pagePath"), Dimension(name="pageTitle")],
        metrics=[Metric(name="sessions")],
        date_ranges=[DateRange(start_date="7daysAgo", end_date="today")],
        order_bys=[
            OrderBy(metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True)
        ],
        limit=limit,
    )
    response = client.run_report(request)

    print("Report result:")
    dimension_headers = response.dimension_headers
    metric_headers = response.metric_headers
    for row in response.rows:
        dim_map = _map_of_values(dimension_headers, row.dimension_values)
        met_map = _map_of_values(metric_headers, row.metric_values)

        print(dim_map, met_map)


def _map_of_values(headers, values) -> dict:
    return {k: v for k, v in zip((x.name for x in headers), (x.value for x in values))}


if __name__ == "__main__":
    main()

公式のサンプルでは credentials JSON ファイルのパスを環境変数 GOOGLE_APPLICATION_CREDENTIALS を経由して BetaAnalyticsDataClient に渡していますが、ここでは変数 CREDENTIALS_PATH で明示的に渡すようにしています。そのために BetaAnalyticsDataClient インスタンス生成方法を次のように変更しています。

公式:

client = BetaAnalyticsDataClient()

本記事:

client = BetaAnalyticsDataClient.from_service_account_file(credentials_path)

公式のサンプル:

Python | API Quickstart | Google Analytics Data API | Google Developers

7. 必要なデータを取得するように調整する

前のステップで無事にレポートデータが取得できることが確認できたら、後は必要なデータを取得するようにリクエストコードを調整すれば OK です。

API の具体的な使い方について公式の情報はあまり豊富ではないので、多くの場合は公式のリファレンスを見ながら手探りで実装する必要があるものと思います:

Python Client for Analytics Data API — google-analytics-data documentation

上述のとおり直接利用するライブラリは google-analytics-data だけになるので、 Poetry などのパッケージマネージャを利用している場合は google-api-python-client や google-auth は dependencies から外してしまって OK です。

以上です。

上のサンプルを少し整えて GitHub Gist に置きました:

Sample: Getting session data of GA4 with Python and google-analytics-data · GitHub

参考

⟨ Python の標準ライブラリだけで … dataclasses.asdict(…⟩