google-ads-scripts

Google Ads Scripts

概述

介绍如何使用 AdsApp API 开发 Google Ads Scripts。通过在 Google Ads 编辑器中运行 JavaScript，自动执行广告系列管理、出价优化、效果报告和批量操作。

核心功能

1. 广告系列操作

以编程方式管理广告系列，包括创建、修改、状态变更和批量更新。使用 AdsApp.campaigns() 并设置条件，按状态、预算、名称模式或类型进行筛选。应用标签以便整理。

2. 关键词与出价管理

根据效果自动执行关键词定位和出价调整。按质量得分筛选，根据 ROAS/CPA 目标调整最高 CPC 出价，添加/移除否定关键词，并实现出价优化算法。

3. 效果报告

使用广告系列、广告组、关键词和广告统计数据生成自定义报告。获取自定义日期范围内的指标，计算衍生指标（CTR、CPC、转化率），并将数据导出到 Google Sheets。

4. 预算管理

控制支出并在广告系列之间分配预算。获取/设置广告系列的每日预算，监控支出是否达到阈值，在达到限额时暂停广告系列，并根据效果分配预算。

5. 自动化规则与优化

通过自动决策为广告系列管理添加智能化功能。暂停表现不佳的关键词，提高表现出色的关键词的出价，并根据星期几的规律调整预算。

6. 错误处理与韧性

针对 API 限制、配额问题和运行时错误实现可靠的错误处理。使用 try-catch 块、空值检查和基于工作表的日志记录，以留存审计记录。请注意，执行时间上限为 30 分钟。

快速入门

最常见的模式——暂停质量得分低且支出高的关键词：

function pauseLowQualityKeywords() {
  const keywords = AdsApp.keywords()
    .withCondition('ad_group_criterion.status = "ENABLED"')
    .withCondition('ad_group_criterion.quality_info.quality_score < 4')
    .withCondition('metrics.cost_micros > 100000000') // 100 in account currency
    .forDateRange('LAST_30_DAYS')
    .get();

  let count = 0;
  while (keywords.hasNext()) {
    keywords.next().pause();
    count++;
  }
  Logger.log(`Paused ${count} low-quality keywords`);
}

最佳实践

• 批量操作 - 先收集实体，再进行处理；避免在循环中单独调用 API
• API 层筛选 - 使用 .withCondition()，而不是在 JavaScript 中筛选
• 错误处理 - 使用 try-catch 包装操作，并将错误记录到工作表或通过电子邮件发送
• 执行限制 - 对大型账户使用 .withLimit() 和批量处理（超时为 30 分钟）
• 微单位转换 - 货币值以微单位表示（显示时除以 1,000,000）
• 审计日志 - 将所有变更及时间戳记录到 Google Sheets

有关每项实践的详细代码示例，请参阅 references/best-practices.md。

与其他技能集成

• google-apps-script - 用于 Google Sheets 报告、Gmail 通知、Drive 文件管理和触发器设置
• google-analytics - 与 GA4 Measurement Protocol 结合，跟踪由脚本触发的事件
• google-tagmanager - 与 GTM 配置协同，实现全面的跟踪

验证与测试

使用 scripts/ 中的验证脚本进行部署前检查：

• scripts/validators.py - 在应用变更前验证广告系列数据、出价值和预算金额

故障排除

常见问题：

1. 执行超时 - 使用 .withLimit() 缩小范围，或分批处理
2. 超出配额 - 降低 API 调用频率，并使用缓存数据
3. 类型错误 - 请记住，货币值需要进行微单位转换
4. 空值 - 访问属性前务必检查是否为空值

使用 Logger.log() 进行调试；在脚本编辑器中通过 View > Logs 查看日志。

参考资料

根据需要加载以下文档，查看详细说明：

• references/ads-api-reference.md - 完整的 AdsApp API 参考，包含选择器、方法、条件、统计信息和企业级模式
• references/examples.md - 详细代码示例：暂停低质量关键字、根据 ROAS 优化出价、将广告系列效果导出到 Sheets
• references/best-practices.md - 最佳实践及代码块：批量操作、API 筛选、错误处理、微单位转换、审计日志
• references/patterns.md - 可复用的自动化模式：条件出价调整、质量得分监控