广告接口对接中的版本分裂与协议陷阱

作者：c4t2026.11.07 03:04浏览量：0

简介：广告 API 对接常被文档的“齐全”误导，实际调试中版本分裂、请求头混用、MIME 类型错误等问题频发。本文梳理两套 API 并行下的鉴权与调用差异，拆解从授权到广告组创建的完整依赖链，帮助后端开发者避开 403、415 等常见错误，建立可复用的调试路径。

广告接口对接中的版本分裂与协议陷阱

一、为什么“文档齐全”不等于“对接顺利”

多数广告平台的接口文档在结构上看似完整：每个资源有独立的端点说明、请求示例和字段表。然而真正进入联调阶段，问题往往不是“找不到接口”，而是“找到了却调不通”。这类问题的根源通常不在业务逻辑，而在协议层的分裂——同一个广告体系下存在两套并行的 API 版本，各自维护独立的请求头规范、内容类型和响应结构。

本文围绕广告接口对接中的典型陷阱展开，重点分析版本分裂带来的鉴权差异、MIME 类型约束，以及从授权到广告组创建的完整依赖关系。示例结构均来自真实对接场景的抽象，可直接用于调试参考。

二、三个最容易让人怀疑人生的点

2.1 不是一套接口：版本分裂的根源

广告平台通常将“广告活动（Campaign）”的创建放在一套较新的 API 版本中，而广告组（AdGroup）及其下级资源（关键词、商品广告、定向等）仍沿用另一套版本。这两套 API 的路径前缀、请求头命名、内容类型和响应结构都不相同。

具体来说：

  • Campaign 创建走新版 API，路径通常带有 /adsApi/v1/ 前缀；
  • AdGroup 及以下资源走另一套版本，路径带有 /sp/ 前缀；
  • 两套 API 的请求头字段名不同，混用会直接返回 403；
  • 内容类型不是通用的 application/json，而是每个资源有专属的 vendor MIME。

这种分裂并非设计缺陷，而是版本演进的中间状态。对接时若按“一套接口”的思维去写通用请求封装，必然在某个资源上碰壁。

2.2 Header 有两套命名

两套 API 的鉴权头字段名不同：

版本 客户端标识头 账户/范围头
新版 API Amazon-Ads-ClientId Amazon-Ads-AccountId
SP v3 Amazon-Advertising-API-ClientId Amazon-Advertising-API-Scope

混用或漏传会导致 403。建议在代码中按 API 版本分别维护 header 构造器，不要试图用一套逻辑兼容。

2.3 Content-Type 不能写 application/json

SP v3 的每个资源都有专属的 vendor MIME 类型，例如关键词资源使用 application/vnd.spKeyword.v3+json，定向资源使用 application/vnd.spTarget.v3+json。写错会返回 415 或 400。

这意味着请求封装不能统一设置 Content-Type，而应根据目标资源动态选择。一个可行的做法是在资源定义表中维护 MIME 映射，发送前自动注入。

三、整体创建依赖关系

广告资源的创建存在严格的依赖顺序。Portfolio 是可选的顶层容器，Campaign 必须归属于某个 Portfolio 或直接挂在账户下。AdGroup 依赖 Campaign，而关键词、商品广告、定向、否定关键词、否定定向都依赖 AdGroup。Campaign 级别的否定关键词和否定定向则直接依赖 Campaign。

用流程图表示如下：

  1. OAuth (LWA)
  2.   → GET /v2/profiles
  3.     → POST /portfolios (可选)
  4.       → POST /adsApi/v1/create_campaigns
  5.         → POST /sp/adGroups
  6.           → POST /sp/productAds
  7.           → POST /sp/keywords
  8.           → POST /sp/targets (或 list PUT)
  9.           → POST /sp/negativeKeywords
  10.           → POST /sp/negativeTargets
  11.         → POST /sp/campaignNegativeKeywords
  12.         → POST /sp/campaignNegativeTargets

注意：自动投放的 Target 在某些版本中不支持直接 Create，需要通过 list 接口配合 PUT 完成。这是另一个容易踩坑的点。

四、按实际对接顺序逐步展开

4.1 OAuth（Login with Amazon）

所有广告 API 请求都需要 Bearer Access Token。标准流程是 OAuth 2.0 授权码模式。

第一步是跳转授权页，请求用户授权。授权范围需要包含广告活动管理相关的 scope。用户同意后，授权码会回调到指定的 redirect URI。后端用授权码换取 refresh token 和 access token。

access token 有效期通常为 1 小时，refresh token 用于续期。建议在 token 过期前 5 分钟主动刷新，避免请求因 401 失败。

4.2 获取 Profile

拿到 access token 后，第一件事是获取 Profile 列表。Profile 代表广告账户在某个市场中的身份标识，后续所有请求都需要带上 Profile ID 作为 scope。

请求示例：

  1. GET /v2/profiles
  2. Headers:
  3.   Authorization: Bearer {access_token}
  4.   Amazon-Advertising-API-ClientId: {client_id}

响应中会返回多个 profile，每个对应一个市场。需要根据业务选择正确的 profile ID，后续请求的 Amazon-Advertising-API-Scope 头就填这个 ID。

4.3 创建 Portfolio（可选）

Portfolio 是广告活动的分组容器，用于批量管理和预算控制。如果业务上不需要分组，可以跳过这一步，直接在账户下创建 Campaign。

创建 Portfolio 的请求走 SP v3 路径，Content-Type 使用对应的 vendor MIME。请求体包含名称和预算信息。

4.4 创建 Campaign

Campaign 创建走新版 API，路径为 /adsApi/v1/create_campaigns。请求头使用新版命名：

  1. POST /adsApi/v1/create_campaigns
  2. Headers:
  3.   Authorization: Bearer {access_token}
  4.   Amazon-Ads-ClientId: {client_id}
  5.   Amazon-Ads-AccountId: {profile_id}
  6.   Content-Type: application/json

注意这里的 Content-Type 是新版 API 的要求，与 SP v3 不同。请求体中需要指定 campaign 的名称、预算、投放类型、目标等字段。

响应结构也与 SP v3 不同，通常是包含 campaign ID 的对象数组。需要从响应中提取 campaignId，用于后续创建 AdGroup。

4.5 创建 AdGroup

AdGroup 创建走 SP v3，路径为 /sp/adGroups。请求头切换为 SP v3 命名，Content-Type 使用 AdGroup 对应的 vendor MIME。

请求体关键字段：

  • campaignId：上一步获取的 Campaign ID；
  • name：广告组名称；
  • defaultBid：默认竞价；
  • state：状态（enabled/paused）。

响应中返回 adGroupId，用于创建下级资源。

4.6 创建 Product Ads

Product Ads 将具体商品与 AdGroup 关联。路径为 /sp/productAds，Content-Type 使用对应 vendor MIME。

请求体需要指定：

  • adGroupId；
  • campaignId；
  • sku 或 asin：商品标识；
  • state。

一个 AdGroup 可以关联多个商品，批量创建时注意单次请求的数量限制。

4.7 创建 Keywords

关键词是手动投放的核心。路径为 /sp/keywords，Content-Type 使用 application/vnd.spKeyword.v3+json。

请求体字段：

  • adGroupId；
  • campaignId；
  • keywordText：关键词文本；
  • matchType：匹配类型（broad/phrase/exact）；
  • bid：竞价；
  • state。

响应中返回 keywordId 列表。批量创建时，部分成功的情况会返回 207 状态码，需要在响应体中逐条检查成功与失败项。

4.8 创建 Targets

定向（Targets）用于自动投放场景。路径为 /sp/targets，但某些类型的定向不支持直接 POST 创建，需要先通过 list 接口获取，再用 PUT 更新。

这是一个容易踩坑的点：自动投放的 Target 在某些版本中不能直接 Create。正确的做法是：

  1. 先调用 list 接口获取系统自动创建的 target；
  2. 修改目标字段后，用 PUT 更新。

如果直接 POST，会返回 405 或 400。

4.9 创建 Negative Keywords 和 Negative Targets

否定关键词和否定定向用于排除不相关的流量。AdGroup 级别的否定资源路径为 /sp/negativeKeywords 和 /sp/negativeTargets，Campaign 级别的路径为 /sp/campaignNegativeKeywords 和 /sp/campaignNegativeTargets。

Content-Type 同样需要匹配对应的 vendor MIME。请求体结构与正向关键词类似，但不需要竞价字段。

五、207 部分成功的处理

批量创建接口在部分成功时返回 207 状态码。响应体通常包含两个数组：成功项和失败项。失败项会附带错误码和错误信息。

处理策略：

  • 不要将 207 视为失败，也不要视为完全成功；
  • 解析响应体，提取成功项的 ID 用于后续依赖；
  • 记录失败项的错误原因，便于重试或人工干预；
  • 在重试时只重试失败项，避免重复创建成功项。

六、调试建议与最佳实践

  1. 按版本维护请求封装：不要试图用一套 header 逻辑兼容所有接口。新版 API 和 SP v3 分别维护独立的请求构造器。

  2. 维护 MIME 映射表：每个资源对应一个 vendor MIME，发送前自动注入，避免手写错误。

  3. token 刷新前置：在 token 过期前主动刷新，不要在收到 401 后再刷新重试，减少不必要的失败。

  4. 依赖顺序不可颠倒：Campaign → AdGroup → 下级资源，每一步都要拿到上一步的 ID 才能继续。

  5. 207 要逐条解析：批量接口的 207 响应必须逐条检查，不能只看 HTTP 状态码。

  6. 自动投放 Target 用 list + PUT：不要直接 POST 创建，先 list 再 PUT 更新。

  7. Postman 调试时注意环境变量：将 token、profile ID、client ID 等设为环境变量，切换环境时不需要手动改。

  8. 日志记录请求与响应：在调试阶段记录完整的请求头和请求体，便于定位 403、415 等问题。

七、总结

广告接口对接的难点不在于业务逻辑的复杂性，而在于协议层的分裂与细节约束。两套 API 并行、两套 header 命名、每种资源独立的 vendor MIME、207 部分成功、自动投放 Target 不能直接 Create——这些点单独看都不难，但叠加在一起就会显著拉长调试周期。

应对策略的核心是：按版本隔离请求封装，按资源维护 MIME 映射，严格遵循依赖顺序，对批量响应逐条解析。把这些基础工作做扎实，后续的联调效率会明显提升。

最热文章