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 刷新令牌（来自初始授权流程）

安全边界

• 此技能仅连接至 Google Analytics Data API 端点。
• 它不会写入或修改您的 GA4 媒体资源——仅进行只读查询。
• 它不会在当前会话之外存储或传输凭据。
• 它需要将OAuth凭据（客户端ID、密钥、刷新令牌）设置为环境变量。

常见查询

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

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/"

可用指标

常用指标：屏幕页面浏览量、会话数、总用户数、新用户数、活跃用户数、跳出率、平均会话时长、转化次数,事件计数

可用维度

常用维度：页面路径,页面标题,着陆页,会话来源,会话媒介,会话广告系列名称,国家/地区,城市,设备类别,浏览器,日期

输出格式

默认：表格格式 添加--json用于JSON输出--csv用于CSV输出