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

前提条件

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

  1. Google Ads API 访问权限：

  2. 软件：

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

  3. 代码库：

开始使用

  1. 导航到项目目录：

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

  2. 运行设置脚本： 此脚本会将 gemini-cli 配置为使用助理的 GEMINI.md 上下文文件和必要工具。

    ./install.sh

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

  3. 启动 gemini-cli：

    gemini

  4. 与助理互动： 您现在可以使用自然语言提问或发出命令。

主要特性

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

    • “可供使用的广告系列类型有哪些？”
    • “如何在 GAQL 中按日期过滤？”
    • “解释 click_view 和 impression_view 之间的区别。”

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

    • “显示过去 30 天内转化次数最多的广告系列。”
    • “获取广告系列 ID 为 12345 的所有已启用广告组的名称。”
    • “查找所有广告系列中被拒登的广告。”生成的代码会保存在 saved_code/ 目录中。

  • 直接执行 API： 直接从 gemini-cli 运行生成的只读 Python 脚本，并在终端中查看格式化结果。助理生成代码后，您会收到屏幕提示：

To run this script, you will need to replace YOUR_CUSTOMER_ID with your actual
Google Ads customer ID and execute the following command in
your shell: <command>

输入 run，如果您的默认语言是 Python、Ruby 或 PHP，脚本将在助理上下文中执行。由于 安全政策，编译后的语言将无法运行。

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

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

  • 问题排查帮助： 获取有关错误消息或意外 API 行为的帮助。

    • “我收到了错误 'AuthenticationError.OAUTH_TOKEN_INVALID'，该怎么办？”
    • “为什么我的查询没有显示任何结果？”

  • 添加上下文： 添加您的代码库以获取上下文。

    • 从 v2.3.0 开始，使用 context_dir 标志添加项目文件： ./update.sh --context_dir /path/to/your/codebase。这样， 助理在创建响应时就可以将您的应用逻辑纳入推理过程。
    • 借助此功能，助理可以使用您选择的语言生成保存的代码示例，即使没有官方客户端库，也能提供支持。
    • 在请求代码输出之前，请告知助理： write saved code examples in <language of your application>

应用场景示例

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

社区和支持

贡献指南

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

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