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

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

该助理是作为模块化插件为 Google Antigravity 和 Claude Code 智能体框架 (v4.0.0) 构建的。它使用 AGENTS.md 和 CLAUDE.md 协定、内置斜杠命令和专业领域技能来维护持久上下文、强大的安全边界和自动化验证流水线。如需大致了解其架构和设计，请参阅什么是 Google Ads API 开发者助理？

前提条件

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

  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：

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell)：

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS：

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell)：

.\install.ps1 -Type claude
# Or include additional client libraries:
.\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 功能、架构规则、最佳实践或特定资源的问题。该助理会根据官方 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
    • 自然语言： 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 执行和变更安全性：直接在代管式虚拟环境中执行生成的只读脚本。

    • 告诉 Google 助理：“运行代码”或“执行脚本”。
    • 变更安全性：为确保安全，系统会生成变更操作（创建、更新、删除）并将其发送到 saved/code/，但助理绝不会直接执行这些操作。请在助理之外手动查看并执行这些命令。

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

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

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

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

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

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

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

    • Linux / macOS：

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (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 解析经理账号层次结构和客户 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：

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell)：

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS：

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell)：

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

卸载

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

Antigravity

Linux / macOS：

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell)：

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

然后重启 Antigravity 主机。

Claude Code

在活跃的 Claude Code 会话中：

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

或者，在终端中运行以下命令：

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

（可选）移除本地 Marketplace 注册表：

claude plugin marketplace remove google-ads-assistant-local

社区和支持

贡献准则

欢迎贡献内容！如需了解相关准则，请参阅 GitHub 代码库中的 CONTRIBUTING.md 文件。

后续步骤

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