Google Ads API Python 快速上手环境配置、google-ads.yaml凭证管理、GAQL 查询与错误排查skills 仓库实战指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文是 GitHub 推荐项目精选 skills 仓库中 Google Ads API Python Setup Reference 的完整实战讲解。文章以该参考文档为核心骨架围绕 Python 官方客户端库google-ads的安装、凭证配置、首个 GAQL 查询脚本的编写与运行、以及常见错误的排查展开并融入仓库内 SKILL.md 中关于凭证获取、login_customer_id层级路由、动态版本解析等上下文帮助你从零开始跑通查询广告系列的第一个 Google Ads API 请求。读完本文你将掌握 Python 环境下 Google Ads API 的完整接入流程并能独立定位USER_PERMISSION_DENIED、DEVELOPER_TOKEN_NOT_APPROVED等高频故障。一、前置条件Python 版本与包管理器在开始之前请确认你的开发环境满足以下两个基础条件Python版本需达到最低支持版本MINIMUM_PYTHON_VERSION及以上。该占位符并非硬编码值——根据 SKILL.md 的动态运行时版本解析Dynamic Language Runtime Version Resolution要求应实时查阅官方 Supported Client Library Versions 文档页扫描其中Python客户端库对应的最低支持运行时版本例如 Python 3.8并将该版本替换到最终输出中。若官方页面不可达仓库记录的离线兜底版本为Python 3.9。包管理器pip。[!IMPORTANT]Action Required: 动态 Python 版本解析在向用户呈现前置条件之前必须动态解析最低 Python 版本以符合当前支持周期访问 Supported Client Library Versions 文档页扫描页面/表格中Python客户端库识别最低支持的 Python 运行时版本在最终输出中用动态获取的版本替换MINIMUM_PYTHON_VERSION占位符。此外整个集成过程中涉及的所有 API 版本与语言运行时版本都禁止硬编码例如v24、Python 3.8必须在执行开始时动态解析最新稳定版本。这与仓库 SKILL.md 中Crucial Requirement: Dynamic Version Resolution Runtime Resolution的约束保持一致。二、Step 1环境与安装[!TIP]最佳实践始终在虚拟环境venv中安装客户端库以避免与其他系统包产生依赖冲突。这对于在共享工作区中运行的自动化 Agent 尤其重要。1. 创建并激活虚拟环境在项目根目录执行以下命令python3 -m venv .venv source .venv/bin/activate2. 安装官方客户端库安装官方 Google Ads Python 客户端库python -m pip install google-ads安装包名为google-ads对应 SKILL.md 中 Python 轨道指定的 Package 名称。虚拟环境隔离了库依赖后续运行脚本时也必须保持该环境处于激活状态否则会出现ModuleNotFoundError详见本文错误排查一节。三、Step 2配置google-ads.yaml与多种加载方式在项目根目录创建一个名为google-ads.yaml的文件。Python 客户端库为GoogleAdsClient的初始化提供了四种加载方式YAML 文件load_from_storage按如下顺序解析配置文件——(1) 显式传给load_from_storage(/path/to/google-ads.yaml)的路径(2)GOOGLE_ADS_CONFIGURATION_FILE_PATH环境变量指定的路径(3) 默认的$HOME/google-ads.yaml。环境变量load_from_env读取大写GOOGLE_ADS_前缀的变量例如GOOGLE_ADS_DEVELOPER_TOKEN、GOOGLE_ADS_CLIENT_ID。注意如果设置了GOOGLE_ADS_CONFIGURATION_FILE_PATHload_from_env会改为从该 YAML 文件加载。字典load_from_dict直接接受一个包含凭证的 Python 字典。YAML 字符串load_from_string接受内存中的原始 YAML 字符串。[!IMPORTANT]封闭式工作区规则Hermetic Workspace Rule对于自包含的项目环境最佳实践是将google-ads.yaml放在项目根目录并显式加载它。向文件中填入你的凭证# 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 # Optional: Un-comment if you are accessing a client account through a manager account # login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE use_proto_plus: true配置参数说明配置键必填含义developer_token是开发者令牌标识你的开发者访问权限与 API 配额取自 Manager 账户的 API Centerclient_id/client_secret是OAuth2 客户端 ID 与密钥标识你的应用来自 Google Cloud Consolerefresh_token是长期有效的 OAuth2 刷新令牌用于自动换取短时访问令牌login_customer_id否10 位 Manager 账户 ID通过经理账户访问客户账户时必填use_proto_plus推荐启用 proto-plus 风格的响应对象使字段访问更贴近 Python 习惯如row.campaign.id关于凭证本身的获取流程Developer Token、OAuth2 Client ID/Secret、Refresh Token、Client Customer ID 与 Login Customer ID 五项参数SKILL.md 给出了完整指引Developer Token登录 Google AdsManager 账户后直接访问 API Centerhttps://ads.google.com/aw/apicenter复制。若令牌状态为 Pending未审批只能用于 Google Ads 测试账户否则调用生产账户会报DEVELOPER_TOKEN_NOT_APPROVED。OAuth2 Client ID Secret在 Google Cloud Console 中创建/选择项目 → 启用Google Ads API→ 配置 OAuth Consent Screen用户类型选ExternalPublishing Status 设为Testing并必须将登录 Google Ads 的邮箱添加为Test User→ 在 Credentials 中创建类型为Desktop App的 OAuth Client ID → 下载 JSON 保存为client_secrets.json。OAuth2 Refresh Token使用gcloudCLI 执行授权流程gcloud auth application-default login \ --scopeshttps://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \ --client-id-fileclient_secrets.json在浏览器中登录测试用户邮箱完成授权后gcloud会提示凭证保存位置通常为~/.config/gcloud/application_default_credentials.json从中复制refresh_token。Client Customer ID10 位数字、不带连字符如1234567890而非123-456-7890在 Google Ads UI 右上角用户图标旁可见。令牌处于 Pending 状态时此 ID必须是测试账户的 Customer ID。Login Customer ID10 位 Manager 账户 ID。若你的 OAuth 凭证与开发者令牌属于 Manager 账户但要查询其下的子/客户账户此参数必填。[!CAUTION]防止USER_PERMISSION_DENIED若通过 Manager 账户层级访问客户账户必须设置该参数。login_customer_idManager账户 IDclient_customer_id子/客户账户 ID。在 manager-client 层级中留空login_customer_id是权限错误的第一大原因。四、Step 3编写快速入门脚本创建名为get_campaigns.py的文件。[!IMPORTANT]规则 1规范化 Customer ID在将 Client Customer ID 传给 API 之前必须先去掉所有连字符进行规范化例如将123-456-7890转换为1234567890。下面的脚本在入口点已自动处理这一点。规则 2配置文件路径下面的脚本配置为先在当前工作目录查找google-ads.yaml再回退到环境变量或默认搜索路径。import argparse import os import sys from google.ads.googleads.client import GoogleAdsClient from google.ads.googleads.errors import GoogleAdsException def main(client, customer_id): # Initialize the Google Ads Service googleads_service client.get_service(GoogleAdsService) # Define the GAQL query query SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id print(Querying Google Ads API...) try: # Execute the search stream request stream googleads_service.search_stream(customer_idcustomer_id, queryquery) for response in stream: for row in response.results: print(fCampaign found: ID {row.campaign.id}, Name {row.campaign.name}, Status {row.campaign.status.name}) except GoogleAdsException as ex: print(fRequest ID {ex.request_id} failed with status {ex.error.code().name}:) for error in ex.failure.errors: print(f\tError: {error.message}) sys.exit(1) if __name__ __main__: # Determine configuration file path (prefer local workspace config) local_config os.path.join(os.getcwd(), google-ads.yaml) if os.path.exists(local_config): # Load explicitly from local workspace googleads_client GoogleAdsClient.load_from_storage(local_config) elif GOOGLE_ADS_DEVELOPER_TOKEN in os.environ: # Load from environment variables googleads_client GoogleAdsClient.load_from_env() else: # Fallback to default search paths (GOOGLE_ADS_CONFIGURATION_FILE_PATH or $HOME/google-ads.yaml) googleads_client GoogleAdsClient.load_from_storage() parser argparse.ArgumentParser(descriptionLists campaigns for a specified customer ID.) parser.add_argument(-c, --customer_id, requiredTrue, help10-digit customer ID.) args parser.parse_args() # Normalize customer ID by removing hyphens before passing to main normalized_customer_id args.customer_id.replace(-, ) main(googleads_client, normalized_customer_id)脚本要点解读查询服务初始化client.get_service(GoogleAdsService)返回 API 服务对象用于执行 GAQL 查询。GAQL 查询SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id使用 Google Ads Query LanguageGAQL声明式地选取广告系列资源。REST 轨道见 references/rest.md使用完全相同的查询串作为 POST body 中的query字段两种方式共享同一套 GAQL 语法。流式搜索search_stream以流式方式返回结果对应 REST 的googleAds:searchStream端点外层迭代response、内层迭代response.results逐行读取数据。异常处理GoogleAdsException暴露了request_id对排查与联系官方支持至关重要REST 路径下对应响应头中的request-id、error.code().name()错误码枚举名与failure.errors逐条错误消息。配置加载优先级脚本入口处的三段式逻辑——本地工作区google-ads.yaml优先 → 检测到GOOGLE_ADS_DEVELOPER_TOKEN环境变量时用load_from_env()→ 否则回退到默认搜索路径。这与本文第三节介绍的加载顺序一一对应。ID 规范化args.customer_id.replace(-, )在进入main前移除所有连字符遵循规则 1。五、Step 4运行脚本在终端中执行脚本传入客户 ID 作为参数。[!NOTE] 运行前请确保虚拟环境已激活source .venv/bin/activate。python get_campaigns.py -c XXXXXXXXXX将XXXXXXXXXX替换为你的 10 位客户 ID带或不带连字符均可。六、Step 5验证与错误排查期望的成功输出执行成功后应看到类似如下的输出Querying Google Ads API... Campaign found: ID 123456789, Name Search - Brand - US, Status ENABLED Campaign found: ID 987654321, Name Display - Remarketing, Status PAUSED常见错误对照表错误症状 / 错误码根因解决方案FileNotFoundException/File not found库找不到google-ads.yaml确保文件确切命名为google-ads.yaml并放在运行脚本的目录或$HOME目录下DEVELOPER_TOKEN_NOT_APPROVED使用未审批Pending的开发者令牌调用生产账户生产调用需要 Explorer、Basic 或 Standard 访问权限使用测试账户允许 Pending 令牌或等待令牌审批NOT_ADS_USER生成刷新令牌所用的 OAuth2 用户凭证无权访问指定的-c/--customer_id使用有权访问目标 Ads 账户的 Google 账户重新执行 OAuth2 授权流程ModuleNotFoundError: No module named googlePython 找不到已安装的库很可能是库安装在虚拟环境中却用全局 Python 解释器运行脚本确保先执行source .venv/bin/activate两类高频错误的深入排查1.USER_PERMISSION_DENIED症状执行 API 请求如检索广告系列时收到USER_PERMISSION_DENIED。可能原因认证的 OAuth2 用户通过Manager 账户间接拥有目标客户账户的访问权但请求头中缺少 Manager 账户 ID。按 SKILL.md 的诊断清单回复用户时应包含解释层级关系认证用户属于目标客户账户之上的 Manager 账户→ 在配置文件中将 10 位 Manager 账户 ID 加入login_customer_id→ 解释路由逻辑login_customer_id让 API 通过 Manager 账户路由 OAuth 凭证以校验对子账户的访问→ 给出修复配置示例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[!CAUTION]安全护栏任何情况下都不应通过暴露原始密码、创建新的未审批开发者令牌、或扩大 OAuth scope超出标准adwordsscope来绕过该错误。2.DEVELOPER_TOKEN_NOT_APPROVED症状脚本以DEVELOPER_TOKEN_NOT_APPROVED报错。可能原因开发者令牌处于 Pending未审批状态却试图访问真实的生产 Google Ads 账户。排查时需明确说明未审批的 Pending 令牌功能完整但仅限 Google Ads 测试账户生产账户必须由 Google Ads API 合规团队审批为Explorer Access、Basic Access或Standard Access三个级别之一不可简化为至少 Basic。沙箱搭建步骤为创建Test Manager 账户无需审批令牌→ 在其下创建Test Client 账户→ 在配置中使用 Test Client Customer ID。该限制由 Google 服务端强制执行修改客户端库源码或使用第三方包装器均无法绕过也不建议这样做。[!NOTE]静态诊断约束根据 SKILL.md排查时不应执行 bash 命令、运行本地测试脚本或在工作区复现错误而应完全依赖静态代码分析、配置审查与上述诊断指南以避免陷入反复失败的执行循环。七、纵向扩展Python 之外的接入路径理解 Python 快速入门后可顺带了解仓库中的其他接入方式它们共享同一套凭证体系与 GAQL 语法其他官方客户端库本技能支持 Python、Java、.NET、PHP、Ruby、Perl 六种官方客户端库与直接 REST 两种轨道见 SKILL.md对应参考文档位于 references/ 目录下如 java.md、ruby.md 等。各语言的关键差异在于配置文件格式与加载机制例如 Java 使用ads.properties键名为api.googleads.developerToken等并通过fromPropertiesFile()加载且需按 API 版本替换导入包名中的vXX占位符。直接 REST若运行环境不适合客户端库轻量 serverless 函数、自定义语言栈或受限运行时可参考 references/rest.md先通过 Service Account 流程推荐或用户认证流程换取短时access_token再向https://googleads.googleapis.com/vXX/customers/{customer_id}/googleAds:searchStream发起携带developer-token、Authorization: Bearer、login-customer-id头的POST请求body 中放入与本文相同的 GAQLquery。AI 助手 / MCP 集成如果你的目标是用自然语言让 AI 助手如 Gemini、Cursor、Claude Code查询 Google AdsSKILL.md 明确指示不要编写自定义脚本或客户端库代码而是直接转用仓库中的 google-ads-api-mcp-setup 技能安装官方 Google Ads MCP Serverpipx install google-ads-mcp该服务器通过 MCPstdio传输暴露list_accessible_customers、get_resource_metadata、search三个只读工具。查询与诊断类工作流如 google-ads-api-account-diagnostics也都是基于 GAQL 的search调用例如通过customer_client资源筛选启用的客户端账户SELECT customer_client.id, customer_client.descriptive_name, customer_client.status, customer_client.manager FROM customer_client WHERE customer_client.status ENABLED AND customer_client.manager FALSE八、小结通过本文你已完整走通 Google Ads API 的 Python 快速入门链路venv虚拟环境与google-ads安装 →google-ads.yaml凭证文件与四种GoogleAdsClient加载方式 →get_campaigns.py中 GAQL 流式查询与异常处理 → 四种常见错误的对照排查。整个流程与仓库 google-ads-api-quickstart 技能的指导原则完全一致凭证获取参考 SKILL.md 的 Step 1动态版本解析遵循其禁止硬编码约束login_customer_id与 Pending 令牌规则贯穿始终。掌握了 Python 客户端的这一最小闭环后你可以向两个方向自然延伸一是对照 references/ 中的 Java、.NET、PHP、Ruby、Perl 或 REST 文档迁移到其他技术栈二是通过 google-ads-api-mcp-setup 将同一套凭证接入 MCP 生态让 AI 助手以自然语言完成后续的账户查询与性能诊断参考 google-ads-api-account-diagnostics。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考