接收帳戶資料變更的推播通知

您可以使用 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/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}"}}

通知資料已編碼。您可以將資料解碼為可讀取的文字格式，以便在實作中使用。以下是您可能用來處理經過編碼的資料的 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/targetMerchantId",
  "managingAccount": "accounts/merchantId",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "eligible",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "eligible",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "eligible",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/targetMerchantId/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)。

測試實作成果

以下是可用於測試回呼 URI 和解碼的通知範例：

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

為回應這項呼叫，回呼 URI 應傳回成功的回應代碼。解碼後的訊息應具有以下值：

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "eligible",
    "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"
}