开发人员指南概述

亚马逊广告 API 概览

管理 Amazon Marketing Stream 订阅

完成 Amazon Marketing Stream 初始设置之后，您可以使用以下操作来查看、添加、更新和存档订阅。

提示

使用亚马逊的 Postman 集合来测试 Amazon Marketing Stream API。集合和环境设置完成后，请查看 Amazon Marketing Stream 文件夹以调用 API。

提示

请尝试 CLI。用于处理本文档中所有操作的 CLI 作为 Amazon Marketing Stream 在 GitHub 上的参考实施的一部分提供。

查看所有订阅

要查看与广告配置文件关联的所有数据集订阅，请使用 GET /streams/subscriptions 接口。

请求

此资源返回为 Amazon-Advertising-API-Scope 中传递的配置文件标识符创建的订阅。您可以使用 maxResults 查询参数以控制每页返回的结果数。

示例

curl --location --request GET 'https://advertising-api.amazon.com/streams/subscriptions?maxResults=10' \
--header 'Amazon-Advertising-API-ClientId: xxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxx' \
--header 'Authorization: Bearer xxxxxxxxx'

响应

示例

{
   "nextToken": "string",
   "subscriptions": [
     {
       "createdDate": "2022-02-16T20:11:05.323Z",
       "destinationArn": "string",
       "dataSetId": "sp-traffic",
       "subscriptionId": "54321",
       "updatedDate": "2022-02-18T20:11:05.323Z",
       "status": "ACTIVE"
     },
     {
       "createdDate": "2022-02-15T20:11:05.323Z",
       "destinationArn": "string",
       "dataSetId": "sp-conversion",
       "subscriptionId": "12345",
       "updatedDate": "2022-03-19T20:11:05.323Z",
       "status": "ARCHIVED"
     },
   ]
 }

如果有更多页的结果，您可以在下次调用的 startingToken 查询参数中传递 nextToken 值。

添加订阅

如果您需要订阅新的数据集或广告主，请使用 POST /streams/subscriptions 接口。

在添加订阅之前，请确保您已经为数据集添加相关的 IAM 策略到您的 SQS 队列。为了完成订阅并开始接收数据，您需要在 SQS 中确认订阅。

您可以在数据指南中查看目前支持哪些数据集。

请求

对于 destinationArn，请确保包含一个 SQS ARN，该 ARN 应用了与您要请求的 dataSetId 匹配的 IAM 策略。

示例

curl --location --request POST 'https://advertising-api.amazon.com/streams/subscriptions' \
--header 'Amazon-Advertising-API-ClientId: xxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxx' \
--header 'Content-Type: application/vnd.MarketingStreamSubscriptions.StreamSubscriptionResource.v1.0+json' \
--header 'Authorization: Bearer xxxxxxxxx' \
--data-raw '{
"clientRequestToken": "123456xyz789101112",
"dataSetId": "sp-traffic",
"notes": "Advertiser 1 sp-traffic subscription",
"destinationArn": "QUEUE_ARN"
}‘

响应

成功调用会返回一个响应，显示 subscriptionID，您可以用来查看订阅状态。

示例

{
   "subscriptionId": "xxxxxxxxxxxxx",
   "clientRequestToken": "123456xyz789101112",
 }

查看订阅状态

创建并确认订阅之后，您可以使用 GET /streams/subscriptions/{subscriptionId} 接口查看订阅的状态信息。

提示

请定期查看订阅状态，以确保所有订阅都处于活动状态。如果一个订阅中使用了用户的令牌，但用户失去了对广告实体的访问权限，则该订阅会被暂停。

可能的状态

| 状态 | 描述 | |--- |--- | | PROVISIONING | 订阅已创建，并且正由亚马逊预配。预配完成后，订阅将进入 PENDING_CONFIRMATION 状态。 | | PENDING_CONFIRMATION | 订阅已创建和预配，正在等待在 SQS 队列中确认。 | | FAILED_CONFIRMATION | 订阅在 3 天内未在 SQS 中得到确认。如果发生这种情况，请创建一个新的订阅，并在 3 天失效期结束前确认该订阅。 | | ACTIVE | 订阅处于活跃状态并正在传送数据。 | | ARCHIVED | 订阅已存档。 | | SUSPENDED | 订阅已暂停。如果创建订阅的账户在广告平台中失去了对广告主的访问权限，则会发生这种情况。 |

警告

SUSPENDED 订阅无法设置为 ACTIVE。暂停订阅后，您必须使用有权访问数据的账户重复进行订阅流程。

请求

示例

curl --location -g --request GET 'https://advertising-api.amazon.com/streams/subscriptions/xxxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxx' \
--header 'Authorization: Bearer Atza| xxxxxxxx'

响应

示例

{
    "subscription": {
        "createdDate": "2021-10-14T18:25:52.861Z",
        "notes": "Advertiser 1 sp-traffic subscription",
        "subscriptionId": "xxxxxxxxxx",
        "destinationArn": "QUEUE_ARN",
        "dataSetId": "sp-traffic",
        "updatedDate": "2021-10-15T18:25:52.861Z",
        "status": "PROVISIONING"
    }
 }

存档订阅

目前无法删除 Amazon Marketing Stream 订阅。您可以通过使用 PUT /streams/subscriptions/{subscriptionId} 接口并将 status设置为 ARCHIVED 来存档订阅。将状态设置为“已存档”会停止与订阅关联的广告主账户和数据集的所有数据传输。

请求

示例

curl --location -g --request PUT 'https://advertising-api.amazon.com/streams/subscriptions/xxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--data-raw '{
 "status": "ARCHIVED"
}'

响应

成功的响应将返回 200 响应。

Amazon Advertising logo