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

前提条件

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

  1. Google Ads API 访问权限：

  2. 软件：

    • Python 3.10 或更高版本。Python 是默认语言，因此您必须安装 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 助理互动： 现在，您可以使用自然语言提问或发出指令。

主要特性

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

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

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

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

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

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，脚本将在 Google 助理上下文中执行。由于安全政策，已编译的语言将无法运行。

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

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

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

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

应用场景示例

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

社区和支持

贡献指南

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