google-ads-api-quickstart

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Ads API Quickstart

Google Ads API快速入门

This skill guides you from absolute zero to running your first successful request to retrieve campaigns.

本技能将指导您从零基础开始，成功运行第一个获取广告系列的请求。

Supported Tracks

支持的接入方式

You can choose to use this skill with:

Official Client Libraries: Python, Java, .NET, PHP, Ruby, or Perl.
Direct REST: Raw HTTP REST requests.

您可以选择以下方式使用本技能：

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

Crucial Requirement: Dynamic Version Resolution & Runtime Resolution

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

[!IMPORTANT] To ensure the integration is secure, stable, and up-to-date, you must resolve all API and runtime versions dynamically. Do not rely on hardcoded defaults.

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

Strict Constraints:

严格约束：

DO NOT Hardcode: Never use hardcoded Google Ads API versions (e.g.,
```
v24
```
) or language runtime versions (e.g.,
```
Python 3.8+
```
,
```
Java 11+
```
) in generated code or environment setup instructions, unless the user explicitly requests a specific version.
MANDATORY Dynamic Resolution: You must dynamically resolve the latest stable versions at the start of execution before generating any code or configuration, using the procedures detailed below.

禁止硬编码：切勿在生成的代码或环境设置说明中使用硬编码的Google Ads API版本（例如
```
v24
```
）或语言运行时版本（例如
```
Python 3.8+
```
、
```
Java 11+
```
），除非用户明确要求特定版本。
必须动态解析：在生成任何代码或配置之前，您必须在执行开始时使用下文详述的流程动态解析最新的稳定版本。

A. Dynamic API Version Resolution

A. 动态API版本解析

To ensure the integration is secure, stable, and up-to-date, you MUST resolve the absolute newest stable major version of the Google Ads API dynamically.

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

Execution Steps:

执行步骤：

Pre-Flight Version Resolution: Use your web search or URL-reading tools to inspect the latest entry in the Google Ads API Release Notes or the highest versioned directory in the Googleapis Github Repository to resolve
```
RESOLVED_API_VERSION
```
(e.g.,
```
v24
```
). If using Java, you MUST also resolve the latest stable release version of the Google Ads Java Client Library (referred to as
```
RESOLVED_LIBRARY_VERSION
```
, e.g.,
```
34.0.0
```
).
Mandatory Response Anchor: You MUST output the following confirmation block as the very first line of your response to the user. Do not output any greeting, pleasantries, or introductory text before this block.
text
```
[SYSTEM: Using Google Ads API version: RESOLVED_API_VERSION (Resolved from release notes)]
```

Strict Placeholder Mapping Table: You MUST perform on-the-fly search-and-replace on all code templates and reference files using the mapping table below. Do not leave raw placeholders in the final output.

Target Language / Tech	Placeholder in Template	Replacement Pattern	Example (Assuming API `v24` )
Java (Maven/Gradle)	`LATEST_LIBRARY_VERSION`	Search & substitute the latest Maven release version of the library.	`34.0.0`
Java (Imports)	`vXX`	Replace with lower-case API version.	`com.google.ads.googleads.v24`
.NET / C# (Namespaces)	`VXX`	Replace with title-case API version.	`Google.Ads.GoogleAds.V24`
PHP (Namespaces)	`VXX`	Replace with title-case API version.	`Google\Ads\GoogleAds\V24`
REST (Endpoint URL)	`vXX`	Replace with lower-case API version.	`https://googleads.googleapis.com/v24/...`

[!TIP] Offline Fallback: If the URLs are unreachable or the scrape fails, do not halt execution. Fall back to these last-known stable versions:
Google Ads API Major Version (
RESOLVED_API_VERSION
):
v24
Java Client Library Version (
RESOLVED_LIBRARY_VERSION
):
34.0.0

预检查版本解析：使用网页搜索或URL读取工具，查看Google Ads API发布说明中的最新条目，或Googleapis GitHub仓库中版本号最高的目录，以解析
```
RESOLVED_API_VERSION
```
（例如
```
v24
```
）。如果使用Java，您还必须解析Google Ads Java客户端库的最新稳定版本（称为
```
RESOLVED_LIBRARY_VERSION
```
，例如
```
34.0.0
```
）。
必须输出的确认块：您必须在对用户的响应中第一行输出以下确认块。在此块之前，不得输出任何问候语、客套话或介绍性文本。
text
```
[SYSTEM: Using Google Ads API version: RESOLVED_API_VERSION (Resolved from release notes)]
```

严格的占位符映射表：您必须使用下面的映射表，对所有代码模板和参考文件进行即时搜索替换。最终输出中不得保留原始占位符。

目标语言/技术	模板中的占位符	替换规则	示例（假设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/...`

[!TIP] 离线 fallback 方案：如果URL无法访问或抓取失败，请勿停止执行。使用以下已知的最新稳定版本作为 fallback：
Google Ads API主版本（
RESOLVED_API_VERSION
）：
v24
Java客户端库版本（
RESOLVED_LIBRARY_VERSION
）：
34.0.0

B. Dynamic Language Runtime Version Resolution

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

To prevent the generated setup guides from becoming obsolete due to language deprecation cycles, you MUST resolve language requirements dynamically.

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

Execution Steps:

执行步骤：

Fetch Live Requirements: Use your URL-reading tools to inspect the official Google Ads Client Libraries - Supported Versions page.
Extract Minimums: Identify the minimum supported runtime version for the user's chosen language by scanning the Overview page or compatibility tables (e.g., looking for explicit requirements like Python 3.8+, Java 11+, .NET 6.0+, PHP 8.1+, Ruby 3.0+).
Apply On-The-Fly: Substitute all runtime placeholders (e.g.,
```
<PYTHON_MIN_VERSION>
```
) in your generated setup guides with these resolved versions.

[!TIP] Offline Fallback: If the URL is unreachable or the scrape fails, do not halt execution. Fall back to these last-known safe minimum versions:
Python:
3.9+
Java:
11+
.NET:
6.0+
PHP:
8.1+
Ruby:
3.0+
Perl:
5.28.1+

获取实时要求：使用URL读取工具查看官方的Google Ads客户端库 - 支持版本页面。
提取最低版本：通过扫描概述页面或兼容性表格，确定用户所选语言的最低支持运行时版本（例如查找明确要求，如Python 3.8+、Java 11+、.NET 6.0+、PHP 8.1+、Ruby 3.0+）。
即时应用：将生成的设置指南中的所有运行时占位符（例如
```
<PYTHON_MIN_VERSION>
```
）替换为这些解析后的版本。

[!TIP] 离线 fallback 方案：如果URL无法访问或抓取失败，请勿停止执行。使用以下已知的安全最低版本作为 fallback：
Python：
3.9+
Java：
11+
.NET：
6.0+
PHP：
8.1+
Ruby：
3.0+
Perl：
5.28.1+

Step 1: Obtain Google Ads API Credentials

步骤1：获取Google Ads API凭证

Before installing libraries or making API calls, you must obtain the five required authentication parameters.

在安装库或调用API之前，您必须获取五个必需的认证参数。

1. Developer Token

1. 开发者令牌（Developer Token）

Purpose: Identifies your developer access and API quota.
How to Obtain:
1. Navigate directly to the API Center in your Google Ads Manager Account: https://ads.google.com/aw/apicenter (Note: You must sign in with a Manager account, not a standard serving account).
2. Copy your Developer Token.

[!WARNING] Pending Token Restriction: If your Developer Token status is "Pending" (unapproved), you MUST ONLY target Google Ads Test Accounts. Attempting to call a production account with a pending token will fail with the error:
DEVELOPER_TOKEN_NOT_APPROVED
.

用途：标识您的开发者权限和API配额。
获取方式：
1. 直接导航到Google Ads经理账户中的API中心：https://ads.google.com/aw/apicenter （注意：您必须使用经理账户登录，而非标准投放账户）。
2. 复制您的开发者令牌。

[!WARNING] 待审核令牌限制：如果您的开发者令牌状态为“待审核”（未获批），您只能针对Google Ads测试账户进行操作。尝试使用待审核令牌调用生产账户将失败，并返回错误：
DEVELOPER_TOKEN_NOT_APPROVED
。

2. OAuth2 Client ID & Client Secret

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

Purpose: Identifies your application to Google's OAuth 2.0 server and allows you to request user authorization.
How to Obtain:
1. Open the Google Cloud Console.
2. Create a new project (or select an existing one).
3. Search for the Google Ads API in the API Library and click Enable.
4. Configure the OAuth Consent Screen:
  - Select External user type.
  - Set the Publishing Status to Testing.
  - [!IMPORTANT]
  - Add Test Users: You MUST add the email address of the Google account you use to log into Google Ads as a Test User in this step. Otherwise, you will be blocked during authorization.
5. Create the OAuth Client:
  - Go to APIs & Services 🡒 Credentials.
  - Click Create Credentials 🡒 OAuth client ID.
  - Select Desktop App as the Application Type.
  - Name the client and click Create.
6. Download Secrets: Click the download icon (JSON) next to your newly created Client ID. Save this file locally as
```
client_secrets.json
```
  .

用途：向Google的OAuth 2.0服务器标识您的应用，并允许您请求用户授权。
获取方式：
1. 打开Google Cloud控制台。
2. 创建新项目（或选择现有项目）。
3. 在API库中搜索Google Ads API并点击启用。
4. 配置OAuth同意屏幕：
  - 选择外部用户类型。
  - 将发布状态设置为测试。
  - [!IMPORTANT]
  - 添加测试用户：您必须将用于登录Google Ads的谷歌账户邮箱地址添加为测试用户。否则，您在授权过程中将被阻止。
5. 创建OAuth客户端：
  - 转到API与服务 🡒 凭证。
  - 点击创建凭证 🡒 OAuth客户端ID。
  - 选择桌面应用作为应用类型。
  - 为客户端命名并点击创建。
6. 下载密钥：点击新创建的客户端ID旁边的下载图标（JSON）。将此文件本地保存为
```
client_secrets.json
```
  。

3. OAuth2 Refresh Token

3. OAuth2刷新令牌

Purpose: Allows your application to obtain new access tokens automatically without requiring manual user login every hour.
How to Obtain: You must run the Google Cloud (
```
gcloud
```
) CLI to generate your refresh token.
1. Install and Verify gcloud CLI:

Ensure the gcloud CLI is installed and available in your terminal.

2. Execute the Login Flow:
Run the following command in your terminal, passing the path to the
```
client_secrets.json
```
file downloaded in the previous step:
bash
```
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. Authorize in Browser:
1. The command will open a Google Account login window in your browser.
2. Sign in using the Test User email registered in your OAuth Consent Screen setup.
3. If your app is unverified, click Advanced and continue to the project. Click Continue to grant permissions.
4. Retrieve Your Refresh Token:
Once successful,
```
gcloud
```
will output a message indicating where the credentials were saved (typically
```
~/.config/gcloud/application_default_credentials.json
```
). Open that file to copy your
```
refresh_token
```
.

用途：允许您的应用自动获取新的访问令牌，无需每小时手动登录。
获取方式：您必须运行Google Cloud（
```
gcloud
```
）CLI来生成刷新令牌。
1. 安装并验证gcloud CLI：

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

2. 执行登录流程：
在终端中运行以下命令，传入上一步下载的
```
client_secrets.json
```
文件路径：
bash
```
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. 该命令将在浏览器中打开谷歌账户登录窗口。
2. 使用在OAuth同意屏幕设置中注册的测试用户邮箱登录。
3. 如果您的应用未经过验证，点击高级并继续访问项目。点击继续以授予权限。
4. 获取刷新令牌：
成功后，
```
gcloud
```
将输出一条消息，指示凭证保存的位置（通常为
```
~/.config/gcloud/application_default_credentials.json
```
）。打开该文件以复制您的
```
refresh_token
```
。

4. Client Customer ID

4. 客户端客户ID（Client Customer ID）

Purpose: The 10-digit ID of the specific Google Ads account you want to query or make changes to.
Format: Must be 10 digits with no hyphens (e.g.,
```
1234567890
```
, NOT
```
123-456-7890
```
).
How to Find It: Log in to the Google Ads UI; the ID is displayed in the top-right corner next to your user icon.

[!IMPORTANT] Test Account Requirement: If your Developer Token is pending (unapproved), this MUST be the Customer ID of a Test Account. Test accounts have a red "Test account" banner in the top right of the UI.

用途：您要查询或修改的特定Google Ads账户的10位ID。
格式：必须为10位数字，无连字符（例如
```
1234567890
```
，而非
```
123-456-7890
```
）。
查找方式：登录Google Ads UI，ID显示在右上角用户图标旁边。

[!IMPORTANT] 测试账户要求：如果您的开发者令牌处于待审核（未获批）状态，此ID必须是测试账户的客户ID。测试账户在UI右上角会显示红色的“测试账户”横幅。

5. Login Customer ID

5. 登录客户ID（Login Customer ID）

What it is: The 10-digit Customer ID of the Google Ads Manager Account that owns or manages the target client account.
Format: Must be 10 digits with no hyphens (e.g.,
```
9876543210
```
).
When to Use: This is mandatory if your OAuth credentials (and developer token) belong to a Manager Account, but you are querying a child/client account (Client Customer ID).

[!CAUTION] Preventing
USER_PERMISSION_DENIED
: If you are accessing a client account through a Manager Account hierarchy, you MUST set this parameter.
login_customer_id
= The Manager Account ID.
client_customer_id
= The Child/Client Account ID. Leaving
login_customer_id
blank in a manager-client hierarchy is the #1 cause of permission errors.

定义：拥有或管理目标客户端账户的Google Ads经理账户的10位客户ID。
格式：必须为10位数字，无连字符（例如
```
9876543210
```
）。
使用场景：如果您的OAuth凭证（和开发者令牌）属于经理账户，但您要查询子账户/客户端账户（客户端客户ID），则此参数必填。

[!CAUTION] 避免
USER_PERMISSION_DENIED
错误：如果您通过经理账户层级访问客户端账户，您必须设置此参数。
login_customer_id
= 经理账户ID。
client_customer_id
= 子账户/客户端账户ID。在经理-客户端层级中遗漏
login_customer_id
是权限错误的头号原因。

Step 2: Choose Your Integration Strategy

步骤2：选择集成策略

Developers can connect to the Google Ads API using either the official high-level client libraries or direct HTTPS REST requests.

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

Path A: Official Client Libraries (Recommended)

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

[!IMPORTANT] Mandatory Agent Directive: Once the user selects their language, you MUST:
Use the
view_file
tool to lazy-load the corresponding reference file listed below.
Apply the Dynamic Version Resolution (Section B) to dynamically replace all
vXX
/
VXX
placeholders and library versions before generating code.

[!IMPORTANT] 必须遵循的Agent指令：一旦用户选择了语言，您必须：
使用
view_file
工具懒加载下面列出的对应参考文件。
应用动态版本解析（B部分），在生成代码前动态替换所有
vXX
/
VXX
占位符和库版本。

Python

If you need to set up the Google Ads API environment for Python, do not guess the configuration. Instead, read the detailed setup guide:

Google Ads API Python Setup Reference (Package:
google-ads
)

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

Google Ads API Python设置参考 (包：
google-ads
)

Java

If you need to set up the Google Ads API environment for Java, do not guess the configuration. Instead, read the detailed setup guide:

Google Ads API Java Setup Reference (Artifact:
com.google.api-ads:google-ads
)

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

Google Ads API Java设置参考 (构件：
com.google.api-ads:google-ads
)

.NET / C#

If you need to set up the Google Ads API environment for .NET/C#, do not guess the configuration. Instead, read the detailed setup guide:

Google Ads API .NET Setup Reference (Package:
Google.Ads.GoogleAds
)

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

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

PHP

If you need to set up the Google Ads API environment for PHP, do not guess the configuration. Instead, read the detailed setup guide:

Google Ads API PHP Setup Reference (Package:
googleads/google-ads-php
)

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

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

Ruby

If you need to set up the Google Ads API environment for Ruby, do not guess the configuration. Instead, read the detailed setup guide:

Google Ads API Ruby Setup Reference (Gem:
google-ads-ruby
)

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

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

Perl

If you need to set up the Google Ads API environment for Perl, do not guess the configuration. Instead, read the detailed setup guide:

Google Ads API Perl Setup Reference (Package:
Google::Ads::GoogleAds::Client
)

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

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

Path B: Direct HTTP REST (No Library Overhead)

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

Use this path if the user's environment does not support the official client libraries (e.g., lightweight serverless functions, custom language stacks, or restricted runtimes).

[!IMPORTANT] Mandatory Agent Directive: If the user chooses the REST path, you MUST:
Use the
view_file
tool to lazy-load the REST reference file below.
Apply Dynamic Version Resolution (Section B) to replace all
vXX
placeholders in the endpoint URLs (e.g., resolving
vXX
to
v24
in
https://googleads.googleapis.com/v24/...
).

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

[!IMPORTANT] 必须遵循的Agent指令：如果用户选择REST路径，您必须：
使用
view_file
工具懒加载下面的REST参考文件。
应用动态版本解析（B部分），替换端点URL中的所有
vXX
占位符（例如将
https://googleads.googleapis.com/vXX/...
中的
vXX
解析为
v24
）。

REST (HTTP)

REST（HTTP）

If you need to set up the Google Ads API environment for REST (HTTP), do not guess the configuration. Instead, read the detailed setup guide:

Google Ads API REST Setup Reference (Protocol: Raw HTTP POST JSON)

如果您需要为REST（HTTP）设置Google Ads API环境，请不要猜测配置。请阅读详细的设置指南：

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

Cross-Referencing: AI-Assistant & MCP Connection

交叉参考：AI助手与MCP连接

[!TIP] AI Assistant / MCP Integration Handoff: If the goal is to connect an AI Assistant (such as Gemini, Cursor, or Claude Code) to query Google Ads via natural language:
DO NOT write custom scripts or client library code.

STOP executing this skill.
Transition Immediately to the google-ads-api-mcp-setup
skill to install and configure the official Google Ads Model Context Protocol (MCP) Server.

[!TIP] AI助手/MCP集成交接：如果目标是将AI助手（如Gemini、Cursor或Claude Code）连接到Google Ads以通过自然语言查询：
不要编写自定义脚本或客户端库代码。

停止执行此技能。
立即切换到**
google-ads-api-mcp-setup
**技能，以安装和配置官方Google Ads模型上下文协议（MCP）服务器。

Step 4: Troubleshooting Common Errors

步骤4：常见错误排查

[!IMPORTANT] Static Diagnostics Constraint: When troubleshooting, you MUST NOT execute bash commands, run local test scripts, or attempt to reproduce the error in the workspace. Rely entirely on static code analysis, configuration review, and the diagnostic guides below to prevent endless, failing execution loops.

[!IMPORTANT] 静态诊断约束：排查错误时，您不得执行bash命令、运行本地测试脚本或尝试在工作区中重现错误。完全依赖静态代码分析、配置审查和下面的诊断指南，以避免无休止的失败执行循环。

1. Error:

USER_PERMISSION_DENIED

1. 错误：

USER_PERMISSION_DENIED

Symptom: You receive a
```
USER_PERMISSION_DENIED
```
error when executing API requests (e.g., retrieving campaigns).
Likely Cause: The authenticating OAuth2 user has access to the target client account indirectly through a Manager Account, but the request header is missing the Manager Account's ID.

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

Required Agent Response Checklist:

必须包含的Agent响应清单：

When helping a user with this error, your response MUST include:

Explain the Hierarchy: Explain that the authenticating user likely belongs to a Manager Account that sits above the target client account.
Provide the Fix: Instruct the user to add their 10-digit Manager Account ID as the
```
login_customer_id
```
in their configuration file.
Explain the Routing Logic: Explain that
```
login_customer_id
```
tells the API to route the OAuth credentials through the manager account to validate access to the child account.
Provide the Configuration Template: Show the exact YAML configuration block below.

[!CAUTION] Security Guardrail: Under no circumstances should you suggest exposing raw passwords, creating new unapproved developer tokens, or widening OAuth scopes beyond the standard
adwords
scope to bypass this error.

当帮助用户解决此错误时，您的响应必须包含：

解释层级关系：说明进行身份验证的用户可能属于目标客户端账户上方的经理账户。
提供修复方案：指导用户将10位经理账户ID添加为配置文件中的
```
login_customer_id
```
。
解释路由逻辑：说明
```
login_customer_id
```
告知API通过经理账户路由OAuth凭证，以验证对子账户的访问权限。
提供配置模板：展示以下确切的YAML配置块。

[!CAUTION] 安全防护：在任何情况下，您都不得建议暴露原始密码、创建新的未获批开发者令牌，或扩大OAuth范围超出标准
adwords
范围以绕过此错误。

Configuration Fix Example (

google-ads.yaml

配置修复示例（

google-ads.yaml

）：

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

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:

添加您的10位经理账户ID以解决USER_PERMISSION_DENIED错误：

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

undefined

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

undefined

2. Error:

DEVELOPER_TOKEN_NOT_APPROVED

2. 错误：

DEVELOPER_TOKEN_NOT_APPROVED

Symptom: The script fails with a
```
DEVELOPER_TOKEN_NOT_APPROVED
```
error message.
Likely Cause: Your Developer Token is currently in the "Pending" (unapproved) state, and you are attempting to target a live production Google Ads account.

症状：脚本执行失败，返回
```
DEVELOPER_TOKEN_NOT_APPROVED
```
错误消息。
可能原因：您的开发者令牌当前处于“待审核”（未获批）状态，而您尝试针对实时生产Google Ads账户进行操作。

Required Agent Response Checklist:

必须包含的Agent响应清单：

When helping a user with this error, your response MUST include:

Explain the "Pending" Restriction: Explain that an unapproved (Pending) developer token is fully functional but restricted to Google Ads Test Accounts only.
Define Production Access Levels: You MUST explicitly list all three access levels by name: state that targeting live production accounts requires the token to be approved for Explorer Access, Basic Access, or Standard Access by the Google Ads API compliance team. Do not condense or paraphrase this to "at least Basic Access".
Provide Sandbox Setup Steps: Guide the user on how to set up a sandbox environment:
- Create a Test Manager Account (which does not require an approved token).
- Create Test Client Accounts under that Test Manager.
- Use the Test Client Customer ID in their configuration.
Provide a Link to the Guide: Point the user to the official Google Ads API Test Accounts Guide.

[!CAUTION] Security & Integrity Guardrail: You MUST NOT advise the developer to modify the client library source code, bypass token validation checks, or use third-party "cracked" wrappers to bypass this error. The restriction is enforced server-side by Google, and client-side modifications will not work.

当帮助用户解决此错误时，您的响应必须包含：

解释“待审核”限制：说明未获批（待审核）的开发者令牌功能完整，但仅能用于Google Ads测试账户。
定义生产访问级别：您必须明确列出所有三个访问级别名称：说明针对实时生产账户需要令牌获得Google Ads API合规团队的探索者访问权限、基础访问权限或标准访问权限。不得将其简化或转述为“至少基础访问权限”。
提供沙箱设置步骤：指导用户如何设置沙箱环境：
- 创建测试经理账户（无需获批令牌）。
- 在该测试经理账户下创建测试客户端账户。
- 在配置中使用测试客户端客户ID。
提供指南链接：将用户指向官方的Google Ads API测试账户指南。

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

google-ads-api-quickstart

Original

Translation

Google Ads API Quickstart

Google Ads API快速入门

Supported Tracks

支持的接入方式

Crucial Requirement: Dynamic Version Resolution & Runtime Resolution

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

Strict Constraints:

严格约束：

A. Dynamic API Version Resolution

A. 动态API版本解析

Execution Steps:

执行步骤：

B. Dynamic Language Runtime Version Resolution

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

Execution Steps:

执行步骤：

Step 1: Obtain Google Ads API Credentials

步骤1：获取Google Ads API凭证

1. Developer Token

1. 开发者令牌（Developer Token）

2. OAuth2 Client ID & Client Secret

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

3. OAuth2 Refresh Token

3. OAuth2刷新令牌

1. Install and Verify gcloud CLI:

2. Execute the Login Flow:

3. Authorize in Browser:

4. Retrieve Your Refresh Token:

1. 安装并验证gcloud CLI：

2. 执行登录流程：

3. 在浏览器中授权：

4. 获取刷新令牌：

4. Client Customer ID

4. 客户端客户ID（Client Customer ID）

5. Login Customer ID

5. 登录客户ID（Login Customer ID）

Step 2: Choose Your Integration Strategy

步骤2：选择集成策略

Path A: Official Client Libraries (Recommended)

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

Python

Python

Java

Java

.NET / C#

.NET / C#

PHP

PHP

Ruby

Ruby

Perl

Perl

Path B: Direct HTTP REST (No Library Overhead)

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

REST (HTTP)

REST（HTTP）

Cross-Referencing: AI-Assistant & MCP Connection

交叉参考：AI助手与MCP连接

Step 4: Troubleshooting Common Errors

步骤4：常见错误排查

1. Error: USER_PERMISSION_DENIED

1. 错误：USER_PERMISSION_DENIED

Required Agent Response Checklist:

必须包含的Agent响应清单：

Configuration Fix Example (google-ads.yaml):

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

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

添加您的10位经理账户ID以解决USER_PERMISSION_DENIED错误：

2. Error: DEVELOPER_TOKEN_NOT_APPROVED

2. 错误：DEVELOPER_TOKEN_NOT_APPROVED

Required Agent Response Checklist:

必须包含的Agent响应清单：

1. Error:
`USER_PERMISSION_DENIED`

1. 错误：
`USER_PERMISSION_DENIED`

Configuration Fix Example (
`google-ads.yaml`
):

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

2. Error:
`DEVELOPER_TOKEN_NOT_APPROVED`

2. 错误：
`DEVELOPER_TOKEN_NOT_APPROVED`