安装和使用 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 Ads API 功能、架构规则或特定资源的问题。助理会根据官方 API 定义提供回答，而不是仅仅依赖于通用 LLM 训练。

    • “可供使用的广告系列类型有哪些？”
    • “如何在 GAQL 中按日期过滤？”
    • “请解释 click_view 和 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
    • 自然语言： validate: SELECT campaign.id FROM campaign

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

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

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

    • “显示客户 123-456-7890 上个月费用最高的前 5 个关键字。”
    • “将结果另存为 CSV 文件。”（导出到 saved/csv/）。

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

    • 只需告诉助理：“运行代码”或“执行脚本”。
    • 变异安全性： 为确保安全，变异操作（创建、更新、删除）会生成到 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-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

（可选） 移除本地 Marketplace 注册表： bash claude plugin marketplace remove google-ads-assistant-local

社区和支持

贡献指南

欢迎大家踊跃贡献！如需了解相关指南，请参阅 GitHub 代码库中的 CONTRIBUTING.md 文件。

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