Google Ads API 快速上手：获取凭据并运行第一个拉取 Campaigns 的请求

Google Ads API 快速上手获取凭据并运行第一个拉取 Campaigns 的请求【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills如果你的目标是用 Google Ads API 完成第一次真实调用——拉取一个广告账户下的 Campaigns 列表那么你需要先凑齐五组鉴权参数再选择一条集成路径官方客户端库或原生 REST把请求发出去。这篇文章基于 skills 仓库中的 google-ads-api-quickstart 技能整理主路径是 Python 官方客户端库google-ads包备选路径是不依赖任何客户端库的直接 REST 请求。前提条件一个可登录的 Google Ads 账户或测试账户、一个 Google Cloud 项目以及终端中可用的gcloudCLI。开始前五组凭据参数从哪里来在写任何代码之前SKILL.md 要求先拿到五个参数。逐个说清楚它们的用途和获取位置。1. Developer Token用于标识你的开发者身份和 API 配额。获取方式用Manager 账户不能用普通投放账户登录 Google Ads进入 API Center地址见文档https://ads.google.com/aw/apicenter复制你的 Developer Token。一个关键限制如果 Token 状态是Pending未批准你只能调用 Google Ads 测试账户拿它调生产账户会直接报DEVELOPER_TOKEN_NOT_APPROVED。测试账户在 Google Ads 界面右上角有红色 Test account 横幅。2. OAuth2 Client ID 与 Client Secret用于向 Google OAuth 2.0 服务标识你的应用。在 Google Cloud Console 中操作新建或选择一个项目在 API Library 中搜索Google Ads API并点击Enable配置 OAuth Consent Screen用户类型选External发布状态设为Testing并把你登录 Google Ads 所用的账户邮箱添加为Test User——文档特别强调漏掉这步会导致后续授权被卡住进入APIs Services → Credentials → Create Credentials → OAuth client ID应用类型选Desktop App创建后点击下载图标JSON把文件保存为client_secrets.json。3. OAuth2 Refresh Token用于让应用自动换取新的 access 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命令执行后会打开浏览器登录窗口用你在 OAuth Consent Screen 里注册的Test User邮箱登录若应用未通过验证点击Advanced继续并授权。成功后gcloud会提示凭据保存位置通常是~/.config/gcloud/application_default_credentials.json——打开这个文件复制其中的refresh_token值。该文件就是保存在你本机上的 ADC 凭据文件注意不要把它提交到代码仓库。4. Client Customer ID你要查询的目标 Google Ads 账户的 10 位数字 ID不能带连字符1234567890而不是123-456-7890。登录 Google Ads 界面右上角用户头像旁显示的就是它。若你的 Developer Token 处于 Pending 状态这里必须是测试账户的 Customer ID。5. Login Customer ID当你的 OAuth 凭据和 Developer Token属于一个Manager 账户而你要查询的是它下面的子客户账户时这个参数是必填的login_customer_id填 Manager 账户的 10 位 IDclient_customer_id填子客户账户的 ID。文档明确指出在 Manager-Client 层级结构中漏填login_customer_id是权限类报错的第一大原因。确定 API 版本动态解析离线时有回退值SKILL.md 对版本的要求是不要硬编码执行前先从 Google Ads API Release Notes 或 googleapis 仓库解析最新稳定主版本RESOLVED_API_VERSIONPython 最低运行时版本从官方的 Supported Client Library Versions 页面解析。当这些页面不可达时文档给出的离线回退值是Google Ads API 主版本v24Java 客户端库版本34.0.0Python 最低版本3.9其余语言Java11、.NET6.0、PHP8.1、Ruby3.0、Perl5.28.1本文后续代码中的vXX占位符都按你解析出的版本或回退值v24替换。主路径Python 客户端库跑通第一个请求Python 参考文档是 references/python.md包名google-ads。环境安装文档建议在虚拟环境中安装以避免依赖冲突python3 -m venv .venv source .venv/bin/activate然后安装官方客户端库python -m pip install google-ads编写配置文件google-ads.yaml在项目根目录创建google-ads.yaml填入前面拿到的凭据。下方代码块中的INSERT_..._HERE占位符分别替换为你在第 1、2、3 步获得的 Developer Token、Client ID、Client Secret 和 Refresh Token# 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如果通过 Manager 账户访问子账户把login_customer_id一行的注释去掉并填入 Manager 账户 ID。关于配置文件的位置文档说明了load_from_storage的解析顺序① 显式传入的路径②GOOGLE_ADS_CONFIGURATION_FILE_PATH环境变量③ 默认的$HOME/google-ads.yaml。此外还支持load_from_env读取GOOGLE_ADS_前缀的环境变量、load_from_dict和load_from_string三种初始化方式。编写脚本get_campaigns.py文档给出的完整脚本如下。它先用 GAQL 查询SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id发起search_stream请求并在入口处自动去掉传入 Customer ID 中的连字符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)配置加载逻辑脚本优先在当前工作目录找google-ads.yaml找不到且设置了GOOGLE_ADS_DEVELOPER_TOKEN环境变量时走load_from_env()否则回退到默认搜索路径。运行并验证确认虚拟环境处于激活状态source .venv/bin/activate后把XXXXXXXXXX替换为你的 10 位 Customer ID带不带连字符都可以脚本会归一化python get_campaigns.py -c XXXXXXXXXX请求成功时文档给出的示例输出如下文档示例具体 Campaign 数量和名称以你的账户为准Querying Google Ads API... Campaign found: ID 123456789, Name Search - Brand - US, Status ENABLED Campaign found: ID 987654321, Name Display - Remarketing, Status PAUSED看到这样的Campaign found: ...行即说明凭据、Token 审批状态和账户访问三者都已就绪。请求失败时脚本会打印Request ID和每个错误的error.message错误信息就是下面排查部分的关键线索。可选路径不装客户端库直接发 REST 请求如果你的环境不适合装官方客户端库例如轻量 serverless 函数、受限运行时references/rest.md 给出直接 HTTP 的方式。与客户端库最大的区别是库会自动刷新 OAuth2 token而 REST 路径需要你手动先换出一个短时效 access token。第一步换取 access token文档列出两条授权路线路线 AService Account 流文档标注为 server-to-server 场景的推荐做法——在 Google Cloud Console 创建 Service Account 并下载 JSON 私钥在 Google Ads 界面授予该 Service Account 邮箱对你账户的直接访问Targeting 级别Explorer、Basic 或 Standard按官方 OAuth 2.0 Server to Server Applications 指南构造并签名 JWT claim setscope 用https://www.googleapis.com/auth/adwordssub参数可省略再到https://oauth2.googleapis.com/token端点交换 access token。路线 B用户授权流替代方案——如果你就是用自己第 3 步拿到的 refresh token直接用 cURL 交换。下面命令中的三处INSERT_..._HERE分别替换为你的 OAuth2 Client ID、Client Secret 和 Refresh Tokencurl \ --data grant_typerefresh_token \ --data client_idINSERT_OAUTH2_CLIENT_ID_HERE \ --data client_secretINSERT_OAUTH2_CLIENT_SECRET_HERE \ --data refresh_tokenINSERT_OAUTH2_REFRESH_TOKEN_HERE \ https://www.googleapis.com/oauth2/v3/token文档示例的响应 JSONaccess token 通常有效期约 1 小时{ access_token: ya29.a0AfH6S..., expires_in: 3599, scope: https://www.googleapis.com/auth/adwords, token_type: Bearer }复制access_token的值供下一步使用。第二步POST 到searchStream端点端点为https://googleads.googleapis.com/vXX/customers/{customer_id}/googleAds:searchStreamvXX替换为你解析出的 API 版本回退值v24方法POST请求头包括Content-Type: application/json、developer-token、Authorization: Bearer access_token以及在 Manager 账户认证时必需的login-customer-id。文档示例的 cURL 命令# Set your target Client Customer ID (10-digit number only, no hyphens) CUSTOMER_ID1234567890 curl --include --request POST https://googleads.googleapis.com/vXX/customers/${CUSTOMER_ID}/googleAds:searchStream \ --header Content-Type: application/json \ --header developer-token: INSERT_DEVELOPER_TOKEN_HERE \ --header Authorization: Bearer INSERT_OAUTH2_ACCESS_TOKEN_HERE \ --header login-customer-id: INSERT_LOGIN_CUSTOMER_ID_HERE \ --data { query: SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id }其中CUSTOMER_ID换成你的 10 位账户 ID三个INSERT_..._HERE分别换成 Developer Token、上一步拿到的 access token、Manager 账户 ID非 Manager 场景可去掉login-customer-id头。文档提示加--include或-i参数可以在响应头里看到request-id这是调试或联系 Google 支持时定位请求的关键。第三步解析流式 JSON 响应searchStream与普通 REST 端点不同它返回的是一段段结果包在 JSON 数组里的流。文档示例响应文档示例字段值以你的账户为准[ { results: [ { campaign: { resourceName: customers/1234567890/campaigns/987654321, id: 987654321, name: Interstate Search Promo, status: ENABLED } }, { campaign: { resourceName: customers/1234567890/campaigns/555444333, id: 555444333, name: Local Brand Awareness, status: PAUSED } } ], fieldMask: campaign.id,campaign.name,campaign.status } ]快速上手阶段的高频报错SKILL.md 和 python.md 给出了以下与首次运行直接相关的报错对照。报错根因文档判断处理方式USER_PERMISSION_DENIED认证用户是通过 Manager 账户间接拥有目标客户账户的访问权但请求中缺少 Manager 账户 ID在配置中补上 Manager 账户的 10 位 ID 作为login_customer_idDEVELOPER_TOKEN_NOT_APPROVEDDeveloper Token 还是 Pending 状态却被拿去调生产账户改用测试账户生产调用要求 Token 被批准到Explorer Access、Basic Access或Standard Access任一级别NOT_ADS_USER生成 refresh token 的 OAuth2 用户没有-c/--customer_id指定账户的访问权换用有目标账户访问权的 Google 账户重新走一遍 OAuth2 授权FileNotFoundException/File not found找不到google-ads.yaml确认文件名精确为google-ads.yaml且放在运行脚本的目录或$HOME下ModuleNotFoundError: No module named google库装进了虚拟环境脚本却用了全局 Python 解释器执行先source .venv/bin/activate再运行USER_PERMISSION_DENIED的 YAML 修复示例login_customer_id填 Manager 账户 IDdeveloper_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文档同时给了两条安全边界不要用暴露明文密码、新建未批准 Token 或扩大 OAuth scope 的方式绕过USER_PERMISSION_DENIEDDEVELOPER_TOKEN_NOT_APPROVED的限制是 Google 服务端强制的改客户端库源码或用第三方破解封装包都无效——正确做法是建测试 Manager 账户加测试客户账户在沙箱环境完成验证。下一步本文只展开了 Python 主路径。同一技能还带有 Java、.NET、PHP、Ruby、Perl 的等价参考文档凭据五参数是通用的只是配置文件格式如 Java 的ads.properties和安装方式不同。如果你的目标不是写脚本而是让 AI 助手Gemini、Cursor、Claude Code 等用自然语言查 Google AdsSKILL.md 明确要求不要走客户端库路线直接转到 google-ads-api-mcp-setup 技能 安装并配置官方 Google Ads MCP Server。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考