通知子 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