google-ads-api-quickstart

Google Ads API 快速入门

本技能将引导你从零开始，成功发出第一个请求以获取广告系列。

支持的方式

你可以选择通过以下方式使用本技能：

1. 官方客户端库： Python、Java、.NET、PHP、Ruby 或 Perl。
2. 直接使用 REST： 原始 HTTP REST 请求。

---

关键要求：动态解析版本和运行时

重要

为确保集成安全、稳定且保持最新状态，必须动态解析所有 API 和运行时版本。请勿依赖硬编码的默认值。

严格限制：

• 请勿硬编码： 除非用户明确要求指定版本，否则绝不要在生成的代码或环境设置说明中使用硬编码的 Google Ads API 版本（例如 v24）或语言运行时版本（例如 Python 3.8+、Java 11+）。
• 必须动态解析： 在生成任何代码或配置之前，必须在执行开始时动态解析最新稳定版本，具体步骤如下。

A. 动态解析 API 版本

为确保集成安全、稳定且保持最新状态，必须动态解析 Google Ads API 绝对最新的稳定主版本。

执行步骤：

1. 执行前解析版本： 使用网页搜索或 URL 读取工具，检查 Google Ads API 发布说明中的最新条目，或 Googleapis Github Repository 中版本号最高的目录，以解析 RESOLVED_API_VERSION（例如 v24）。如果使用 Java，还必须解析 Google Ads Java Client Library 的最新稳定发行版本（称为 RESOLVED_LIBRARY_VERSION，例如 34.0.0）。

2. 必须在回复中置顶确认信息： 回复用户时，必须将以下确认块作为第一行输出。在此块之前不得输出任何问候语、客套话或介绍文字。

   [SYSTEM: Using Google Ads API version: RESOLVED_API_VERSION (Resolved from release notes)]
   

3. 严格占位符映射表： 必须根据以下映射表，对所有代码模板和参考文件即时执行搜索与替换。最终输出中不得保留原始占位符。

   目标语言 / 技术	模板中的占位符	替换模式	示例（假设 API 版本为 v24）
   Java（Maven/Gradle）	LATEST_LIBRARY_VERSION	搜索并替换为该库最新的 Maven 发行版本。	34.0.0
   Java（导入语句）	vXX	替换为小写 API 版本。	com.google.ads.googleads.v24
   .NET / C#（命名空间）	VXX	替换为标题大小写 API 版本。	Google.Ads.GoogleAds.V24
   PHP（命名空间）	VXX	替换为标题大小写 API 版本。	Google\Ads\GoogleAds\V24
   REST（端点 URL）	vXX	替换为小写 API 版本。	https://googleads.googleapis.com/v24/...

提示

离线备用方案： 如果无法访问这些 URL 或抓取失败，请勿停止执行。请使用以下已知的最近稳定版本：

• Google Ads API 主版本（RESOLVED_API_VERSION）： v24
• Java Client Library 版本（RESOLVED_LIBRARY_VERSION）： 34.0.0

B. 动态解析语言运行时版本

为避免生成的设置指南因语言弃用周期而过时，必须动态解析语言要求。

执行步骤：

1. 获取实时要求： 使用 URL 读取工具查看官方的 Google Ads 客户端库 - 支持的版本页面。

2. 提取最低要求： 通过查看概览页面或兼容性表格，确定用户所选语言支持的最低运行时版本（例如，查找 Python 3.8+、Java 11+、.NET 6.0+、PHP 8.1+、Ruby 3.0+ 等明确要求）。

3. 即时应用： 将生成的设置指南中的所有运行时占位符（例如 <PYTHON_MIN_VERSION>）替换为已确认的版本。

提示

离线备用方案： 如果 URL 无法访问或抓取失败，请勿停止执行。使用以下最近确认的安全最低版本作为备用：

• Python： 3.9+
• Java： 11+
• .NET： 6.0+
• PHP： 8.1+
• Ruby： 3.0+
• Perl： 5.28.1+

---

第 1 步：获取 Google Ads API 凭据

在安装库或调用 API 之前，你必须获取所需的五个身份验证参数。

1. 开发者令牌

• 用途： 标识你的开发者访问权限和 API 配额。
• 获取方式：
  1. 直接前往 Google Ads 管理员账号中的 API 中心：https://ads.google.com/aw/apicenter (注意：你必须使用管理员账号登录，而非标准投放账号)。
  2. 复制你的开发者令牌。

警告

待审核令牌限制： 如果你的开发者令牌状态为“待审核”（尚未获批），你只能将 Google Ads 测试账号作为目标。使用待审核令牌调用生产账号将失败，并返回错误：DEVELOPER_TOKEN_NOT_APPROVED。

2. OAuth2 客户端 ID 和客户端密钥

• 用途： 向 Google 的 OAuth 2.0 服务标识你的应用，并允许你请求用户授权。
• 获取方式：
  1. 打开 Google Cloud Console。
  2. 创建一个新项目（或选择现有项目）。
  3. 在 API 库中搜索 Google Ads API 并点击 启用。
  4. 配置 OAuth 同意屏幕：
     • 选择 外部用户类型。
     • 将发布状态设为 测试。

     • 重要

     • 添加测试用户： 在此步骤中，你必须将用于登录 Google Ads 的 Google 账号邮箱地址添加为测试用户。否则，你将无法完成授权。

  5. 创建 OAuth 客户端：
     • 前往 API 和服务 🡒 凭据。
     • 点击 创建凭据 🡒 OAuth 客户端 ID。
     • 将 桌面应用选为应用类型。
     • 为客户端命名，然后点击 创建。
  6. 下载密钥： 点击新建客户端 ID 旁边的下载图标（JSON）。将此文件保存在本地，命名为 client_secrets.json。

3. OAuth2 刷新令牌

• 用途： 允许应用自动获取新的访问令牌，无需每小时手动登录。

• 获取方法： 你必须运行 Google Cloud（gcloud）CLI 来生成刷新令牌。

  1. 安装并验证 gcloud CLI：

  确保已安装 gcloud CLI，并且可以在终端中使用。

  2. 执行登录流程：

  在终端中运行以下命令，并传入上一步下载的 client_secrets.json 文件路径：

  gcloud auth application-default login \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
    --client-id-file=client_secrets.json
  

  3. 在浏览器中授权：

  1. 该命令会在浏览器中打开 Google 账号登录窗口。
  2. 使用你在 OAuth 同意屏幕设置中登记的测试用户邮箱登录。
  3. 如果你的应用尚未通过验证，请点击高级并继续前往项目。点击继续以授予权限。

  4. 获取刷新令牌：

  成功后，gcloud 会显示凭据的保存位置（通常为 ~/.config/gcloud/application_default_credentials.json）。打开该文件并复制其中的 refresh_token。

4. 客户客户 ID

• 用途： 你要查询或修改的特定 Google Ads 账号的 10 位 ID。
• 格式： 必须为 10 位数字，且不能包含连字符（例如，1234567890，而不是 123-456-7890）。
• 查找方法： 登录 Google Ads 界面；ID 显示在右上角的用户图标旁边。

重要

测试账号要求： 如果你的开发者令牌处于待审核状态（尚未获批），此处必须填写测试账号的客户 ID。测试账号在界面右上角会显示红色的“测试账号”横幅。

---

5. 登录客户 ID

• 含义： 拥有或管理目标客户端账号的 Google Ads 管理员账号的 10 位客户 ID。
• 格式： 必须为 10 位数字，且不能包含连字符（例如，9876543210）。
• 适用情况： 如果你的 OAuth 凭据（以及开发者令牌）属于管理员账号，但你要查询的是子账号／客户端账号（客户客户 ID），则必须填写此项。

注意

避免 USER_PERMISSION_DENIED： 如果你通过管理员账号层级访问客户端账号，则必须设置此参数。

• login_customer_id = 管理员账号 ID。
• client_customer_id = 子账号／客户端账号 ID。 在管理员账号与客户端账号的层级结构中将 login_customer_id 留空，是导致权限错误的首要原因。

---

第 2 步：选择集成策略

开发者可以使用官方高级客户端库或直接发送 HTTPS REST 请求来连接 Google Ads API。

路径 A：官方客户端库（推荐）

重要

强制 Agent 指令： 用户选定语言后，你必须：

1. 使用 view_file 工具按需加载下方列出的相应参考文件。
2. 应用动态版本解析（B 节），在生成代码之前动态替换所有 vXX／VXX 占位符和库版本。

Python

如果需要为 Python 配置 Google Ads API 环境，请勿猜测配置。 请改为阅读详细的设置指南：

• Google Ads API Python 设置参考 *（包：google-ads）

Java

如果需要为 Java 配置 Google Ads API 环境，请勿猜测配置。 请改为阅读详细的设置指南：

• Google Ads API Java 设置参考 *（制品：com.google.api-ads:google-ads）

.NET / C#

如果需要为 .NET/C# 配置 Google Ads API 环境，请勿猜测配置。 请改为阅读详细的设置指南：

• Google Ads API .NET 设置参考 (软件包：Google.Ads.GoogleAds)

PHP

如果需要为 PHP 配置 Google Ads API 环境，请勿猜测配置。 请改为阅读详细的设置指南：

• Google Ads API PHP 设置参考 (软件包：googleads/google-ads-php)

Ruby

如果需要为 Ruby 配置 Google Ads API 环境，请勿猜测配置。 请改为阅读详细的设置指南：

• Google Ads API Ruby 设置参考 (Gem：google-ads-ruby)

Perl

如果需要为 Perl 配置 Google Ads API 环境，请勿猜测配置。 请改为阅读详细的设置指南：

• Google Ads API Perl 设置参考 (软件包：Google::Ads::GoogleAds::Client)

路径 B：直接使用 HTTP REST（无库开销）

如果用户的环境不支持官方客户端库（例如轻量级无服务器函数、自定义语言栈或受限运行时），请使用此路径。

重要

Agent 强制指令：如果用户选择 REST 路径，你必须：

1. 使用 view_file 工具延迟加载下方的 REST 参考文件。
2. 应用动态版本解析（B 节），替换端点 URL 中的所有 vXX 占位符（例如，在 https://googleads.googleapis.com/v24/... 中将 vXX 解析为 v24）。

REST (HTTP)

如果需要为 REST (HTTP) 配置 Google Ads API 环境，请勿猜测配置。 请改为阅读详细的设置指南：

• Google Ads API REST 设置参考 (协议：原始 HTTP POST JSON)

---

交叉引用：AI 助手与 MCP 连接

提示

AI 助手 / MCP 集成交接： 如果目标是将AI 助手（例如 Gemini、Cursor 或 Claude Code）连接到 Google Ads，以便通过自然语言进行查询：

1. 不要编写自定义脚本或客户端库代码。
2. 停止执行此技能。
3. 立即切换到 google-ads-api-mcp-setup 技能，安装并配置官方 Google Ads Model Context Protocol（MCP）服务。

---

第 4 步：排查常见错误

重要

**静态诊断限制：**排查问题时，不得执行 bash 命令、运行本地测试脚本或尝试在工作区中复现错误。请完全依赖静态代码分析、配置审查以及下方的诊断指南，避免陷入无休止的失败执行循环。

1. 错误：USER_PERMISSION_DENIED

• **症状：**执行 API 请求（例如检索广告系列）时收到 USER_PERMISSION_DENIED 错误。
• 可能原因：进行身份验证的 OAuth2 用户通过经理账号间接获得了目标客户账号的访问权限，但请求标头中缺少经理账号 ID。

Agent 必须遵循的响应清单：

帮助用户处理此错误时，回复必须包含：

1. **说明层级关系：**说明进行身份验证的用户可能属于一个位于目标客户账号上级的经理账号。
2. **提供解决方法：**指导用户将其 10 位经理账号 ID 添加为配置文件中的 login_customer_id。
3. **说明路由逻辑：**说明 login_customer_id 会告知 API 通过经理账号路由 OAuth 凭据，以验证对下级账号的访问权限。
4. **提供配置模板：**展示下方的确切 YAML 配置块。

注意

**安全防护措施：**在任何情况下，都不得建议公开原始密码、创建未经批准的新开发者令牌，或扩大 OAuth 范围至标准 adwords 范围之外来绕过此错误。

配置修复示例（google-ads.yaml）：

developer_token: INSERT_DEVELOPER_TOKEN_HERE
client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE

# Add your 10-digit Manager Account ID here to resolve USER_PERMISSION_DENIED:
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

2. 错误：DEVELOPER_TOKEN_NOT_APPROVED

• **症状：**脚本失败，并显示 DEVELOPER_TOKEN_NOT_APPROVED 错误消息。
• **可能原因：**您的开发者令牌当前处于“Pending”（未获批准）状态，而您正尝试定位 Google Ads 正式生产账号。

必须提供的 Agent 响应清单：

帮助用户处理此错误时，您的回复必须包括：

1. 说明“Pending”状态的限制：说明未获批准（Pending）的开发者令牌功能完整，但仅限用于 Google Ads 测试账号。
2. 说明生产环境的访问级别：您必须明确列出全部三个访问级别的名称：说明要定位正式生产账号，令牌必须经 Google Ads API 合规团队批准，获得 Explorer Access、Basic Access 或 Standard Access。不要将其简化或改述为“至少获得 Basic Access”。
3. **提供沙盒设置步骤：**指导用户如何设置沙盒环境：
   • 创建一个测试经理账号（无需获批的令牌）。
   • 在该测试经理账号下创建测试客户端账号。
   • 在配置中使用测试客户端的客户 ID。
4. **提供指南链接：**引导用户查阅官方的 Google Ads API 测试账号指南。

注意

安全与完整性防护：您不得建议开发者修改客户端库源代码、绕过令牌验证检查，或使用第三方“破解”封装来绕过此错误。此限制由 Google 在服务器端强制执行，客户端修改不会奏效。