亚马逊广告API对接全攻略：从认证到物料创建的最佳实践

在广告自动化投放场景中，对接官方广告接口几乎是每个规模化运营团队的必经之路。然而，不少开发者在实际对接过程中都会遇到“接口版本混乱”“请求头命名不一致”“Content-Type频繁报错”等棘手问题。本文以亚马逊广告平台（Amazon Ads）的SP广告系列接口为例，从整体架构、认证流程、物料层级创建顺序到常见错误排查，系统性地梳理一套可复用的对接方法论。

一、先厘清API体系的整体结构：为什么“绕”是常态？

很多初次接触广告API的开发者，都会有一个直观感受：这套接口不像常规RESTful API那样“一个域名+一套鉴权+统一资源路径”走天下。实际上，亚马逊广告API在设计上采用了多版本并存的架构，不同资源层级由不同的API版本负责管理。这种设计虽然增加了初期的学习成本，但也为不同业务场景提供了更精细的控制粒度。

具体来看，SP广告业务主要涉及两套接口体系：

第一套：Ads API v1，负责Campaign（广告活动）级别的创建与管理。其典型路径前缀为 /adsApi/v1/...，请求头使用 Amazon-Ads-ClientId 与 Amazon-Ads-AccountId 进行身份标识。这套接口相对轻量，主要负责活动层级的增删改查。

第二套：Sponsored Products v3（以下简称SP v3），覆盖AdGroup（广告组）及其以下所有层级，包括ProductAd（商品广告）、Keyword（关键词）、Target（商品投放/受众投放）、NegativeKeyword（否定关键词）以及NegativeTarget（否定投放）等。其路径前缀统一为 /sp/...，请求头则改为 Amazon-Advertising-API-ClientId 与 Amazon-Advertising-API-Scope。

两套接口在请求头命名、Content-Type规范、响应结构上均有差异。如果开发者没有提前建立清晰的版本意识，混用请求头或错误设置Content-Type，极容易触发403（Forbidden）或415（Unsupported Media Type）错误。

此外，SP v3接口对Content-Type有严格且细粒度的要求。不同于常规API直接使用 application/json，SP v3要求每个资源类型使用专属的vendor MIME类型。例如，创建Keyword时，Content-Type必须设置为 application/vnd.spKeyword.v3+json；创建Target时则需使用 application/vnd.spTargeting.v3+json。一旦写错或缺失，服务端会直接返回400或415错误，导致请求失败。

二、对接前置准备：LWA OAuth认证流程

在正式调用任何业务接口之前，必须完成开发者账号注册、应用创建以及OAuth令牌获取。亚马逊广告API使用LWA（Login with Amazon）作为统一的身份认证协议，其流程与行业标准OAuth 2.0一致，但需要注意几个关键参数：

1. Client ID 与 Client Secret：在开发者后台创建应用后获得，用于换取访问令牌。
2. Refresh Token：首次授权时通过用户登录授权获取，用于长期维持会话，避免频繁弹出登录框。
3. Access Token：每次API调用的临时凭证，有效期较短（通常为数小时），过期后需用Refresh Token重新换取。

一个典型的令牌获取流程如下：

import requests
# 1. 使用 refresh_token 换取 access_token
token_url = "https://api.amazon.com/auth/o2/token"
payload = {
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}
resp = requests.post(token_url, json=payload)
access_token = resp.json().get("access_token")

获取到Access Token后，每次API调用都需要在HTTP Header中携带两个鉴权信息：Authorization: Bearer {access_token}，以及对应API版本的Client ID字段。

三、完整对接流程：从Profiles到投放物料的逐级创建

广告物料创建并非“一次请求搞定所有”，而是遵循严格的层级依赖关系。整体流程可归纳为：OAuth认证 → 获取Profiles →（可选）创建Portfolio → 创建Campaign → 创建AdGroup → 创建ProductAd/Keyword/Target/NegativeKeyword/NegativeTarget。下面按实际开发顺序逐一展开。

3.1 获取Profiles：确定投放账号

所有Campaign必须归属于某个Profile（即广告账号）。调用 GET /v2/profiles 接口可以获取当前授权用户下的所有广告账号列表。该接口无特殊请求体，只需携带认证头即可。

headers = {
    "Authorization": f"Bearer {access_token}",
    "Amazon-Advertising-API-ClientId": "YOUR_CLIENT_ID",
    "Amazon-Advertising-API-Scope": "YOUR_PROFILE_ID"
}
resp = requests.get("https://advertising-api.amazon.com/v2/profiles", headers=headers)
profiles = resp.json()

返回结果中包含profileId，这个ID将作为后续所有SP v3接口调用中的 Amazon-Advertising-API-Scope 参数值，用于标识操作归属的广告账号。

3.2 创建Portfolio（可选）

Portfolio是广告活动的逻辑分组，可用于预算管理和效果汇总。该步骤为可选操作，如果不做分组，可直接跳过。创建Portfolio走SP v3接口，路径为 /sp/portfolios，请求体包含名称、预算等字段。

3.3 创建Campaign：进入Ads API v1体系

Campaign的创建走Ads API v1，路径为 /adsApi/v1/campaigns。这里需要特别注意，请求头应使用v1规范：

Amazon-Ads-ClientId: {client_id}
Amazon-Ads-AccountId: {profile_id}
Content-Type: application/json

请求体核心字段包括：name（活动名称）、profileId、tactic（如T00020表示SP广告）、budget、startDate、state（enabled/paused）等。

一个常见误区是：开发者误以为所有SP相关接口都使用同一套请求头，结果在Campaign创建时误用v3请求头导致403。务必在代码中根据接口路径前缀显式区分两套头的组装逻辑。

3.4 创建AdGroup：进入SP v3体系

Campaign创建成功后，返回的campaignId将作为AdGroup的父级ID。调用 POST /sp/adGroups 创建广告组，此时请求头切换为v3规范：

Amazon-Advertising-API-ClientId: {client_id}
Amazon-Advertising-API-Scope: {profile_id}
Content-Type: application/vnd.spAdGroup.v3+json

请求体包含：campaignId、name、defaultBid 等。成功后会返回adGroupId，作为后续商品广告、关键词、投放等资源的父级ID。

3.5 创建ProductAd、Keyword、Target及否定实体

在AdGroup之下，可以并行创建多个子资源。每类资源均有独立的vendor MIME类型，且请求体结构各不相同。

• ProductAd（商品广告）：POST /sp/productAds，Content-Type为 application/vnd.spProductAd.v3+json，请求体需包含 adGroupId 与 sku 或 asin。
• Keyword（关键词）：POST /sp/keywords，Content-Type为 application/vnd.spKeyword.v3+json，请求体包含 adGroupId、keywordText、matchType、bid。
• Target（投放目标）：POST /sp/targets，Content-Type为 application/vnd.spTargeting.v3+json，请求体支持 targetingExpression 或 productList 等复杂结构。
• NegativeKeyword（否定关键词）：POST /sp/negativeKeywords，Content-Type为 application/vnd.spNegativeKeyword.v3+json。
• NegativeTarget（否定投放）：POST /sp/negativeTargets，Content-Type为 application/vnd.spNegativeTargeting.v3+json。

值得注意的是，否定关键词和否定投放分为AdGroup级别与Campaign级别两类。如果需要在Campaign级别全局排除某些词或商品，则需调用 /sp/campaignNegativeKeywords 和 /sp/campaignNegativeTargets 两个独立接口，其路径与AdGroup级别的接口不互通，切勿混用。

四、高频错误排查与避坑指南

在实际对接过程中，以下几类错误出现的频率最高，建议提前做好防御性编码。

4.1 403 Forbidden：请求头混用

这是最常见的错误。解决思路很简单：在封装API调用函数时，将v1和v3的Header定义成两个独立的构造器，并依据URL路径自动选择。例如：

def build_headers_v1(access_token, client_id, profile_id):
    return {
        "Authorization": f"Bearer {access_token}",
        "Amazon-Ads-ClientId": client_id,
        "Amazon-Ads-AccountId": profile_id,
        "Content-Type": "application/json"
    }
def build_headers_v3(access_token, client_id, profile_id, mime_type):
    return {
        "Authorization": f"Bearer {access_token}",
        "Amazon-Advertising-API-ClientId": client_id,
        "Amazon-Advertising-API-Scope": profile_id,
        "Content-Type": mime_type
    }

4.2 400/415：Content-Type错误

SP v3对MIME类型要求极其严格，哪怕是微小的拼写错误（比如少写+json），服务端也会直接拒绝请求。建议将每个资源的MIME常量定义在配置文件中，避免硬编码。

4.3 请求体字段缺失或类型不匹配

部分接口对字段类型有严格校验，如 bid 必须是数字类型（不能传字符串），state 只能是枚举值（如 enabled 或 paused）。建议在发起调用前用JSON Schema做一次本地校验，减少无效请求次数。

4.4 限流与重试机制

广告API对请求频率有严格限制。建议在代码中实现指数退避重试策略，当收到429（Too Many Requests）或5xx错误时，自动等待后重试。同时，可以监控 X-RateLimit-Remaining 响应头，提前预估剩余配额。

五、工程化建议：如何构建健壮的对接层

从工程实践角度看，建议将广告API对接封装为一个独立的SDK模块，核心模块包括：

1. 认证模块：负责Access Token的缓存与刷新，避免每次调用都走OAuth流程。
2. 请求客户端：统一处理Header构建、超时设置、重试策略、日志记录。
3. 资源模型：为Campaign、AdGroup、Keyword等定义数据类，并实现与请求体/响应体的序列化映射。
4. 高层业务接口：面向业务层提供如 create_full_campaign(name, adgroups, keywords) 这样的聚合方法，内部自动编排各层级的创建顺序。

此外，考虑到广告物料创建往往需要批量操作，建议在服务端设计异步任务队列，将API调用放入队列中顺序消费，既避免触发限流，也便于失败重试与状态追踪。

六、总结

对接亚马逊广告API虽然初看复杂，但核心难点主要集中在版本区分、请求头规范、MIME类型管理以及物料创建顺序四个方面。只要建立起清晰的API版本意识，合理封装请求层，并遵循“Profile→Campaign→AdGroup→子资源”的逐级创建逻辑，就能高效、稳定地实现广告自动化投放能力。希望本文的梳理能为正在对接或即将开展对接工作的团队提供一条更顺畅的路径。