google-analytics

用途

Google Analytics 技能用于访问 GA4 数据与管理接口：使用 Google Analytics Data API 进行 GA4 报表查询，使用 Google Analytics Admin API 进行账号与媒体资源管理。适用于用户提到 "Google Analytics"、"GA4" 等场景。

主要能力

• 列出账号
• 列出媒体资源
• 运行基础报表
• 查询热门页面
• 查看实时活跃用户
• 发现可用的维度和指标

使用方式

前置条件

• 在 vm0.ai -> Settings -> Connectors（OAuth）中连接 Google Analytics。
• 所连接的 Google 账号必须有权访问对应的 GA4 账号/媒体资源。
• 访问令牌会以 $GOOGLE_ANALYTICS_TOKEN 注入。

基础 URL：

• Data API: https://analyticsdata.googleapis.com
• Admin API: https://analyticsadmin.googleapis.com

GA4 媒体资源 ID 为数字，例如 properties/123456789，不是像 G-XXXXXXXXXX 这样的衡量 ID。

1. 列出账号

curl -s "https://analyticsadmin.googleapis.com/v1beta/accounts" \
  --header "Authorization: Bearer $GOOGLE_ANALYTICS_TOKEN" \
  | jq '.accounts[] | {name, displayName, regionCode}'

2. 列出媒体资源

将 <account-id> 替换为 accounts/<account-id> 中的数字 ID。

curl -s -G "https://analyticsadmin.googleapis.com/v1beta/properties" \
  --header "Authorization: Bearer $GOOGLE_ANALYTICS_TOKEN" \
  --data-urlencode "filter=parent:accounts/<account-id>" \
  | jq '.properties[] | {name, displayName, propertyType, timeZone, currencyCode}'

3. 运行基础报表

写入 /tmp/ga4_report.json：

{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "date" }],
  "metrics": [
    { "name": "activeUsers" },
    { "name": "sessions" },
    { "name": "screenPageViews" }
  ],
  "orderBys": [{ "dimension": { "dimensionName": "date" } }]
}

然后运行：

curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/<property-id>:runReport" \
  --header "Authorization: Bearer $GOOGLE_ANALYTICS_TOKEN" \
  --header "Content-Type: application/json" \
  -d @/tmp/ga4_report.json \
  | jq '.rows[] | {date: .dimensionValues[0].value, activeUsers: .metricValues[0].value, sessions: .metricValues[1].value, pageViews: .metricValues[2].value}'

4. 热门页面

写入 /tmp/ga4_top_pages.json：

{
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "pagePath" }],
  "metrics": [{ "name": "screenPageViews" }, { "name": "activeUsers" }],
  "orderBys": [{ "metric": { "metricName": "screenPageViews" }, "desc": true }],
  "limit": 10
}

然后运行：

curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/<property-id>:runReport" \
  --header "Authorization: Bearer $GOOGLE_ANALYTICS_TOKEN" \
  --header "Content-Type: application/json" \
  -d @/tmp/ga4_top_pages.json \
  | jq '.rows[] | {page: .dimensionValues[0].value, pageViews: .metricValues[0].value, activeUsers: .metricValues[1].value}'

5. 实时活跃用户

写入 /tmp/ga4_realtime.json：

{
  "dimensions": [{ "name": "unifiedScreenName" }],
  "metrics": [{ "name": "activeUsers" }],
  "limit": 10
}

然后运行：

curl -s -X POST "https://analyticsdata.googleapis.com/v1beta/properties/<property-id>:runRealtimeReport" \
  --header "Authorization: Bearer $GOOGLE_ANALYTICS_TOKEN" \
  --header "Content-Type: application/json" \
  -d @/tmp/ga4_realtime.json \
  | jq '.rows[] | {screen: .dimensionValues[0].value, activeUsers: .metricValues[0].value}'

6. 发现可用维度与指标

curl -s "https://analyticsdata.googleapis.com/v1beta/properties/<property-id>/metadata" \
  --header "Authorization: Bearer $GOOGLE_ANALYTICS_TOKEN" \
  | jq '{dimensions: [.dimensions[].apiName], metrics: [.metrics[].apiName]}'

适用场景

• 查看 GA4 账号与媒体资源信息。
• 拉取按日期的活跃用户、会话、页面浏览等基础报表。
• 统计热门页面。
• 监控实时活跃用户。
• 查询某个媒体资源支持哪些维度和指标。

限制与注意事项

• 使用前必须完成 Google Analytics 连接器授权，且账号须有权访问目标 GA4 账号/媒体资源。
• GA4 媒体资源 ID 为数字，不要与 G-XXXXXXXXXX 形式的衡量 ID 混淆。
• 当用户不知道账号或媒体资源 ID 时，先用 Admin API 查询。
• 日常报表建议以昨天为结束日期，因为当天数据可能不完整。
• 保持维度与指标兼容；报表失败时可调用 metadata 验证 API 名称。
• 较大报表使用 limit 与 offset 分页。

故障排查

如果请求失败，运行：

zero doctor check-connector --env-name GOOGLE_ANALYTICS_TOKEN
zero doctor check-connector --url https://analyticsdata.googleapis.com/v1beta/properties/0:runReport --method POST
zero doctor check-connector --url https://analyticsadmin.googleapis.com/v1beta/accounts --method GET