安装和使用 Google Ads API 开发者助理

Google Ads API 开发者助理可将深厚的 Google Ads API 领域专业知识直接融入您的 AI 编码环境。使用自然语言提示和内置斜杠命令来构建查询、生成客户端库代码、执行只读 API 调用、流式传输临时报告以及排查集成问题。

该助理是为 Google Antigravity 和 Claude Code 代理框架 (v4.0.0) 构建的模块化插件。它使用 AGENTS.md 和 CLAUDE.md 合约、内置斜杠命令和专业领域技能来保持持久的上下文、强大的安全边界和自动验证流水线。

前提条件

在开始之前，请确保满足以下条件：

  1. Google Ads API 访问权限：

  2. 软件：

开始使用

请按照以下步骤克隆代码库、运行特定于平台的安装脚本、配置凭据并激活插件。

1. 克隆存储库

将代码库克隆到本地机器，然后前往项目目录：

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. 运行安装脚本

针对目标平台运行安装脚本。默认情况下，系统会包含 Python 客户端库。您可以选择性地添加其他客户端库（--php、--ruby、--java、--dotnet 或 --all）。

Antigravity

Linux / macOS： ```bash ./install.sh agy

或者包含其他客户端库：

./install.sh agy --java --dotnet ```

Windows (PowerShell)： ```powershell .\install.ps1 -Type agy

或者包含其他客户端库：

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS： ```bash ./install.sh claude

或者包含其他客户端库：

./install.sh claude --php --dotnet ```

Windows (PowerShell)： ```powershell .\install.ps1 -Type claude

或者包含其他客户端库：

.\install.ps1 -Type claude -Php -Dotnet ```

3. 配置凭据

确保您的 API 配置文件（例如 google-ads.yaml、google_ads_php.ini 或 google_ads_config.rb）位于 $HOME 目录中。

（可选）如需配置默认客户 ID，请直接在 config/customer_id.txt 中输入您的客户 ID 号码（例如 1234567890）。您还可以在 config/api_version.txt 中检查或固定有效 API 版本。

4. 激活插件

  • Antigravity：重启 Antigravity / agy 主机会话以加载插件。
  • Claude Code：在有效的 Claude Code 会话中，运行 /reload-plugins 或重启 claude。

5. 与 Google 助理互动

您可以在终端中直接使用自然语言提示或专用斜杠命令与助理互动。

主要特性

  • 自然语言问答：询问有关 Google Ads API 功能、最佳实践或特定资源的问题。

  • 自然语言问答和概念指导：您可以提出有关 Google Ads API 功能、架构规则或特定资源的问题。助理会根据官方 API 定义生成回答，而不是仅仅依赖于通用 LLM 训练。

    • “可供使用的广告系列类型有哪些？”
    • “如何在 GAQL 中按日期过滤？”
    • “Explain the difference between click_view and impression_view.”
    • “什么是共享套装，我该如何使用？”
    • Claude Code 斜杠命令： /explain、/step-by-step、/assistant-tutorial

  • 基于事实的客户端库代码生成：使用官方 Google Ads 客户端库（Python、Java、PHP、.NET 和 Ruby）生成经过测试的惯用代码。

    • “显示过去 30 天内转化次数最多的广告系列。”
    • “获取客户 123-456-7890 的所有已启用广告组的名称。”
    • “编写代码以制作效果最大化广告系列。” 生成的代码会保存在 saved/code/ 目录中。

  • 程序化 GAQL 查询验证：在执行之前，自动针对 API 元数据、字段兼容性、零展示规则和日期细分对复杂查询进行试运行和验证。

    • Claude Code： /validate-gaql
    • Natural Language： validate: SELECT campaign.id FROM campaign

  • 对象和 Protobuf 架构检查：动态检查任何有效 API 版本的资源结构、嵌套字段、数据类型和枚举值，而不会产生远程元数据开销。

    • Claude Code： /inspect-object <resource_or_enum>
    • 自然语言： “检查广告系列资源”

  • 临时实时报告和 CSV 导出：以简单明了的英语询问效果数据。助理直接针对您的账号构建、验证和运行 GAQL 查询，并将实时格式化表格流式传输到终端。

    • “Show top 5 keywords by cost last month for customer 123-456-7890.”
    • “将结果保存为 CSV 文件。”（导出为 saved/csv/）。

  • 直接执行 API 和变异安全性：在受管理的虚拟环境中直接执行生成的只读脚本。

    • 只需告诉 Google 助理：运行代码或执行脚本。
    • 变异安全性：为了安全起见，变异操作（创建、更新、删除）会生成到 saved/code/，但永远不会由助理直接执行。在助理之外手动查看和执行这些操作。

  • 高级诊断和线下转化问题排查：调查线下转化上传失败问题、预先验证上传文件，并生成详细的诊断报告。

    • Claude Code： /troubleshoot-conversions
    • 自然语言： “为客户 123-456-7890 排查转化问题。” （报告已保存到 saved/data/）。

  • MCC 账号层次结构映射：检索子账号客户 ID 并映射经理账号下的账号层次结构。

    • Claude Code： /get-cids <manager_cid>
    • 自然语言： “获取经理账号 123-456-7890 下的所有客户客户 ID”

  • 效果最大化广告系列商品详情过滤条件和排除对象：为素材资源组生成产品划分树和网页网址排除对象。

    • Claude Code： /pmax-filter
    • 自然语言： “为我的效果最大化广告系列创建网页排除对象过滤器”

  • 其他代码库上下文：将应用逻辑和自定义架构注册到助理的推理中。

    • Linux / macOS： bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell)： powershell .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Claude Code 斜杠命令参考

使用 Claude Code 时，可以使用以下内置斜杠命令。 在 Google Antigravity 中，您可以使用自然语言提示或技能工具名称（例如 validate_gaql 和 inspect_object）来调用这些功能，如主要功能中所述：

斜杠命令 用途 示例
/validate-gaql 验证 GAQL 语法、兼容性和规则。 /validate-gaql
/inspect-object 检查 Protobuf 字段、类型和枚举。 /inspect-object Campaign
/get-cids 解决 MCC 层次结构和客户 CID。 /get-cids 1234567890
/troubleshoot-conversions 运行线下转化上传诊断。 /troubleshoot-conversions
/pmax-filter 生成 PMax 商品详情过滤条件和排除对象。 /pmax-filter
/explain 提供 4 部分结构化说明。 /explain shared set
/step-by-step 制定多阶段任务执行计划。 /step-by-step upload conversions
/assistant-tutorial 运行交互式 11 步演示。 /assistant-tutorial

维护和更新

如需更新代码库、插件安装和客户端库，请执行以下操作：

Antigravity

Linux / macOS： bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell)： powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS： bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell)： powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

卸载

如需卸载助理插件，请执行以下操作：

Antigravity

Linux / macOS： bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell)： powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

然后重启 Antigravity 主机会话。

Claude Code

在有效的 Claude Code 会话中： none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

或者从终端执行以下操作： bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

（可选）移除本地应用商店注册信息： bash claude plugin marketplace remove google-ads-assistant-local

社区和支持

贡献指南

欢迎大家踊跃贡献！如需查看相关准则，请参阅 GitHub 代码库中的 CONTRIBUTING.md 文件。

上一页
什么是 Google Ads API 开发者助理？