GA4 API 踩坑

1. 工具定位

GA4 (Google Analytics 4) 是新一代跨平台的数据采集与用户行为分析工具。在通过 API 进行数据自动化拉取时，需特别注意其底层的各种限制与不稳定性。

---

2. 核心请求限制 (Quota Limits)

GA4 API 实施了极其严格的令牌配额机制（Token-based Quota），设计高频轮询任务时极易触发 429 Too Many Requests。

警告

速率监控核心 每次执行报表查询请求（RunReport），GA4 会返回消耗的 Property Quota Tokens。必须在应用层实现退避重试（Exponential Backoff）机制，防止因并发导致配额被锁。 (注：具体消耗的 Token 量取决于请求的时间跨度、维度及指标复杂度。)

---

3. 已知底层 Bug 汇总 (截至当前记录期)

在深度集成 GA4 接口时，曾捕获到以下 Google 官方尚未修复的底层问题：

3.1. 账户维度层级校验 Bug

在执行 accounts.runAccessReport 请求时：

• 如果该资源 不是 Google Analytics 360 付费账户，请求载荷中 严禁使用 propertyName 作为维度进行聚合查询。
• 解决方案：只能降级使用底层的 propertyId 作为替代维度。

3.2. Google Signal API 冲突

• 如果媒体资源（Property）在控制台中开启了 Google Signals（谷歌信号数据收集），当前某些直接调用相关信号数据的 API 操作会被系统直接阻断或判定不可用。

3.3. 受众群体 (Audience) 周期参数异常

• 在构建受众群体定义或请求 Audience 数据时，只要 JSON 负载中包含 inAnyNDayPeriod（在任意 N 天周期内）这一时间窗口约束字段，接口就会直接抛出底层验证报错。