2026 年 Google Ads API 访问：Cloud 项目取代开发者令牌
自 2026 年 9 月 9 日起，Google Ads API 的访问权限按 Google Cloud 项目授予，而不再按开发者令牌授予。本文说明发生了哪些变化、如何设置当前的访问权限，以及 2026 年 6 月的搭建指南中哪些内容依然适用。
2026 年 9 月 9 日发生了哪些变化
我们在 2026 年 6 月发布的 Google Ads API 搭建、认证与读写操作指南以开发者令牌为基础：在经理账号的 API Center 中申请令牌，在那里申请 Basic 访问权限，并在每次调用时发送该令牌。三个月后，这一基础发生了变化。Google 自己的文档现在明确写道："Developer tokens were sunset on September 9, 2026."
访问权限的决定本身并没有消失，而是转移了位置。您的 API 访问级别现在由您生成 OAuth 凭据时所用的 Google Cloud 项目决定，现有访问权限已自动迁移到 Cloud 项目。申请不再在 API Center 中提交；Google 要求开发者不要再在 API Center 申请开发者令牌，而是改为在 Google Cloud Console 的 Google Ads API Overview 页面申请访问权限。仍在 API Center 中待处理的 Basic 申请已被关闭，需要从 Cloud Console 重新提交。
6 月的指南按原样保留在线上，并在顶部添加了带日期的说明。本文作为后续跟进，介绍当前有何不同，并在早期内容仍然适用之处链接回原文。
访问级别现在属于 Cloud 项目
各访问级别本身并不陌生，只是新增了一项要求。以下限制取自 Google 截至 2026 年 10 月的访问级别文档：
| 访问级别 | 生产账号 | 每日操作数 |
|---|---|---|
| Test | 否，仅限测试账号 | 15,000 |
| Explorer | 是 | 针对生产账号 2,880 |
| Basic | 是 | 15,000 |
| Standard | 是 | 无总体上限（个别服务仍可能受限） |
Explorer 是实际的入门级别。据 Google 介绍，通过 Cloud Console 提交的申请会被自动审核，大多数情况下会升级为 Explorer 访问权限——足以满足内部报表和在自有账号上进行少量自动化的需求。Basic 和 Standard 仍需审核，且两者现在都新增了一项前提条件：对 Google Cloud 项目进行品牌验证。Standard 还涉及人工审计。
问题在于，技术搭建已经正常运行时，品牌验证很容易被忽视。在 Explorer 访问权限下运行的脚本在达到每日上限之前都会表现正常，因此请在业务量到来之前规划好验证，而不是之后。
当前的访问设置步骤
流程比以前更短，因为 Cloud 项目现在是决定访问权限的唯一位置：
- 创建一个 Google Cloud 项目，或选择将承载您的 Google Ads 集成的现有项目。此步骤无需开通结算。
- 在该项目的 API 库中启用 Google Ads API。
- 在同一个项目中创建凭据——基于用户的访问使用 OAuth 客户端，或使用带 JSON 密钥的服务账号。
- 在 Cloud Console 的 Google Ads API Overview 页面申请访问权限；如需 Basic 或 Standard 访问权限，请完成品牌验证。
这里的关键是第 3 步。由于访问权限跟随签发 OAuth 凭据的项目，来自另一个无关项目的凭据不会继承您所申请的访问级别。多年来在不同项目中创建过测试客户端的团队，应在依赖生产访问权限之前加以整合。
6 月指南中的 OAuth 细节——adwords 范围、用于获取刷新令牌的离线访问、刷新令牌失效的原因——均未改变，依然适用。
认证与配置
开发者令牌在实际中已变为可选。Google 表示，您仍可继续在请求标头中发送它，但服务器会忽略它，且预计未来的 API 主版本将拒绝它。官方 Python 库 32.0.0 版本移除了要求配置中必须包含令牌的检查。
因此，基于用户 OAuth 的最简 google-ads.yaml 如下：
client_id: YOUR_CLIENT_ID.apps.googleusercontent.com
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
login_customer_id: "1234567890"
use_proto_plus: true对于服务账号，json_key_file_path 取代三个 OAuth 密钥，也可以与 impersonated_email 搭配使用。每个密钥还可以通过带 GOOGLE_ADS_ 前缀的环境变量来设置，例如 GOOGLE_ADS_JSON_KEY_FILE_PATH——在配置文件容易进入备份和代码仓库的服务器上，这是更稳妥的选择。
login_customer_id 的含义保持不变。通过经理账号访问客户账号时，它指定的是该经理账号（仅数字，不含连字符）。缺少它时，此类调用会以 USER_PERMISSION_DENIED 失败。
版本与 Python 库
版本固定值得比通常更多的关注。6 月的指南使用了 version="v22"，而该版本已不再可用：google-ads Python 库的 33.0.0 版本移除了 v21 和 v22。截至 2026 年 10 月，当前的 API 版本为 v26（2026 年 10 月 14 日发布），库 34.0.0 增加了对它的支持。
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("google-ads.yaml", version="v26")明确固定版本仍然是正确的默认做法。实际上，未固定版本的客户端会在下次升级库时悄然改变行为，而 Google 会按公布的时间表停用 API 版本——固定版本至少能把这种停用变成有计划的变更，而不是突如其来的意外。
欧盟政治广告声明
有一项要求让许多现有集成措手不及：Campaign 资源上的 contains_eu_political_advertising 字段。在 v26 之前的 API 版本中，每个新广告系列都必须声明该字段。自 2026 年 4 月 1 日起，当账号中仍存在未声明的广告系列时，mutate 调用会以 EU_POLITICAL_ADVERTISING_DECLARATION_REQUIRED 失败。v26 放宽了这一要求：对于不以欧盟为明确定位目标的广告系列，该字段变为可选。
明确声明只需一行代码，并能让广告系列创建代码在各版本间保持有效：
campaign.contains_eu_political_advertising = (
client.enums.EuPoliticalAdvertisingStatusEnum.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING
)6 月指南中沿用的内容
早先的讲解大部分涉及的是如何使用 API，而不是如何获得访问权限，这部分内容依然经得起时间考验。GAQL 读取查询、用于安全测试写入操作的 validate_only 模式、对 update_mask 的显式处理，以及经理账号、Cloud 项目和目标账号三者的分离，均按原文所述适用。不再适用的是访问途径：API Center、开发者令牌申请，以及基于令牌的架构图。
一个好的集成——无论是内部脚本还是面向客户的工具——都会把访问权限视为由某个明确命名的 Cloud 项目所拥有的配置。这在 2026 年 9 月之前就是合理的做法；自那以后，它正是 Google 定义访问权限的方式。