Google Ads

核心用法

Google Ads技能提供托管式OAuth认证网关，用户通过Maton API密钥即可调用完整的Google Ads API v23接口。核心工作流分为三步：首先在ctrl.maton.ai创建OAuth连接并完成浏览器授权，然后使用listAccessibleCustomers获取可访问的客户ID，最后通过googleAds:search端点执行GAQL查询获取广告数据。

该技能支持两类核心查询模式：标准search适用于常规数据获取，searchStream用于处理大规模结果集。查询语言GAQL（Google Ads Query Language）语法接近SQL，可提取广告系列、广告组、关键词、受众及丰富的效果指标。

显著优点

1. 零OAuth基础设施：开发者无需注册Google Cloud项目、配置OAuth consent screen或维护refresh token，Maton自动处理token轮换与过期
2. 原生API透传：网关直接代理至googleads.googleapis.com，保留官方API完整能力，包括所有资源类型、细分维度（segments）及统计指标
3. 多账户管理：支持通过Maton-Connection头部切换不同Google Ads账户连接，适合代理商或跨市场团队
4. 多语言示例完备：提供Python、JavaScript、bash curl的完整可运行代码块

潜在局限

• 速率限制：每账户10 req/sec，高频数据同步场景需实现客户端退避
• 依赖第三方网关：所有流量经gateway.maton.ai中转，存在单点可用性风险
• 数据延迟：未明确说明是否支持实时竞价数据，默认存在数小时级别的报告延迟
• 权限粒度：OAuth权限范围由Maton预设，无法自定义缩减scope以降低安全暴露面

适合人群

• 营销分析师与增长团队：快速提取ROI数据制作报表
• 中小技术团队：无专职DevOps/安全工程师，无法维护OAuth基础设施
• 代理商与MCN：需要同时管理多个客户Google Ads账户

常规风险

1. API密钥泄露：MATON_API_KEY若硬编码或日志泄露，攻击者可遍历所有授权连接的广告数据
2. 过度授权：OAuth连接默认获取账户完整读写权限，即使仅执行查询也可能具备修改预算/停用广告的潜在能力
3. 供应链风险：Maton作为中间层拥有解密后的OAuth token，需信任其安全实践与合规承诺
4. 合规盲区：技能文档未提及GDPR/CCPA数据处理协议，欧盟用户数据流经美国服务器可能存在跨境合规问题

安全配置建议

• 将MATON_API_KEY注入环境变量，禁止提交至版本控制
• 定期审计ctrl.maton.ai中的连接状态，及时清理离职人员或废弃项目的授权
• 对生产环境使用只读服务账户（如Google Ads API原生支持），与本技能互补使用降低写权限暴露

核心用法

本Skill提供通过Maton API网关访问Google Ads API的完整集成方案，采用托管OAuth模式，用户无需自行处理复杂的Google OAuth 2.0认证流程。主要功能包括：

• 客户账户管理：listAccessibleCustomers 获取可访问的Google Ads账户列表
• GAQL数据查询：使用Google Ads Query Language查询营销活动(campaign)、广告组(ad_group)、关键词(keyword)及效果指标
• 流式数据获取：searchStream 接口支持大规模数据导出
• 连接管理：通过 ctrl.maton.ai 控制台创建、查看、删除OAuth连接

典型工作流：
1. 在maton.ai注册获取 MATON_API_KEY
2. 调用连接API创建Google Ads OAuth授权链接
3. 浏览器完成Google账号授权
4. 使用GAQL查询所需数据（支持标准SQL-like语法，含 DURING LAST_30_DAYS 等时间宏）

显著优点

• 零OAuth维护成本：Maton托管刷新令牌，自动处理token过期
• 多语言示例完备：提供Python、JavaScript、Bash curl的完整代码模板
• GAQL原生支持：直接编写类SQL查询，无需学习REST API复杂参数结构
• 多账户切换：通过 Maton-Connection 头部指定不同连接，适合代理运营场景
• 数据单位透明：文档明确标注金额单位为micros（需÷1,000,000转换）

潜在缺点与局限性

• 第三方网关依赖：所有数据流经Maton服务器（gateway.maton.ai），存在数据中转风险
• 服务商可信度：Maton为较新的社区项目（T3级别），缺乏大型企业长期安全验证
• 功能受限：仅支持查询类操作（read-only），不支持广告创建、出价修改等写入操作
• 速率限制：10 req/sec/账户的硬性限制，大规模数据拉取需分片处理
• 地理合规疑虑：未明确说明数据存储地理位置，GDPR敏感场景需谨慎评估

适合人群

• 广告代理商/分析师：需要快速批量获取多账户投放数据，无需维护OAuth基础设施
• 数据工程师：构建营销数据ETL管道，偏好GAQL而非官方SDK的复杂配置
• 初创团队：无专职后端人员，希望即用即走的Google Ads数据接入方案
• Python自动化用户：习惯用标准库 urllib 或 requests 快速脚本化任务

常规风险

| 风险类型 | 具体说明 | 缓解建议 |

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

| API密钥泄露 | `MATON_API_KEY` 泄露可导致账户数据被非法访问 | 定期轮换密钥，避免硬编码，使用密钥管理服务 |

| 供应链攻击 | Maton网关被入侵可能导致中间人数据窃取 | 监控Google Ads账户活动日志，验证API调用来源IP |

| OAuth权限过度授权 | 连接创建时可能默认请求较宽权限范围 | 在Maton控制台审查并限制权限至只读最小集合 |

| 服务中断 | Maton平台故障将导致数据获取中断 | 关键业务场景保留官方API SDK作为fallback方案 |

| 数据驻留合规 | 不确定数据是否跨境处理 | 企业用户需联系Maton确认数据存储位置及DPA条款 |