Google Ads

核心用法

本技能提供 Google Ads API 的托管式集成，通过 Maton 平台代理请求至 Google 官方 API，自动处理 OAuth 认证和开发者令牌注入。用户仅需配置 MATON_API_KEY 环境变量，即可使用标准 GAQL（Google Ads Query Language）查询广告账户数据。支持的功能包括：列出可访问的客户账户、查询广告系列/广告组/关键词/效果指标、以及流式查询大数据集。

显著优点

1. 零配置 OAuth：免除了复杂的 Google Cloud 项目设置、OAuth 客户端配置和令牌刷新管理
2. 原生 GAQL 支持：完全兼容 Google Ads 官方查询语言，查询能力无阉割
3. 多账户管理：通过 Connection ID 机制支持同一 API Key 下的多账户切换
4. 完整读写能力：支持查询之外的数据修改操作（需用户显式确认）

潜在缺点与局限性

• 第三方代理依赖：所有流量经过 Maton 服务器，存在单点故障和服务商信任问题
• 速率限制：明确标注 10 req/sec 每账户的硬性限流，大规模数据拉取需使用 Search Stream
• 数据隐私：广告数据流经中间商，敏感商业信息暴露给 Maton 平台
• 货币单位陷阱：金额字段统一为微单位（micros），需手动除以 1,000,000，易引发计算错误

适合人群

• 需要快速接入 Google Ads 数据但不愿处理 OAuth 复杂配置的开发者
• 中小型营销技术团队，广告账户数量在 1-10 个范围内
• 需要临时数据拉取或报表自动化的数据分析师

常规风险

| 风险类型 | 说明 |

|---------|------|

| 服务商风险 | Maton 平台若遭遇安全事件或停止运营，将直接导致服务中断 |

| 认证泄露 | `MATON_API_KEY` 泄露可导致账户数据被非法访问，需严格保管 |

| 误操作风险 | 写操作（创建/修改/删除）虽需用户确认，但脚本批量执行时仍可能引发事故 |

| 合规风险 | 部分行业（如医疗、金融）的广告数据外流经第三方可能违反数据治理政策 |

核心用法

本 Skill 提供通过 Maton API 代理服务访问 Google Ads 的官方途径，核心工作流程为：

1. 获取 API Key：在 maton.ai 注册并获取 MATON_API_KEY
2. 建立 OAuth 连接：调用 /connections 端点创建 Google Ads 授权会话，浏览器完成 Google 账号授权
3. 执行 GAQL 查询：使用 Google Ads Query Language (GAQL) 检索广告系列、广告组、关键词及效果指标
4. 管理多账号：通过 Maton-Connection 头部指定不同连接 ID，支持多账号场景

关键端点包括 listAccessibleCustomers（获取可访问客户）、googleAds:search（标准查询）、googleAds:searchStream（大数据量流式查询）。货币值统一以 micros（百万分之一）返回，日期段支持 LAST_30_DAYS、THIS_MONTH 等语义化表达式。

显著优点

| 维度 | 优势 |

|------|------|

| **认证简化** | 托管 OAuth 免除了开发者自行维护 refresh token、处理授权流程的复杂工作 |

| **原生 GAQL** | 完整支持 Google Ads Query Language，功能与官方 API 1:1 对齐 |

| **多语言示例** | 提供 Bash、Python、JavaScript 完整代码片段，降低接入门槛 |

| **安全写入** | 明确声明所有写操作需用户显式确认，具备误操作防护 |

| **连接管理** | 独立的连接生命周期 API，支持多账号、团队权限场景 |

潜在缺点与局限性

• 第三方依赖：核心功能依赖 Maton 服务的可用性与持续性，存在供应商锁定风险
• 速率限制：10 req/sec 的账号级限流，大规模数据抓取需实现退避逻辑
• 网络要求：必须保持外网连通，无法离线使用
• 调试门槛：curl 管道至 jq 时环境变量可能不展开，新手易遇"Invalid API key"困惑
• 文档深度：仅覆盖常用查询场景，复杂归因分析、转化路径等高级用例需查阅 Google 官方文档

适合人群

• 广告主运营人员：需快速导出效果数据用于周报、BI 分析
• MarTech 开发者：构建广告数据 ETL 管道，无需从零搭建 OAuth 基础设施
• 代理商：管理多个客户 Google Ads 账号，需程序化切换账号
• 数据分析师：熟悉 SQL 语义，希望通过 GAQL 进行自定义维度下钻分析

常规风险

| 风险类型 | 说明 | 缓释建议 |

|----------|------|----------|

| **密钥泄露** | `MATON_API_KEY` 泄露可能导致账号数据被拉取 | 使用环境变量/密钥管理服务，禁止硬编码 |

| **OAuth 范围** | 授权时 Google 展示的范围可能过于宽泛 | 定期审计 Maton 连接权限，移除闲置授权 |

| **数据精度** | 报表数据存在延迟（通常 3 小时内），非实时 | 关键决策前确认 `segments.date` 最新同步时间 |

| **成本误读** | micros 单位未转换导致金额计算错误 ×1,000,000 | 封装货币转换层，统一输出为元/美元等标准单位 |