您可以使用 Merchant Notifications API 來取得帳戶資料變更的推播通知。舉例來說,如果您訂閱了產品狀態變更通知,即可在產品遭到拒登時即時收到通知。您可以訂閱任何子帳戶或其他已連結帳戶的通知。
本指南將舉例說明如何管理產品狀態變更通知。您可以使用這些範例,變更要求中的 registeredEvent
欄位值,管理其他事件的通知。如需事件類型的完整清單,請參閱 Merchant Notifications API 參考資料。
訂閱
如要接收通知,你必須擁有 callBackUri
。回呼 URI 必須符合下列規定:
- 必須是可公開存取的 HTTPS 位址,並具備由憑證授權單位簽署的有效 SSL 憑證。
- 必須接受含有
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"