名称： ga4
描述： 通过 Analytics Data API 查询 Google Analytics 4 (GA4) 数据。适用于需要获取网站分析数据的场景，如热门页面、流量来源、用户数、会话数、转化数或任何 GA4 指标/维度。支持自定义日期范围和筛选。
元数据： {"clawdbot":{"emoji":"📊","requires":{"bins":["python3"]}}}

GA4 - Google Analytics 4 数据 API

查询 GA4 媒体资源以获取分析数据：页面浏览量、会话数、用户数、流量来源、转化数等。

初始设置（一次性）

1. 启用 Google Analytics Data API：https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com
2. 创建 OAuth 凭据或使用现有的 Google Cloud 项目
3. 设置环境变量：
   • GA4_PROPERTY_ID - 您的 GA4 媒体资源 ID（数字格式，例如 "123456789"）
   • GOOGLE_CLIENT_ID - OAuth 客户端 ID
   • GOOGLE_CLIENT_SECRET - OAuth 客户端密钥
   • GOOGLE_REFRESH_TOKEN - OAuth 刷新令牌（来自初始授权流程）

常用查询示例

热门页面（按页面浏览量）

python3 scripts/ga4_query.py --metric screenPageViews --dimension pagePath --limit 30

包含会话数与用户数的热门页面

python3 scripts/ga4_query.py --metrics screenPageViews,sessions,totalUsers --dimension pagePath --limit 20

流量来源

python3 scripts/ga4_query.py --metric sessions --dimension sessionSource --limit 20

着陆页

python3 scripts/ga4_query.py --metric sessions --dimension landingPage --limit 30

自定义日期范围

python3 scripts/ga4_query.py --metric sessions --dimension pagePath --start 2026-01-01 --end 2026-01-15

按页面路径筛选

python3 scripts/ga4_query.py --metric screenPageViews --dimension pagePath --filter "pagePath=~/blog/"

可用指标

常用指标：screenPageViews（页面浏览量）, sessions（会话数）, totalUsers（总用户数）, newUsers（新用户数）, activeUsers（活跃用户数）, bounceRate（跳出率）, averageSessionDuration（平均会话时长）, conversions（转化数）, eventCount（事件数）

可用维度

常用维度：pagePath（页面路径）, pageTitle（页面标题）, landingPage（着陆页）, sessionSource（会话来源）, sessionMedium（会话媒介）, sessionCampaignName（会话广告系列名称）, country（国家）, city（城市）, deviceCategory（设备类别）, browser（浏览器）, date（日期）

输出格式

默认：表格格式
添加 --json 参数输出 JSON 格式
添加 --csv 参数输出 CSV 格式