Google Analytics 4

直接通过 Google Analytics Data API（analyticsdata.googleapis.com）查询 GA4 属性。

配置（仅需一次）

1. 创建 Google Cloud 项目（或复用已有项目）

访问 https://console.cloud.google.com，创建或选择一个项目。

2. 将 OAuth 同意屏幕设置为“内部”

进入 API 和服务 > 凭据 > OAuth 同意屏幕 > 受众，设置：

• 用户类型：内部

此举可跳过 Google 的应用验证流程（该流程对 Analytics 等敏感权限范围要求提供演示视频）。对于个人或团队用途，“内部”类型已足够。注意：此设置要求使用 Google Workspace 账户（而非个人 @gmail.com 账户）。

若必须使用“外部”类型（例如你仅有个人 Gmail 账户），请将发布状态设为“已上线”，并在 数据访问 / 权限范围 中添加 analytics.readonly 权限范围。

3. 添加 Analytics 权限范围

进入 OAuth 同意屏幕 > 数据访问（或“权限范围”），添加以下权限范围：

https://www.googleapis.com/auth/analytics.readonly

Google 将其列为“敏感权限范围”。若你的应用类型为“内部”，则无需验证。

4. 启用 Analytics Data API

访问：https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com

点击 启用。

5. 创建 OAuth 2.0 凭据

进入 API 和服务 > 凭据 > 创建凭据 > OAuth 客户端 ID

• 应用类型：桌面应用
• 名称：任意自定义名称

保存生成的 客户端 ID 和 客户端密钥。

6. 获取你的 GA4 Property ID

访问 https://analytics.google.com > 管理（齿轮图标）> 属性设置。Property ID 即顶部显示的数字值。

7. 生成刷新令牌（refresh token）

在本地机器上运行以下命令（需浏览器完成 Google 登录流程）：

pip install google-auth-oauthlib

python3 -c "from google_auth_oauthlib.flow import InstalledAppFlow; flow = InstalledAppFlow.from_client_config({'installed': {'client_id': 'YOUR_CLIENT_ID', 'client_secret': 'YOUR_CLIENT_SECRET', 'auth_uri': 'https://accounts.google.com/o/oauth2/auth', 'token_uri': 'https://oauth2.googleapis.com/token'}}, scopes=['https://www.googleapis.com/auth/analytics.readonly']); creds = flow.run_local_server(port=0); print('REFRESH TOKEN:', creds.refresh_token)"

将 YOUR_CLIENT_ID 和 YOUR_CLIENT_SECRET 替换为你自己的值。系统将自动打开浏览器窗口供你使用 Google 账户登录。从终端输出中复制刷新令牌（refresh token）。

8. 设置环境变量

GA4_PROPERTY_ID=123456789
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token

问题排查

• 403 HTML 错误页面：可能未在 OAuth 同意屏幕中添加 analytics.readonly 权限范围。请前往“数据访问 / 权限范围”中添加该范围，并重新生成刷新令牌。
• 403 JSON 错误 “caller does not have permission”：当前 Google 账户无权访问该 GA4 属性。请在 Google Analytics 中检查 管理 > 属性访问管理。
• 令牌刷新失败：刷新令牌可能已过期。请按第 7 步重新生成。

查询示例

按浏览量排序的热门页面

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics screenPageViews 
  --dimension pagePath 
  --limit 20

按浏览量、会话数与用户数排序的热门页面

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics screenPageViews,sessions,totalUsers 
  --dimension pagePath 
  --limit 20

流量来源

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics sessions 
  --dimension sessionSource 
  --limit 20

按来源与媒介划分的流量

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics sessions,totalUsers,conversions 
  --dimensions sessionSource,sessionMedium 
  --limit 20

着陆页

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics sessions,bounceRate 
  --dimension landingPage 
  --limit 30

自定义日期范围

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics screenPageViews,sessions 
  --dimension pagePath 
  --start 2026-01-01 
  --end 2026-01-31 
  --limit 20

按路径前缀过滤

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics screenPageViews,sessions 
  --dimension pagePath 
  --filter "pagePath=~/blog/" 
  --limit 20

按广告系列统计转化数

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics conversions,sessions 
  --dimensions sessionCampaignName,sessionSource 
  --limit 20

设备类型分布

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics sessions,totalUsers 
  --dimension deviceCategory 
  --limit 10

国家/地区分布

python3 /mnt/skills/user/google-analytics/scripts/ga4_query.py 
  --metrics sessions,totalUsers 
  --dimension country 
  --limit 20

常用指标（Metrics）

screenPageViews、sessions、totalUsers、newUsers、activeUsers、bounceRate、averageSessionDuration、conversions、eventCount、engagementRate、userEngagementDuration

常用维度（Dimensions）

pagePath、pageTitle、landingPage、sessionSource、sessionMedium、sessionCampaignName、country、city、deviceCategory、browser、date、week、month

输出格式

结果以格式化表格形式输出至标准输出（stdout）。如需原始 JSON 格式，请通过管道传递给 | python3 -m json.tool。