开发人员指南概述

亚马逊广告 API 概览

如何使用合作伙伴机会 API

以下示例演示如何使用 cURL 调用合作伙伴机会 API。

partnerOpportunities 资源

请求

GET https://advertising-api.amazon.com/partnerOpportunities

cURL 命令示例

curl 'https://advertising-api.amazon.com/partnerOpportunities' \
 -H 'Accept: application/vnd.partneropportunity.v1+json' \
 -H 'Amazon-Advertising-API-ClientId: <LWA_APP_CLIENT_ID>' \
 -H 'Amazon-Advertising-API-Manager-Account: <PARTNER_NETWORK_ACCOUNT_ID>' \
 -H 'Authorization: Bearer <ACCESS_TOKEN>'

响应（response）示例

{
  "opportunities": [
    {
      "partnerOpportunityId": "opportunity-1-id",
      "title": "Title for opportunity-1",
      "description": "Description for opportunity-1",
      "callToAction": "Action that opportunity-1 recommends you to take",
      "product": "Amazon advertising product that opportunity-1 corresponds to",
      "objective": "Objective that opportunity-1 intends to improve e.g. brand engagement",
      "createdDate": "2022-05-15T23:42:33.823Z",
      "updatedDate": "2022-05-16T23:43:54.867Z",
      "dataUrl": "/partnerOpportunities/opportunity-1-id/file"
    },
    {
      "partnerOpportunityId": "opportunity-2-id",
      "title": "Title for opportunity-2",
      "description": "Description for opportunity-2",
      "callToAction": "Action that opportunity-2 recommends you to take",
      "product": "Amazon advertising product that opportunity-2 corresponds to",
      "objective": "Objective that opportunity-2 intends to improve e.g. sales",
      "createdDate": "2022-05-14T23:42:33.823Z",
      "updatedDate": "2022-05-15T23:43:54.867Z",
      "dataUrl": "/partnerOpportunities/opportunity-2-id/file"
    },
    {
      "partnerOpportunityId": "opportunity-3-id",
      "title": "Title for opportunity-3",
      "description": "Description for opportunity-3",
      "callToAction": "Action that opportunity-3 recommends you to take",
      "product": "Amazon advertising product that opportunity-3 corresponds to",
      "objective": "Objective that opportunity-3 intends to improve e.g. awareness",
      "createdDate": "2022-05-13T23:42:33.823Z",
      "updatedDate": "2022-05-14T23:43:54.867Z",
      "dataUrl": "/partnerOpportunities/opportunity-3-id/file"
    },
    {
      "partnerOpportunityId": "opportunity-4-id",
      "title": "Title for opportunity-4",
      "description": "Description for opportunity-4",
      "callToAction": "Action that opportunity-4 recommends you to take",
      "product": "Amazon advertising product that opportunity-4 corresponds to",
      "objective": "Objective that opportunity-4 intends to improve e.g. retention",
      "createdDate": "2022-05-15T23:42:33.823Z",
      "updatedDate": "2022-05-16T23:43:54.867Z",
      "dataUrl": "/partnerOpportunities/opportunity-4-id/file"
    }
  ]
}

文件资源

请求

GET https://advertising-api.amazon.com/partnerOpportunities/<partnerOpportunityId>/file

curl 命令示例

curl 'https://advertising-api.amazon.com/partnerOpportunities/<partnerOpportunityId>/file' \
 -H 'Accept: application/vnd.partneropportunity.v1+json' \
 -H 'Amazon-Advertising-API-ClientId: <LWA_APP_CLIENT_ID>' \
 -H 'Amazon-Advertising-API-Manager-Account: <PARTNER_NETWORK_ACCOUNT_ID>' \
 -H 'Authorization: Bearer <ACCESS_TOKEN>'

响应（response）示例

HTTP/1.1 307 Temporary Redirect
location: <S3_DOWNLOAD_URL>

机会数据文件示例

机会数据文件中的数据对于每种不同类型的机会都是不同的。

例如，如果一个文件包含的机会用于为冗余库存 ASIN 创建广告活动，该文件可能包含以下各列：

| 站点 | 广告产品类型 | 加密的广告主 ID | ASIN | 广告主名称 | |--- |--- |--- |--- |--- | | | | | | |

问题排查

401“未授权”错误响应

验证您是否已在 API 调用中包含所有必需的标头（header）。有关这些必需标头及其示例值的更多信息，请参阅启用合作伙伴机会 API。

如果这不能解决问题，请检查与您的 LwA 应用程序关联的用户账户是否与您用于为 API 调用生成访问令牌和刷新令牌的账户相同。

还要验证此用户账户在合作伙伴网络账户中是否具有 **admin（管理员）**或 **developer（开发人员）**权限。您的合作伙伴网络账户的管理员可以在“管理用户”页面上将 LwA 应用程序用户的访问权限级别更改为 admin 或 developer。有关更多信息，请参阅管理员用户帮助页面。

更改这些权限后，最多可能需要 2 小时才能对 API 生效。请至少等待这么长时间，然后再次调用 API。

如果您继续收到此错误，请先为您的 LwA 应用程序创建新的授权代码，确保当前登录 LwA 的用户是上文中授予了 admin 或 developer 权限的用户。然后，检索新的访问令牌和刷新令牌，并将这些值传递到相应的标头中。

403“禁止”错误响应

验证当创建授权码 时登录 LwA 的用户是否具有合作伙伴网络账户中的 admin 或 developer 权限。如需进一步了解，请参阅创建用户和管理用户的访问权限级别。

如果您继续收到此错误，请验证在 Amazon-Advertising-API-Manager-Account 标头中传递的标识符是否为与合作伙伴网络账户 ID 关联的值。此值可使用合作伙伴网络平台进行检索，方法是选择右上角的用户设置链接以显示账户详细信息，然后复制合作伙伴网络账户编号字段的值。

404“未找到”错误响应

如果您在检索 /partnerOpportunities/{partnerOpportunityId}/file 资源时收到此响应，请验证 partnerOpportunityId 路径参数的值是否有效。您可以通过检索 partnerOpportunities 资源并检查 opportunities 列表中的 partnerOpportunityId 属性，来验证此标识符。请注意，每个机会都在 dataUrl 属性中包含一个 URL，其中填充了正确的 partnerOpportunityId 值。

如果您继续收到此错误，请确认您的广告主或 ASIN 是否符合机会标准。例如，如果机会要求您为“冗余库存”ASIN 创建商品推广活动，则您的广告主必须具有处于“冗余库存”状态的 ASIN。

请注意，您最近对广告主或 ASIN 所做的任何更改可能需要多达一天才能在机会 API 中生效。

415“不受支持的媒体类型”错误响应

验证 API 请求中的 Accept 标头是否设置为 application/vnd.partneropportunity.v1+json。请注意，通配符不是 Accept 标头的有效值。例如，不允许使用 Accept: */*。

后续步骤

有关合作伙伴机会 API 的更多信息，请参阅资源参考。

Amazon Advertising logo