用途
本技能用于指导通过 treg 调用 Google Ads API 时的常见陷阱与正确做法。所有条目基于 2026-07-22 在真实账户上通过 treg call google-ads 的实测验证，并标注了各陷阱在无此文件时被独立代理触发的次数，帮助判断哪些是真实高频问题。
主要能力与要点
1. 固定 API 版本
路径带版本号，猜错会返回 Google 的 HTML 404 而非 JSON，且 API 与 treg tool ls 都不报告当前版本。应使用 v25（2026-07-22 发布，2026-08-17 经代理实测，约 2027 年 8 月下线）。两种失败需区分：HTML 404 表示版本从未存在（猜高或路径拼错）；JSON 400 UNSUPPORTED_VERSION 表示版本已下线。Google 大约每季度发布一个大版本，各版本存活约 12 个月。应直接跳到最新 GA 版本，而非仅上一个版本。
2. contains_eu_political_advertising 为创建活动必填
几乎所有代码示例都缺失此字段，创建活动会 REQUIRED 失败，需提供 "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"。
3. 竞价策略须用子消息而非枚举
仅发送 "biddingStrategyType":"TARGET_SPEND" 会在 campaign_bidding_strategy 上 REQUIRED 失败。它是 protobuf oneof，需发送字段本身："targetSpend":{}、"manualCpc":{}、"maximizeConversions":{}。枚举是只读输出。
4. 移除父资源会孤立子资源，且子资源状态会“说谎”
移除活动后，其广告组、条件、广告变为不可变，但仍报告旧状态——被移除活动的广告组仍显示 ENABLED，修改会返回 OPERATION_NOT_PERMITTED_FOR_REMOVED_RESOURCE。应通过 campaign.status 验证清理，而非子资源。先移除活动，再移除其预算，预算不会被自动移除。资源永不硬删除，REMOVED 为终态，查询时应过滤 WHERE campaign.status != 'REMOVED'。
5. 金额以微单位表示
amountMicros: 3000000 = 每天 $3.00。10⁶ 的疏忽会创建每天 $3,000 的预算且无报错，是唯一会静默花钱的错误。发送前显式计算 dollars * 1_000_000 并复查。货币不一定是 USD，可用 SELECT customer.currency_code, customer.time_zone FROM customer 查询。
6. updateMask 控制变更范围 仅列出的字段会变更；设置了但未列出的字段被忽略，列出了但未设置的字段被清空。amount_micros 与 amountMicros 均被接受。
7. login-customer-id 失败表现为认证失败
在经理账户下操作客户账户需要头部 --header 'login-customer-id: 9876543210'。错误或未授权的值返回 401 UNAUTHENTICATED，而非定向错误。调试 OAuth 前先检查该头部。
validateOnly 校验
{"validateOnly":true,"operations":[...]} 成功返回 {} 且不改变任何内容。适用于花钱或难以撤销的操作，用于捕捉语法合法但内容错误的变更（如预算打错）。
读取效果数据
使用 v25/customers/<CID>/googleAds:search 查询指标。指标需要日期条件（DURING LAST_30_DAYS 或 BETWEEN），否则返回生命周期总计。大批量无分页拉取用 googleAds:searchStream，关键词级细节在 keyword_view。零转化时需先确认是否有追踪，不能将零直接视为效果结论。
创建活动的最小可行流程 先建预算再建活动。活动需设置 name、status（PAUSED）、advertisingChannelType、campaignBudget、竞价策略子消息、containsEuPoliticalAdvertising 与 networkSettings。随后依次 adGroups:mutate → adGroupCriteria:mutate（关键词）→ adGroupAds:mutate（响应式搜索广告）。无广告组、关键词或广告的活动无法投放。
适用场景
适用于通过 treg 对 Google Ads 账户进行效果分析、预算调整、活动创建与清理的代理与开发者，尤其在真实付费账户上操作时。
限制
测试账户在测试经理账户下创建，是独立 Google 账户，生产经理无法承载。它们没有投放数据，也无法测试转化上传，只能验证变更机制；效果与转化工作必须在真实账户上进行。本资料未提供具体收费与价格信息。
参考链接
字段参考：https://developers.google.com/google-ads/api/fields/v25/overview GAQL 语法：https://developers.google.com/google-ads/api/docs/query/grammar 测试账户：https://developers.google.com/google-ads/api/docs/best-practices/test-accounts 下线日期：https://developers.google.com/google-ads/api/docs/sunset-dates