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

前提条件

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

  1. Google Ads API 访问权限：

  2. 软件：

    • Python 3.10 或更高版本。Python 是默认语言，因此您必须安装此语言并将其添加到路径中。
    • Google Antigravity 命令行工具已安装。
    • jq（命令行 JSON 处理程序）。如果缺少此项，安装脚本会尝试安装。

  3. 代码库：

开始使用

  1. 导航到项目目录：

    cd <full path>/google-ads-api-developer-assistant

    （注意：如果您已启用 Antigravity shell 集成，则进入此目录会自动初始化助理会话）。

  2. 运行安装脚本：此脚本会初始化开发环境并克隆所需的 Google Ads 客户端库（默认情况下会安装 Python）。

    ./install.sh

    如果您使用的是 Windows，请运行 install.ps1 PowerShell 脚本。

  3. 配置凭据：确保您的 google-ads.yaml（或等效语言）放置在您的主目录中。

  4. 与 Google 助理互动：会话处于有效状态后，您可以在终端中直接使用自然语言与 Google 助理互动。

主要特性

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

    • “可供使用的广告系列类型有哪些？”
    • “如何在 GAQL 中按日期过滤？”
    • “Explain the difference between click_view and impression_view.”

  • 代码生成：生成 GAQL 查询和可执行的 Python 代码片段。

    • “显示过去 30 天内转化次数最多的广告系列。”
    • “获取广告系列 ID 为 12345 的所有已启用广告组的名称。”
    • “查找所有广告系列中被拒登的广告。” 生成的代码会使用 ruff 自动进行代码检查，并保存到 saved/code/ 目录中。

  • 直接执行 API：在隔离的虚拟环境 (.venv) 中直接运行生成的只读 Python 脚本，并在终端中以表格形式查看格式化后的结果。

    • 只需告诉 Google 助理：运行代码或执行脚本。
    • 为了安全起见，系统会生成变异操作（创建、更新、删除），但绝不会执行这些操作。

  • CSV 导出：将 API 调用的表格结果保存到 CSV 文件中。

    • “将结果保存到 CSV 文件中。”文件会保存在 saved/csv/ 目录中。

  • 高级诊断和问题排查：获取有关错误消息、意外 API 行为或线下转化问题的帮助。

    • “为什么我的查询没有返回任何结果？”
    • “针对客户 123-456-7890 排查转化问题。”（在 saved/data/ 中生成详细的诊断报告）。

  • 其他上下文：添加您自己的代码库或自定义库作为上下文。

    • 使用 update.sh 脚本和 --context_path 选项来注册项目文件： none ./update.sh --context_path /path/to/your/codebase
    • 这样，助理在创建回答或以您偏好的语言生成代码时，便可在推理过程中纳入您的应用逻辑。

应用场景示例

  • 报告：
    • “为客户 12345678 获取上个月费用最高的前 5 个关键字。”
  • 账号结构：
    • “列出所有广告系列名称及其 ID。”
  • 问题排查：
    • “我上传了 100 次转化，但界面中只显示了 78 次。如何使用 API 调试此问题？”
  • 学习：
    • “/explain what a shared set is”（解释什么是共享集）
  • 代码生成：
    • “编写代码以制作针对 company name 的效果最大化广告系列。”

社区和支持

贡献指南

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

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