开发人员指南概述

亚马逊广告 API 概览

配置文件

在亚马逊广告 API 中，配置文件表示广告主在特定站点中的账户。如果广告主只在一个站点进行推广，他们可能只有一个配置文件，而如果在其他地区或全球范围内进行推广，则可能拥有针对各个站点的单独配置文件。

配置文件、账户和身份认证

亚马逊广告 API 中的配置文件与亚马逊广告平台中的_账户_相对应。各个站点分别对应一个单独建立的_账户_。同一个_用户_（广告主）可以使用相同的亚马逊登录凭据在平台或通过 API 管理多个账户。

配置文件在亚马逊广告 API 中起着至关重要的作用，它决定了给定调用的管理范围。要访问特定站点中的广告主的数据和服务，配置文件标识符是一个必需的凭据。

授权

调用亚马逊广告 API 需要基于 OAuth 2.0 的授权。为了成功调用 API，请求标头中必须包含以下内容：

此外，通过亚马逊广告 API 获得的几乎所有资源都需要在请求标头中传递特定的配置文件标识符。这个值作为 Amazon-Advertising-API-Scope 参数传递。

即使广告主只有一个配置文件，此标头也是必需的。如果未包含 Amazon-Advertising-API-Scope 标头或标头不正确，将返回 401 Unauthorized 或 400 Bad Request 响应。

检索配置文件

可以通过 GET 请求在 /v2/profiles 接口检索给定广告主的配置文件列表。此调用不需要 Amazon-Advertising-API-Scope 标头。

检索到的列表包括与访问令牌所代表的权限相关联的广告主的配置文件。检索到的列表中的每个配置文件都表示广告主在特定站点中的账户。

给定配置文件的 profileId 将在后续调用 API 时传递，以提供对该配置文件的站点中的广告主资源的访问权限。

注意

通过 GET /v2/profiles 返回的响应中，最多包含 5000 个项目。

地区

配置文件资源仅返回其站点位于 API 主机涵盖地区内的配置文件。

例如，一个只在日本和新加坡站点拥有账户的广告主，在通过 https://advertising-api.amazon.com/v2/profiles 向北美主机发出 GET 请求时，将会收到一个空的响应体 [ ]。此广告主应通过 https://advertising-api-fe.amazon.com/v2/profiles 向远东主机发出调用以检索此地区的配置文件。

对于给定主机所覆盖地区以外的站点中配置文件的 profileId，在作为 Amazon-Advertising-API-Scope 标头传递时不能用于主机上的其他操作的授权。将返回 4XX - Unauthorized 响应。

权限

默认情况下，GET /profiles 接口只显示对广告活动具有查看 (View) 和编辑 (Edit) 权限的配置文件。可以使用请求中的 apiProgram 和 accessLevel 参数进行调整。

例如，下面的请求将返回北美地区的配置文件列表，其中授权账户对报告具有 View 权限：

https://advertising-api.amazon.com/v2/profiles?accessLevel=view&apiProgram=report

配置文件类型

配置文件资源包含一个 accountInfo 对象，该对象包含有关与配置文件关联的账户的元数据。type 属性描述了账户类型，目前有三种类型可供选择：

类型属性值 账户类型 描述
vendor 供应商 该账户为供应商账户。供应商账户仅用于商品推广、品牌推广和展示型推广。
seller 卖家 该账户为卖家账户。卖家账户仅用于商品推广、品牌推广和展示型推广。请注意，对于品牌推广和展示型推广，其账户必须完成亚马逊品牌注册。
agency 广告代理商 该账户是广告代理商账户。广告代理商账户仅用于 DSP 和 Data Provider API。

提示

可以使用 profileTypeFilter 参数对响应进行筛选，使其只包含特定配置文件类型。

示例

检索配置文件

在此示例中，广告主在加拿大、墨西哥和美国站点中运营账户。广告主已授权客户端标识符为 amzn1.application-oa2-client.XXX 的客户端访问其数据和服务，并且该客户端已检索到一个 access_token Atza|zZzZzZzZ。

下面的 API 调用将在北美主机上检索一个包含三个配置文件的列表：

GET /v2/profiles HTTP/1.1
Host: advertising-api.amazon.com
Content-Type: 'application/json'
Authorization: 'Bearer Atza|zZzZzZzZ'
Amazon-Advertising-API-ClientId: 'amzn1.application-oa2-client.XXX'

Response body:

[
  {
    "profileId": 777777777,
    "countryCode": "CA",
    "currencyCode": "CAD",
    "timezone": "America/Los_Angeles",
    "accountInfo": {
      "marketplaceStringId": "A2EUQ1WTGCTBG2",
      "id": "ENTITY2Plqweuieorf",
      "type": "vendor",
      "name": "Name of the Account",
      "validPaymentMethod": false
    }
  },
  {
    "profileId": 888888888,
    "countryCode": "MX",
    "currencyCode": "MXN",
    "timezone": "America/Los_Angeles",
    "accountInfo": {
      "marketplaceStringId": "A1AM78C64UM0Y8",
      "id": "ENTITY2Ihjasdjkeru",
      "type": "vendor",
      "name": "Name of the Account",
      "validPaymentMethod": false
    }
  },
  {
    "profileId": 999999999,
    "countryCode": "US",
    "currencyCode": "USD",
    "timezone": "America/Los_Angeles",
    "accountInfo": {
      "marketplaceStringId": "ATVPDKIKX0DER",
      "id": "ENTITYZIbbbbbrrr",
      "type": "vendor",
      "name": "Name of the Account",
      "validPaymentMethod": true
    }
  }
]

使用配置文件标识符

对于该广告主，每次调用亚马逊广告 API，都可以访问与上述配置文件之一相关联的资源。

例如，要访问墨西哥地区此广告主账户下的商品推广活动 资源，需要将第二个配置文件中的 profileId 作为 Amazon-Advertising-API-Scope 标头进行传递。

GET /v2/sp/campaigns HTTP/1.1
Host: advertising-api.amazon.com
Content-Type: 'application/json'
Authorization: 'Bearer Atza|zZzZzZzZ'
Amazon-Advertising-API-ClientId: 'amzn1.application-oa2-client.XXX'
Amazon-Advertising-API-Scope: 888888888

要访问美国或加拿大的账户，必须为每个配置文件进行额外的请求，并将相应的 profileId 作为 Amazon-Advertising-API-Scope 标头进行传递。

配置文件概念

进一步了解

进一步了解本文档中不同概念的相关信息：

要遵循有关在亚马逊广告 API 中建立授权的分步指南，请参阅亚马逊的入门指南。

Amazon Advertising logo