接收关于账号数据更改的推送通知

您可以使用 Merchant Notifications API 接收有关账号数据更改的推送通知。例如，如果您订阅了商品状态变化通知，则可以在商品被拒批时实时收到通知。您可以为自己的任何子账号或其他关联账号订阅通知。

本指南提供了有关如何管理商品状态变化通知的示例。您可以使用这些示例来管理其他事件的通知，只需更改请求中的 registeredEvent 字段的值即可。如需查看事件类型的完整列表，请参阅 Merchant Notifications API 参考文档。

订阅

如需接收通知，您需要拥有 callBackUri。您的回调 URI 必须满足以下要求：

• 必须是可公开访问的 HTTPS 地址，且具有由证书授权机构签名的有效 SSL 证书。
• 必须接受包含 Content-Type 标头和 application/json 值的 HTTP POST 请求。
• 必须返回以下某个响应代码，以确认已收到通知。
  • 102
  • 200
  • 201
  • 202
  • 204

您可以为多个订阅使用相同的回调 URI。我们建议为每个高级账号和每种事件类型使用唯一的回调 URI，以尽量减少对单个 URI 的推送请求负载。

以下是订阅特定商家账号商品状态变更通知的请求示例。在请求网址中，使用应接收通知的账号的商家 ID 作为 merchantId；在请求正文中，使用要接收通知的账号的商家 ID 作为 targetMerchantId。如果您的账号是没有关联账号的独立账号，并且您希望为自己的账号接收通知，请在这两个位置使用您自己的商家 ID。

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETMERCHANT_ID",
  "callBackUri": "https://example.com"
}

成功的调用会为您的订阅返回 name，其中包含订阅 ID：

{
  "name":"accounts/MERCHANT_ID/notificationsubscriptions/subscriptionId",
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETMERCHANT_ID",
  "callBackUri": "https://example.com"
}

您可以使用此 name GET 和 DELETE 单个订阅。

您可以订阅有关所有关联账号的产品状态变更的通知，只需在请求中添加 "allManagedAccounts": true（而非 targetAccount）即可：

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com"
}

如需更新现有订阅，请将 PATCH 与 update_mask 搭配使用，在 JSON 正文中指定要更新的字段及其新值：

PATCH https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri

{
  "​callBackUri": "https://my-own-personal-domain.com"
}

解码通知

创建订阅后，您会收到发送到指定 callBackUri 的通知，格式如下：

{"message":{"data":"{base64_encoded_string}"}}

通知数据已编码。您可以将数据解码为可读取的文本格式，以便在实现中使用。下面是一个 Spring Boot 控制器示例，您可以使用它来处理编码数据：

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void doStuff(@RequestBody String message) {
        //wrapped message
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        message = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(message);
        String decodedMessage = new String(decodedBytes);
        // Implement your business logic here
  }
}

下面是一个已解码的 base64_encoded_string 示例：

{
  "account": "accounts/TARGETMERCHANT_ID",
  "managingAccount": "accounts/MERCHANT_ID",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/TARGETMERCHANT_ID/products/ONLINE~en~US~1234",
  "expirationTime": "2024-10-22T02:43:47.461464Z"
}

如果通知中没有 oldValue 字段，则表示系统已向您的账号添加了新商品。如果没有 newValue 字段，则表示该商品已从您的账号中删除。

reportingContext 字段仅支持枚举值 ReportingContextEnum 中的值 (SHOPPING_ADS、LOCAL_INVENTORY_ADS、YOUTUBE_SHOPPING、YOUTUBE_CHECKOUT、YOUTUBE_AFFILIATE)。

对于商品状态变更事件，oldValue 和 newValue 字段将具有以下值之一：(approved, pending, disapproved, ``)。

测试实现效果

以下是可用于测试回调 URI 和解码的通知示例：

curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIgp9"}}' https://{callBackUri}

作为对此调用的响应，您的回调 URI 应返回成功响应代码。解码后的消息应具有以下值：

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~000000000000",
  "resource": "accounts/1234/products/ONLINE~en~US~000000000000",
  "expirationTime": "2024-10-22T02:43:47.461464Z"
}