GA4 Data API (v1beta) の runReport でセッション数とページビューを取得する

概要・目的

Google Analytics 4 (GA4) の公式ライブラリ @google-analytics/data を使って、指定したプロパティの「アクティブユーザー数」「セッション数」「スクリーンページビュー数」を取得します。

UA（ユニバーサルアナリティクス）と異なり、GA4 ではメトリクス名やディメンション名が変更されているため注意が必要です。

実装コード

以下のコードで認証およびデータ取得を行います。

import { BetaAnalyticsDataClient } from '@google-analytics/data';

// サービスアカウントキーのパスを指定、または環境変数 GOOGLE_APPLICATION_CREDENTIALS を設定
const analyticsDataClient = new BetaAnalyticsDataClient({
  keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS,
});

async function getGA4BasicMetrics(propertyId: string) {
  const [response] = await analyticsDataClient.runReport({
    property: `properties/${propertyId}`,
    dateRanges: [
      {
        startDate: '7daysAgo',
        endDate: 'today',
      },
    ],
    dimensions: [
      {
        name: 'date',
      },
    ],
    metrics: [
      {
        name: 'activeUsers',
      },
      {
        name: 'sessions',
      },
      {
        name: 'screenPageViews',
      },
    ],
  });

  console.log('Report result:');
  response.rows?.forEach((row) => {
    const date = row.dimensionValues?.[0]?.value;
    const activeUsers = row.metricValues?.[0]?.value;
    const sessions = row.metricValues?.[1]?.value;
    const pageViews = row.metricValues?.[2]?.value;
    console.log(`${date} -> Users: ${activeUsers}, Sessions: ${sessions}, PV: ${pageViews}`);
  });
}

// 実行 (プロパティIDは数字のみ)
getGA4BasicMetrics('123456789');

実行結果 / レスポンス例

Report result:
20260914 -> Users: 42, Sessions: 48, PV: 95
20260915 -> Users: 56, Sessions: 63, PV: 120
20260916 -> Users: 38, Sessions: 41, PV: 81
...

ハマりどころ・注意点

1. property のフォーマット
   • プロパティIDだけ（例: 123456789）を渡すと 400 Bad Request になります。必ず先頭に properties/ を付与して properties/123456789 と指定してください。
2. ページビューのメトリクス名
   • UA時代の pageviews ではなく、GA4 では screenPageViews が正しい名前です。
3. 権限エラー (403)
   • GCPでサービスアカウントを作成しただけでは閲覧できません。GA4 管理画面 >「プロパティのアクセス管理」から、作成したサービスアカウントのメールアドレスを「閲覧者」として追加する必要があります。