您可以使用 Merchant Notifications API 接收关于帐号数据更改的推送通知。例如,如果您订阅了商品状态更改通知,则可以在商品遭拒批时实时收到通知。您可以为您的任何子帐号或其他关联帐号订阅通知。
本指南举例说明了如何管理有关商品状态变化的通知。您可以使用这些示例来管理其他事件的通知,只需更改请求中 registeredEvent
字段的值即可。如需查看事件类型的完整列表,请参阅 Merchant Notifications API 参考文档。
订阅
若要接收通知,您需要拥有 callBackUri
。您的回调 URI 必须满足以下要求:
- 必须是具有有效 SSL 证书且由证书授权机构签名且可公开访问的 HTTPS 地址。
- 必须接受带有
Content-Type
标头和application/json
值的 HTTPPOST
请求。 - 必须返回以下响应代码之一,以确认已收到通知。
102
200
201
202
204
您可以为多个订阅使用相同的回调 URI。我们建议为每个高级帐号针对每个事件类型使用唯一的回调 URI,以尽可能减少向单个 URI 发送的推送请求的负载。
下面是一个示例请求,用于订阅特定商家帐号的商品状态变化通知。在请求网址中,将应接收通知的帐号的商家 ID 用作 merchantId
,并在请求正文中使用要接收通知的帐号的商家 ID 作为 targetMerchantId
。如果您的帐号是未关联帐号的独立帐号,并且您希望在自己的帐号时收到通知,请在这两个位置都使用您自己的商家 ID。
POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/merchantId/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/targetMerchantId",
"callBackUri": "https://example.com"
}
成功的调用会针对您的订阅返回 name
,包括订阅 ID:
{
"name":"accounts/merchantId/notificationsubscriptions/subscriptionId",
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"targetAccount": "accounts/targetMerchantId",
"callBackUri": "https://example.com"
}
您可以使用此name
来GET
和DELETE
个人订阅。
您可以订阅所有关联帐号的商品状态变化通知,只需在请求中添加 "allManagedAccounts": true
而不是 targetAccount
即可:
POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/merchantId/notificationsubscriptions/
{
"registeredEvent": "PRODUCT_STATUS_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com"
}
如需更新现有订阅,请使用 PATCH
和 update_mask
来指定要更新的字段,以及 JSON 正文中的新值:
PATCH /notifications/v1beta/accounts/merchantId/notificationsubscriptions/subscriptionId?update_mask=callBackUri
{
"callBackUri": "https://my-own-personal-domain.com"
}
解码通知
创建订阅后,您会收到发送给指定 callBackUri
的通知,格式如下:
{"message":{"data":"{base64_encoded_string}"}}
通知数据已经过编码。您可以将数据解码为可读文本格式,以便在实现中使用。以下是一个弹簧启动控制器示例,您可以使用它来处理已编码的数据:
@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/targetMerchantId"
"managing_account": "accounts/merchantId"
"resource_type": PRODUCT
"attribute": STATUS
"changes": {
"old_value": "eligible"
"new_value": "disapproved"
"region_code": "GE"
"reporting_context": SHOPPING_ADS
},
"changes" {
"old_value": "eligible"
"new_value": "disapproved"
"region_code": "JP"
"reporting_context": SHOPPING_ADS
},
changes {
"old_value": "eligible"
"new_value": "disapproved"
"region_code": "US"
"reporting_context": SHOPPING_ADS
}
resource_id: "ONLINE~en~US~1234"
resource: "accounts/targetMerchantId/products/ONLINE~en~US~1234"
测试实现效果
以下是可用于测试回调 URI 和解码的示例通知:
curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ImFjY291bnQiOiAiYWNjb3VudHMvMTIzNCIKIm1hbmFnaW5nX2FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIKInJlc291cmNlX3R5cGUiOiBQUk9EVUNUCiJhdHRyaWJ1dGUiOiBTVEFUVVMKImNoYW5nZXMiOiB7CiAgIm9sZF92YWx1ZSI6ICJlbGlnaWJsZSIKICAicmVnaW9uX2NvZGUiOiAiVVMiCiAgInJlcG9ydGluZ19jb250ZXh0IjogU0hPUFBJTkdfQURTCn0KInJlc291cmNlX2lkIjogIk9OTElORX5lbn5VU34wMDAwMDAwMDAwMDAiCiJyZXNvdXJjZSI6ICJhY2NvdW50cy8xMjM0L3Byb2R1Y3RzL09OTElORX5lbn5VU34wMDAwMDAwMDAwMDAi"}}' https://{callBackUri}
为了响应此调用,您的回调 URI 应返回一个成功的响应代码。解码后的消息应具有以下值:
"account": "accounts/1234"
"managing_account": "accounts/5678"
"resource_type": PRODUCT
"attribute": STATUS
"changes": {
"old_value": "eligible"
"region_code": "US"
"reporting_context": SHOPPING_ADS
}
"resource_id": "ONLINE~en~US~000000000000"
"resource": "accounts/1234/products/ONLINE~en~US~000000000000"