SP-API 中 Notifications API 结合 Amazon EventBridge 使用的详细教程

1.基本介绍

1.1 Notifications API

Notifications API 是 SP-API 中的一种接口类型，可以用于创建和管理接收 SP-API 发来的通知消息和消息传递的目的地资源以及相应的订阅。目前支持的订阅的资源类型有 Amazon SQS，以及 Amazon EventBridge。
相比传统的轮询方式来获取数据，使用 Notifications API 来创建订阅模式，可以在 Amazon 消息产生后直接触发并传递给开发者自己订阅消息的应用，从而有效的地减少轮训请求的次数，提高应用消息的实时性，和代码的维护性。

Notifications API 是一种不需要授权的 Grantless operation API。调用 Grantless API 不需要提供 refresh token
而是显式的使用 withScope 参数的方式来定义 Scope。SP-API
中的 Grantless 请求有如下 API:

Operation name	HTTP method and path
createDestination	POST /notifications/v1/destinations
deleteDestination	DELETE /notifications/v1/destinations/{destinationId}
deleteSubscriptionById	DELETE /notifications/v2/subscriptions/{notificationType}/{subscriptionId}
getDestination	GET /notifications/v1/destinations/{destinationId}
getDestinations	GET /notifications/v1/destinations
getSubscriptionById	GET /notifications/v1/subscriptions/{notificationType}/{subscriptionId}
getAuthorizationCode	GET /authorization/v1/authorizationCode

目前，Notifications API 支持 EventBridge 的通知类型有：

Notification Type	Description
BRANDED_ITEM_CONTENT_CHANGE	每当与销售合作伙伴有品牌关系的任何 ASIN 的标题、描述、项目符号或图像发生更改时发送。
ITEM_PRODUCT_TYPE_CHANGE	每当与销售合作伙伴有品牌关系的任何 ASIN 的产品类型名称发生更改时发送。
LISTINGS_ITEM_STATUS_CHANGE	每当销售伙伴拥有的商品状态发生变化时发送。
LISTINGS_ITEM_ISSUES_CHANGE	每当与销售伙伴拥有的商品相关的问题发生变化时发送。
PRODUCT_TYPE_DEFINITIONS_CHANGE	每当有新的产品类型或产品类型版本时发送。

支持 SQS 的通知类型可参考 SP-API 中 Notifications API 结合 Amazon SQS 使用的详细教程中的介绍。

本文将以 LISTINGS_ITEM_STATUS_CHANGE 为例来创建 EventBridge 事件总线的订阅，并将消息发送到订阅 SNS 的邮箱中。

1.2 Amazon EventBridge

Amazon EventBridge 是一种无服务器事件总线，可使用从您的应用程序、集成式软件即服务 (SaaS) 应用程序和 AWS 服务生成的事件，更轻松地大规模构建事件驱动型应用程序。EventBridge 提供从事件源（例如 Zendesk, Shopify，或是 Selling Partner API）到目标对象（例如 AWS Lambda 和其他 SaaS 应用程序）的实时数据流。您可以设置路由规则，以确定将数据发送到何处，从而构建在事件发布者和使用者完全解耦的情况下对数据源进行实时响应的应用程序架构。

2.如何配置 Amazon EventBridge 来进行 Notifications API 消息传递

通过调用 Notifications API 创建事件源(Create Destination)
配置 Amazon SNS 话题和订阅，作为接收 EventBridge 的消息终点
配置 Amazon EventBridge 事件源与事件总线，并对事件总线添加规则和目标
通过调用 Notifications API 创建订阅(Create Subscription)
监测到相应事件后，通知自动发送到订阅的 EventBridge 的目的地中

Step1. 通过调用 Notifications API 创建事件源(Create Destination)

使用 API 的方式来发送 Grantless 请求可参考如下 Python 请求:

grantless_payload = {'grant_type': 'client_credentials', 'client_id': client_id, 'client_secret': client_secret,
                     "scope": "sellingpartnerapi::notifications"}
    lwa = requests.post("https://api.amazon.com/auth/o2/token", data=grantless_payload)

请求创建 Destination，此处我们以美东一 us-east-1 为例:

POST https://sellingpartnerapi-na.amazon.com/notifications/v1/destinations
{
  "resourceSpecification":
  {
    "eventBridge":
    {
      "accountId": "123456789",
      "region": "us-east-1"
    }
  },
  "name": "YourDestinationName"
}

以 Python 代码的请求为例，向 Notifications API 发送请求并创建 EventBridge 的事件源。

normal_endpoint = "https://sellingpartnerapi-na.amazon.com"
    headers = {'content-type': 'application/json', 'Accept': 'application/json', 'x-amz-access-token': access_token}
    destinationParams = {
        "resourceSpecification":
            {
                "eventBridge":
                    {
                        "accountId": "${yourAccountId}",
                        "region": "us-east-1"
                    }
            },
        "name": "yourDestination"
    }

    destinationResponse = requests.post(normal_endpoint + "/notifications/v1/destinations",
                                      data=json.dumps(destinationParams), headers=headers, auth=auth)

返回的结果如下:

{
    "payload": {
        "resource": {
            "sqs": null,
            "eventBridge": {
                "name": "aws.partner/sellingpartnerapi.amazon.com/${yourAccountId}/amzn1.sp.solution.id",
                "accountId": "yourAccountId",
                "region": "us-east-1"
            }
        },
        "destinationId": "yourDestinationId",
        "name": "yourDestinationName"
    }
}

这里我们记录下 resource:eventBridge:name 和 destinationId 的值，这两个值将在配置 EventBridge 和管理订阅中用到。

Step2. 配置 SNS 话题和订阅，作为 EventBridge 的消息终点

Amazon SNS 是一种基于 Pub/Sub 模式的托管式消息收发服务，使用 SNS 可以将消息源收到的消息扇出到多个订阅中。本例中我们将使用 Email 订阅的方式作为目的地来接收 SP-API 发往 EventBridge 的消息。这里我们使用 Notifications API 创建 EventBridge 事件源时的 AWS 区域 us-east-1 来进入 Amazon SNS 并创建 Topic。

SNS 的 Topic 类型分为两种，一种是用于对接 FIFO(first-in, first-out) SQS 类型的 Topic，另一种是标准的 Topic。这里我们的 SNS 将用于作为 EventBridge 消息路由的终点，我们选用 Standard 类型的 Topic。并填写好 SNS 的名字。

接下来我们来为 SNS 添加订阅的目标用于消息接收。这里我们 Protocol 选择 Email 用作发往邮件的目标订阅。并填写好邮箱地址创建订阅

在邮箱中确认好订阅后发往 SNS 的消息即可触达邮箱地址。

Step3. 配置 Amazon EventBridge 事件源与事件总线，并对事件总线添加规则和目标。

这里我们使用 Notifications API 创建 EventBridge 事件源时的 AWS 区域 us-east-1 来进入 Amazon EventBridge ，点击
Partner Event Sources, 可以看到来自 sellingpartnerapi 的事件源。点击 Associate with event bus 来进行关联。

关联后，点击 Rules 选项，选择上一步骤中的事件总线，然后点击 Create Rules 来创建新的规则。

在 Event source 中选择 AWS events or EventBridge partner events 事件源，此处的事件源即为我们使用 Notifications API 的 Destinations 创建的事件源。

Event Pattern 中可参考如下格式选择 Amazon Selling Partner APIs 的事件

然后选择 Custom patterns, 来定义规则来对 EventBridge 发来的消息进行过滤和路由。
我们以 LISTINGS_ITEM_STATUS_CHANGE 通知类型为例添加来过滤单一事件类型的规则规则。其他可选的通知类型可参考通知类型文档中的介绍。

{
  "source": [{
    "prefix": "aws.partner/sellingpartnerapi.amazon.com"
  }],

  "account": ["yourAccountId"],
  "detail-type": ["LISTINGS_ITEM_STATUS_CHANGE"]
}

在 Target 中，选择本区域中创建好的 SNS 服务，借助 Amazon SNS 可以通过 SMS，移动推送和电子邮件将消息大规模发送给用户。本例中我们将推送至先前配置好的邮件收件人中。此外 EventBridge 也可将消息推送至其他 EventBridge/Kinesis/SQS/Lambda/Step Function 等目标中，将消息进行分发或处理。

至此，我们完成了 EventBridge 的创建。

Step4. 通过调用 Notifications API 创建订阅(Create Subscription)

接下来，我们以 LISTINGS_ITEM_STATUS_CHANGE 为例向 SP-API 发送请求来创建 EventBridge 对于通知类型的订阅。

destinationParams = {
        "payloadVersion": "1.0",
        "destinationId": "yourDestination"
}

createSubscriptionResponse = requests.get(normal_endpoint+"/notifications/v1/subscriptions/LISTINGS_ITEM_STATUS_CHANGE",
                                               data=json.dumps(destinationParams),headers=headers, auth=auth)

返回的结果如下：

    "payload": {
        "subscriptionId": "yourSubscriptionId",
        "payloadVersion": 1.0,
        "destinationId": "yourDestination"
    }
}

至此，我们完成了针对 LISTINGS_ITEM_STATUS_CHANGE 的订阅。

Step5.监测到相应事件后，通知自动发送到订阅 EventBridge 的目的地中

当我们的 Listing 商品状态发生变化时（例如：Buyable/Discoverable/Delete 等）我们的 SNS 目的地均可以收到通知，通知的对应字段描述如下。

Name	Description	Type	Required
SellerID	卖家 MerchantID	string	Yes
MarketplaceId	亚马逊上对应 listing 的亚马逊 marketplace ID	string	No
Asin	Listing 项的 Amazon Standard Identification Number (ASIN)	string	No
Sku	受影响商品的 SKU	string	Yes
CreatedDate	Listing 创建时的 ISO8601 时间戳	string	No
Status	当前 Listing 项的状态组，当前没有包含的状态，代表当前 Listing 项当前不适用。例如，如果“BUYABLE”不存在，则 Listing 项当前不可购买。	Array of ListingsItemStatus	Yes