google-analytics

用途

本技能用于查询 Google Analytics 4（GA4）数据，通过 curl + jq 命令行方式调用 Google 官方 API，适合在终端或脚本化流程中获取分析报告。

认证方式

用户的 OAuth 令牌存放在环境变量 $GOOGLE_ANALYTICS_TOKEN 中（作用域为 analytics.readonly）。每次调用都需要 Authorization: Bearer $GOOGLE_ANALYTICS_TOKEN 请求头。示例中将其封装为 AUTH 变量使用。

涉及的 API

本技能使用两个 API：

Admin API（analyticsadmin.googleapis.com/v1beta）：用于发现用户可访问的 GA4 属性。
Data API（analyticsdata.googleapis.com/v1beta）：用于运行报告。

使用方式

列出可访问的 GA4 属性

通过账户摘要列出用户可访问的属性：

curl -sS -H "$AUTH" "https://analyticsadmin.googleapis.com/v1beta/accountSummaries" \
  | jq '.accountSummaries[]?.propertySummaries[]? | {property, displayName}'

其中 property 形如 properties/123456789，其中的数字即 PROPERTY_ID。

运行报告

PID="123456789"
curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json" -d '{
  "dateRanges":[{"startDate":"28daysAgo","endDate":"today"}],
  "dimensions":[{"name":"pagePath"}],
  "metrics":[{"name":"screenPageViews"},{"name":"activeUsers"}],
  "orderBys":[{"metric":{"metricName":"screenPageViews"},"desc":true}],
  "limit":10
}' "https://analyticsdata.googleapis.com/v1beta/properties/$PID:runReport" \
  | jq '.rows[] | {page: .dimensionValues[0].value, views: .metricValues[0].value, users: .metricValues[1].value}'

通过替换维度与指标可以生成其他报告：sessionDefaultChannelGroup + sessions（获客来源）、country + activeUsers（地域）、eventName + eventCount / conversions（事件）。日期支持 NdaysAgo、today、yesterday 或 YYYY-MM-DD 格式。

实时报告

curl -sS -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"dimensions":[{"name":"country"}],"metrics":[{"name":"activeUsers"}]}' \
  "https://analyticsdata.googleapis.com/v1beta/properties/$PID:runRealtimeReport" | jq '.rows'

错误处理

失败时返回格式为 {"error":{"code","message","status"}}，应原样展示。401 错误表示需要重新安装（重新授权）。

注意事项

本技能仅适用于 GA4（Data API v1）。旧版 Universal Analytics（UA）已停止服务，不要使用遗留的 analytics/v3 端点。
维度/指标的 API 名称必须有效（例如是 screenPageViews，而不是 "Pageviews"）。如果某个名称返回 400，说明 API id 写错了，应查阅 GA4 维度与指标列表。
报告受 limit 限制（默认 1 万行），可使用 offset 进行分页。

适用场景

适用于需要以命令行方式查询 GA4 报表数据的场景，例如获取页面浏览量、活跃用户、获客渠道、地域分布、事件统计以及实时数据等。

限制

需要用户自行提供有效的 OAuth 令牌且作用域为 analytics.readonly。
仅支持 GA4，不支持已停用的 Universal Analytics。
报告结果受 limit 与 offset 分页限制。
依赖 curl 与 jq 工具环境。