通知子 API 總覽

當 Merchant Center 帳戶中的資料有異動時，你可以使用 Notifications 子 API 接收推播通知。您可以訂閱即時事件動態消息，直接傳送到您設定的 HTTPS 端點，不必定期輪詢 API 來偵測變更。

Notifications 子 API 支援下列通知：

  • 產品狀態變更： 在任何已連結的帳戶或子帳戶中，當產品核准狀態變更時 (例如產品遭拒登或獲得核准)，系統會即時發出快訊。
  • 帳戶服務變更：在建立、更新或刪除 AccountService 資源時，接收即時快訊 (例如建立、修改或移除帳戶服務關係時)。

必要條件和回呼 URI 設定

如要接收推播通知，你必須提供 callBackUri。回呼 URI 必須符合下列規定：

  • 必須是可公開存取的 HTTPS 位址，且具有由認可的憑證授權單位簽署的有效 SSL 憑證。
  • 必須接受 HTTP POST 要求，並將 Content-Type 標頭設為 application/json。

  • 必須傳回下列其中一個 HTTP 狀態碼，確認已收到通知：

    • 102
    • 200
    • 201
    • 202
    • 204

多個訂閱項目可以共用同一個回呼 URI。為盡量減少單一端點的負載，請為每個進階帳戶和事件類型使用不重複的回呼 URI。

管理訂閱項目

Notifications 子 API 提供建立、列出、擷取、更新及刪除通知設定的方法。

建立訂閱項目

建立訂閱項目時，請指定要接收的事件類型。每種事件類型都需要不同的設定欄位，並提供不同的酬載結構。

如要瞭解如何建立訂閱項目，以及查看各事件類型的範例要求，請參閱下列指南：

可列出訂閱項目

如要列出帳戶的所有通知訂閱項目，請將 GET 要求傳送至 notificationsubscriptions 集合：

GET https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions

擷取訂閱項目

如要取得特定訂閱項目的詳細資料，請使用訂閱項目的資源名稱：

GET https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}

更新訂閱項目

如要更新現有訂閱項目的回呼 URI，請傳送 PATCH 要求，並使用 update_mask 指定要更新的欄位：

PATCH https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}?update_mask=callBackUri

{
  "callBackUri": "https://example.com/updated-callback"
}

刪除訂閱項目

如要停止接收通知，請刪除訂閱項目：

DELETE https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}

解碼通知

發生事件時，Google 會將通知傳送到您註冊的callBackUri。推送通知會以 JSON 封包的形式傳送，並包含以 base64 編碼的 data 酬載：

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

解碼資料字串，存取 JSON 事件酬載。下列 Spring Boot 控制器範例說明如何接收及解碼推播通知：

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void handleNotification(@RequestBody String message) {
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        String encodedData = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(encodedData);
        String decodedPayload = new String(decodedBytes);
        // Process decodedPayload according to the registered event type
  }
}

後續步驟

如要設定訂閱項目及處理特定事件的已解碼酬載，請參閱：

下一頁
Product status changes