多版本广告投放 API 对接实践：从鉴权到资源编排

一、为什么广告投放 API 对接容易“绕”？

对接广告投放类开放接口，难点通常不在单个接口本身，而在于整体体系的复杂度。以某电商平台的广告 API 为例，有三个最容易让开发者“怀疑人生”的点，值得在动手之前先说清楚。

1. 不是一套接口，而是两套并行体系

不少开发者默认整个广告创建流程是一套连贯的接口，实际上并非如此：广告活动层的创建走 v1 版本体系，而广告组及其下层资源全部走 v3 版本体系。两套体系的路径前缀、请求头命名、内容类型约定、响应结构都不一样，不能指望用同一套客户端配置“一把梭”到底。这意味着对接代码从第一天起就应该按版本拆分模块，而不是等出了问题再打补丁。

2. 请求头有两套命名规范

同样是表达“客户端身份”这个语义，v1 体系要求在请求头中同时提供客户端标识与账户标识两类头域；v3 体系则要求提供客户端标识与作用域标识两类头域，且头域名称的写法与 v1 完全不同。两套命名在视觉上极为相似，极易混淆，一旦混用，服务端无法正确识别调用方身份，直接返回 403。这类错误的隐蔽之处在于：单独看每一个头域“好像都填了”，只有逐字对照文档才能发现是版本用错了。

3. Content-Type 不能随手写 application/json

在多数 Web 开发场景中，请求体是 JSON 就写 application/json，几乎成了肌肉记忆。但 v3 体系下，每个资源都有专属的 vendor MIME 类型，遵循 application/vnd.{资源类型}.v{版本号}+json 的模式，这是 RFC 6838 定义的 vendor tree 命名约定，平台借此在服务端精确区分资源类型与接口版本。如果沿用通用的 application/json，轻则 415（不支持的媒体类型），重则 400，且报错信息往往不够直观，排查成本很高。

把这三个点理清之后，整个对接工作就有了主线：识别版本边界、对齐头域命名、精确匹配内容类型。下面按实际对接顺序逐步展开。

二、先看全局：资源模型与创建依赖链

广告投放的资源模型是典型的层级结构：账户 → 站点/市场上下文 → 广告组合（可选）→ 广告活动 → 广告组 → 下层投放对象。下层投放对象包括商品广告、关键词、投放目标（支持单条创建或批量更新）、否定关键词、否定投放目标，以及挂在活动级的否定关键词与否定投放目标。

创建必须自上而下逐层进行，整体依赖关系可以抽象为一张有向无环图：

OAuth 鉴权
   └─> 获取站点/账户上下文
         └─> (可选) 创建广告组合
               └─> 创建广告活动 (v1 体系)
                     ├─> 创建广告组 (v3 体系)
                     │     ├─> 商品广告
                     │     ├─> 关键词
                     │     ├─> 投放目标（或批量更新）
                     │     ├─> 否定关键词
                     │     └─> 否定投放目标
                     ├─> 活动级否定关键词
                     └─> 活动级否定投放目标

理解这张图的意义有两层：其一，任何下层资源创建失败，都应先检查其上游父资源是否已成功创建并处于可用状态；其二，做删除、暂停或归档时，顺序要反过来，从叶子节点往上逆序处理，否则会遇到“存在子资源不允许操作父资源”之类的约束。

三、第一步：完成 OAuth 2.0 鉴权

主流投放平台的开放接口普遍基于标准 OAuth 2.0 授权码流程，基本步骤如下：

1. 引导广告主跳转平台授权页完成登录与授权，回调获得授权码；
2. 用授权码换取 access_token，同时拿到长期有效的 refresh_token；
3. access_token 有效期较短，需在过期前用 refresh_token 静默刷新；
4. 将 token 管理独立成模块：集中存储、提前刷新、并发加锁。

# 伪代码：token 管理器
class TokenManager:
    def get_access_token(self):
        if self.is_expiring_soon():
            with self.lock:          # 防止多实例并发刷新
                self.refresh()
        return self.access_token

特别提醒：多实例部署时，若不加以锁控制，多个节点同时刷新 token，可能出现“互相踢下线”的循环失效问题，这是生产环境最常见的鉴权事故之一。

四、第二步：获取账户与站点上下文

鉴权完成后，第一件事不是创建广告，而是查询当前授权账号下可操作的站点/市场列表（通常是一个独立于业务版本体系的查询接口），拿到每个站点的唯一标识。后续所有业务请求都需要携带该标识作为作用域，服务端据此将请求路由到对应站点的数据空间。

两个实践要点：

• 作用域与身份是两个维度：token 解决“你是谁”，站点标识解决“你操作哪个市场”，二者缺一不可；
• 多站点运营时做好映射：站点标识要与业务侧的店铺、站点维度建立稳定的映射关系，避免跨站点串数据。

五、第三步：创建广告活动（v1 体系）

广告活动是预算与投放策略的载体，在 v1 体系下创建时需注意：

• 请求头使用 v1 的命名规范，即客户端标识 + 账户标识两类头域；
• Content-Type 使用通用的 application/json 即可；
• 关键参数包括每日预算、投放策略（如动态加价或固定竞价）、起止时间等；
• 创建接口通常采用异步批量设计：提交后返回的是“受理结果”，最终成败需再调用查询接口确认，不能假设提交成功即创建成功。

因此，本地落库时应先记录“提交中”状态，待远端状态确认后再流转为“生效”或“失败”。

六、第四步：创建广告组及下层资源（v3 体系）

拿到活动 ID 后切换到 v3 体系创建广告组，再逐层挂载下层资源。这一步是踩坑重灾区，务必注意三点：

1. 请求头整体切换：客户端标识头域换成 v3 的命名，作用域头域填入上一步拿到的站点标识；
2. Content-Type 必须使用对应资源的 vendor MIME：不同资源不能共用一个 MIME，具体名称需以平台接口文档为准；
3. 响应结构也不同：多为“受理 + 异步结果”的组合，需按提交—轮询—取结果的节奏处理。

为了让两套体系不打架，推荐封装统一的请求头工厂，把差异收敛到一处：

def build_headers(api_version, resource_type=None, scope=None):
    headers = {"Authorization": f"Bearer {get_token()}"}
    if api_version == "v1":
        headers.update({
            "X-Client-Id":  CLIENT_ID,      # 示意命名，以平台文档为准
            "X-Account-Id": ACCOUNT_ID,
            "Content-Type": "application/json",
        })
    elif api_version == "v3":
        headers.update({
            "X-Client-Id": CLIENT_ID,
            "X-Scope":     scope,
            "Content-Type": f"application/vnd.{resource_type}.v3+json",
        })
    return headers

七、高频错误与排查清单

现象	常见原因	处理建议
403	v1/v3 头域混用、缺少作用域头域、token 权限不足	逐项对照两套头域命名规范
415	Content-Type 未使用对应资源的 vendor MIME	建立“资源类型 → MIME”映射表
400	路径版本与 MIME 版本不匹配、必填字段缺失	先核对版本一致性，再校验字段
404/409	父资源尚未创建完成或状态不可用	沿依赖链检查上游资源状态
429	触发限流	指数退避重试，降低并发

八、工程化最佳实践

1. 版本化客户端：v1 与 v3 各自独立封装，头域、序列化、错误解析互不干扰；
2. 依赖编排：用状态机或任务编排引擎管理创建顺序，支持断点续跑与部分重试；
3. 幂等设计：为每次创建请求生成唯一外部单号，重试前先查询后创建，避免重复建广告；
4. 定期对账：拉取远端资源列表与本地库比对，兜住“提交成功但落库失败”等边缘情况；
5. 监控告警：重点覆盖 token 刷新失败率、403/415 错误率、限流触发频次。

九、总结

多版本并存的广告投放 API，考验的不是单接口的调用能力，而是对整体体系的建模能力。抓住三件事：其一，明确两套接口体系的边界，以及各自头域命名与内容类型约定；其二，以资源依赖链为主线编排创建顺序，自上而下创建、自下而上清理；其三，把易错点收敛到统一的封装层，用工程手段而非人肉记忆保证一致性。做到这三点，对接工作就能从“反复试错”变成“按图施工”。