本頁面由 Cloud Translation API 翻譯而成。

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

您可以使用 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",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}

如果通知中沒有 oldValue 欄位，表示帳戶中新增了新產品。如果沒有 newValue 欄位，表示產品已從帳戶中刪除。

如果產品已刪除，就不會有 expirationTime 欄位。

reportingContext 欄位僅支援列舉值 ReportingContextEnum 中的 (SHOPPING_ADS、LOCAL_INVENTORY_ADS、YOUTUBE_SHOPPING、YOUTUBE_CHECKOUT、YOUTUBE_AFFILIATE)。

對於產品狀態變更事件，oldValue 和 newValue 欄位會包含下列任一值：approved、pending、disapproved、``。

eventTime 欄位會保留事件本身的建立時間，如果您想排序訊息，應依據該欄位的值，而非收到訊息的順序。

請參閱 ProductStatusChangeMessage 格式，瞭解詳細資訊。

測試實作成果

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

curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIiwKICAiZXZlbnRUaW1lIjogIjIwMjQtMDMtMjFUMDI6NDM6NDcuNDYxNDY0WiIKfQ=="}}' 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",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}

Control access to your account

Enable automatic improvements