用途
本技能用于在 treg 环境下查询 Google Analytics 4（GA4）Data API 时避免静默错误。资料明确指出，它不讲解 GA4 Data API 的基础用法，而是只收录那些"返回貌似合理的错误答案却不报错"的情况。内容于 2026-07-22 在线验证，每个陷阱都由三个独立智能体踩坑确认。
主要能力（收录的陷阱）
1. endDate:"today" 会静默包含不完整的一天
资料给出示例：
- 28daysAgo → today，/top-page = 45,120（包含不完整的一天）
- 28daysAgo → yesterday，/top-page = 44,300
建议：除非用户明确询问今天，否则使用 yesterday。如果必须使用 today，应说明最后一天是不完整的。
2. 零不代表零——先确认是否被追踪
资料称曾有智能体对有真实营收的业务报告"$0 营收和 0 转化"，其中两个给出高置信度。keyEvents、conversions 和 totalRevenue 在没有任何埋点时都会返回 0，与真正的零无法区分。
在报告任何零之前，应先确认该属性是否配置了任何关键事件：
--data '{"dateRanges":[...],"metrics":[{"name":"keyEvents"}]}'
不要在同一个调用中同时请求 keyEvents 和 conversions——它们是别名，GA4 会以 400 "Found duplicate metrics: conversions" 拒绝。应二选一。
资料指出：如果在一个有流量的站点上，长时间窗口内 keyEvents 为 0，正确答案应是"该来源的转化未在 GA4 中埋点，此问题无法从该来源回答"，而绝不是"营收为 $0"。营收很可能在 Stripe/PostHog 中。
3. 零行响应根本没有 rows 键
不是 rows: []——该键完全缺失，rowCount 也一样。结构因查询而异：
| 查询 | 返回的顶层键 |
|---|---|
| 按维度分组 | ['dimensionHeaders','metricHeaders','metadata','kind'] |
| 仅指标（如 keyEvents） | ['metadata','kind']——表头也消失 |
d['rows'] 会抛出 KeyError，看起来像请求格式错误。应使用 d.get('rows', [])，把空视为"无数据"，然后应用陷阱 #2。
3b. 不要把 dateRange 列为维度
比较两个时期是常见需求，但直接做法会报错：
400: "Field dateRange is not a dimension. This field can be used in a Pivot or
OrderBy like a dimension, but does not need to be listed in the Dimensions."
在 dateRanges 中传入 2 个或更多条目，API 会自动把范围作为额外的维度值追加。给这些范围命名以便在输出中标记。
4. 维度求和不等于总量——会多计
与无维度的真实总量对比（示例数据，重点是比例）：
| 分组方式 | 求和 vs 真实总量 |
|---|---|
| sessionDefaultChannelGroup | ~104% |
| country | ~104% |
| pagePath | ~189% |
会话会跨多个页面，因此按页面求和会严重重复计数。绝不要通过求和某个维度来报告总量——应单独运行一次无维度查询。
5. limit 默认 10000 并静默截断
一次无限制的 pagePath 查询恰好返回 10000 行，而 "rowCount": 42613——丢弃了 32,613 行，且没有任何警告。rowCount 才是真相；len(rows) 不是。在声称"全部"或"每一个"之前应比较两者。
6. Admin API 是不同主机，无法通过 /call/ 访问
该工具绑定到 analyticsdata.googleapis.com。任何位于 analyticsadmin.googleapis.com 的内容——accountSummaries、属性元数据——都会返回 Google HTML 404，而非 JSON。资料提到两个智能体在此浪费了多次尝试，包括试图传入绝对 URL（会被拼接成垃圾）。
要列出属性，应使用 treg，而不是代理：
treg connections resources <connection-id> # hits the Admin API server-side
使用方式
- 属性 id 获取：
treg connections ls→ google-analytics 行的 resource_ref。 - 其他内容均走标准 GA4 Data API。runReport、runRealtimeReport、batchRunReports、runPivotReport、checkCompatibility、/metadata 均已验证可通过 /call/ 工作。
- 两个小提示：metric 值是字符串（做算术前需转换）；metadata.timeZone 决定 "today" 的含义（属性按自己时区报告，例如 Australia/Sydney）。
适用场景
在 treg 环境下通过 /call/ 调用 GA4 Data API 进行报表查询时，尤其是需要向用户报告总量、转化、营收或多期对比结果时。
限制
- 资料提到一个"已报告但此处未观察到"的情况：高基数维度可能塌缩为一个 (other) 行。
- 本技能针对的数据边界限于 analyticsdata.googleapis.com；Admin API 需改用 treg 命令。
- 资料未提供其他平台、收费或价格信息。
参考
- API schema: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema
- runReport: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport
- Quotas: https://developers.google.com/analytics/devguides/reporting/data/v1/quotas