從物件變更通知遷移至 Pub/Sub 通知

本指南適用於 Cloud Storage 物件變更通知功能的使用者。建議使用 Cloud Storage 的 Pub/Sub 通知，產生可追蹤 Cloud Storage 值區中物件變更的通知。Pub/Sub 通知在速度、彈性、設定和成本效益方面都有所提升。本指南說明物件變更通知與 Cloud Storage 的 Pub/Sub 通知之間的差異，並提供從物件變更通知遷移至 Pub/Sub 通知的遷移步驟。

物件變更通知總覽

物件變更通知是 Cloud Storage 的舊版機制，用於通知應用程式值區中物件的變更。設定物件變更通知後，每當新增、更新或刪除物件，Cloud Storage 就會將 HTTP POST 要求 (webhook) 傳送至指定的應用程式網址。如要建立物件變更通知，請使用 JSON API、用戶端程式庫或 gsutil 通知 watchbucket 指令，將 watchAll 要求傳送至 Cloud Storage。沒有 pull 機制，您必須擁有由 HTTP 伺服器支援的公開存取網域名稱，才能接收 Webhook 訊息。由於 Pub/Sub 通知具有可靠性、可擴充性和靈活性，因此建議您在新實作項目中使用 Cloud Storage 適用的 Pub/Sub 通知。

詳情請參閱物件變更通知。

Pub/Sub 通知總覽

Cloud Storage 的 Pub/Sub 通知提供現代化、可擴充且可靠的方式，可將事件資訊傳送至 Pub/Sub 主題，藉此觸發動作，因應 Cloud Storage 值區的變更。Pub/Sub 會以 HTTP POST 要求的形式，將訊息推送至 Webhook。當物件建立、更新或刪除時，Cloud Storage 會將包含物件中繼資料的訊息發布至指定的 Pub/Sub 主題，然後由 Cloud Run 函式、資料管道或微服務等各種訂閱者取用，透過至少一次傳送和強大的錯誤處理功能，實現彈性且事件驅動的架構。

如需更多詳細資訊，請參閱「Cloud Storage 的 Pub/Sub 通知」。

比較物件變更通知與 Pub/Sub 通知

下表比較物件變更通知與 Pub/Sub 通知功能：

功能 物件變更通知 Pub/Sub 通知
Purpose 當值區中的物件變更時，透過 HTTP POST 要求 (Webhook) 直接通知應用程式。 變更 Cloud Storage 值區物件時，將相關資訊傳送至 Pub/Sub 主題。
放送機制 直接將 HTTP POST (Webhook) 傳送至指定應用程式網址。 發布至 Pub/Sub 主題的訊息隨後可供各種訂閱者使用，例如 Cloud Run 函式、其他應用程式和資料管道。
穩定性 嘗試確保可靠的傳送作業，但無法保證及時性。通知可能會無限期延遲。 提供「至少傳送一次」的保證，也就是訊息可能會多次傳送，但不會遺失。Pub/Sub 會處理訊息的持續性和重試作業。
擴充性 可擴充性較低，因為這類通知依賴應用程式需要處理的直接 Webhook。 具備高擴充性，專為大規模事件處理而設計。
工作彈性 僅限直接整合 Webhook。 極具彈性。Pub/Sub 訊息可以觸發 Cloud Run 函式、饋送至資料管道 (Dataflow)，以及供其他微服務使用。
篩選 無 Pub/Sub 訂閱項目層級提供強大的篩選選項，訂閱者只會收到符合特定條件的訊息。
安全性 應用程式端點必須可公開存取 (HTTPS)。 Pub/Sub 提供 IAM，可精細控管主題和訂閱項目的存取權。無論是直接提取通知，還是將通知推送至公開端點，Pub/Sub 都能協助安全地傳送訊息。
複雜度 基本用途的設定可能較簡單，但管理可靠的放送和擴展功能可能會變得複雜。 需要瞭解 Pub/Sub 概念 (主題、訂閱)，但可為事件導向架構提供更強大且易於管理的解決方案。
淘汰狀態 已淘汰，建議您在新實作項目中使用 Pub/Sub 通知。 使用中。這是 Cloud Storage 通知的主要方法，且目前仍在積極開發中。
建議用途 不建議用於新專案。主要適用於無法遷移的較簡單舊版整合。 強烈建議用於建構強大、可擴充的事件導向架構，以回應 Cloud Storage 變更。

為什麼要遷移至 Pub/Sub 通知？

從舊版物件變更通知遷移至 Pub/Sub，是管理 Cloud Storage 通知事件的重要步驟。建議您在 Trusted Cloud的事件驅動架構中使用 Pub/Sub，因為相較於物件變更通知，Pub/Sub 在技術和作業方面都具有顯著優勢。

遷移至 Pub/Sub 通知的優點如下：

  • 可靠的傳送機制：Pub/Sub 會為每個訂閱項目傳送每個發布的訊息至少一次，確保事件傳送給消費者。相較於可靠性較低的物件變更通知傳送模型，可靠的傳送機制可將資料遺失情況降到最低，並提升工作流程的可靠性。
  • 可擴充性：Pub/Sub 通知專為高輸送量而設計，可自動處理大量事件。使用 Pub/Sub 通知，即可消除物件變更通知可能造成的效能瓶頸，避免資料或事件頻率增加時發生問題。
  • 與服務整合 Trusted Cloud ：Pub/Sub 可與多項 Trusted Cloud 服務無縫整合，讓您靈活運用 Cloud Run 函式、Cloud Run、Dataflow 建立自動化工作流程，並透過 Cloud Logging 和 Cloud Monitoring 提升可觀測性。
  • 精細控管：使用 Pub/Sub 時，您可以在訂閱層級篩選訊息。這樣一來，取用者就只會收到相關事件，減少不必要的處理作業和網路流量。
  • 平台支援：Pub/Sub 通知是支援的訊息傳遞服務。遷移後，您就能使用持續強化、提供安全性更新和完整文件的技術，不像已淘汰的物件變更通知。

遷移步驟

物件變更通知和 Cloud Storage 的 Pub/Sub 通知有時會傳送重複訊息。因此，您必須將取用程式碼設計為可安全處理重複訊息。

如要從物件變更通知遷移至 Pub/Sub 通知，請按照下列步驟操作：

  1. 除了現有的物件變更通知設定，您也可以開始使用 Cloud Storage 適用的 Pub/Sub 通知。如要瞭解如何設定 Pub/Sub 通知，請參閱「設定 Cloud Storage 的 Pub/Sub 通知」。

  2. 測試並確認應用程式的 Pub/Sub 通知處理工作流程正常運作。如要瞭解如何監控 Pub/Sub 訂閱項目，請參閱「在 Pub/Sub 中監控訂閱項目」。

  3. 停止處理從物件變更通知管道收到的訊息。如要停止通知管道，請提出 stop 要求。

Pub/Sub 推送訂閱項目的注意事項

Pub/Sub 提取訂閱項目提供更靈活的控制選項，而 Pub/Sub 推送訂閱項目則與物件變更通知訊息十分相似。因此，推播訂閱功能可做為現有物件變更通知使用者的快速遷移路徑。如要詳細比較推送和提取訂閱，請參閱「選擇訂閱類型」。

如果您打算使用推送訂閱，並重複使用現有的通知處理程式碼，就必須考量物件變更通知與 Pub/Sub 通知推送要求格式和回應程式碼解讀方式的差異。我們將在下面的章節中說明其中的不同之處。

推送要求格式

本節說明物件變更通知和 Pub/Sub 通知的推送要求格式差異。

  • 物件變更通知：物件變更通知會以 HTTP POST 要求的形式，傳送至您的應用程式網址，格式如下：

    POST /ApplicationUrlPath
Accept: * / *
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
"kind": "storage#object",
"id": "BucketName/ObjectName",
"selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
"name": "ObjectName",
"bucket": "BucketName",
"generation": "1367014943964000",
"metageneration": "1",
"contentType": "application/octet-stream",
"updated": "2013-04-26T22:22:23.832Z",
"size": "10",
"md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
"mediaLink": "https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
"owner": {
  "entity": "user-jeffersonloveshiking@gmail.com"
},
"crc32c": "C7+82w==",
"etag": "COD2jMGv6bYCEAE="
}

  • Pub/Sub 通知：如果設定為發送式傳送，系統會以 HTTP POST 要求的形式傳送 Pub/Sub 通知。data 欄位包含 Base64 編碼的 Cloud Storage 事件酬載。解碼資料欄位時，該欄位會與物件變更通知訊息主體相符。

    POST /YourSpecifiedURL
Accept: * / *
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
{
  "deliveryAttempt": 5,
  "message":
    {"attributes":
      {"notificationConfig":"projects/_/buckets/foo/notificationConfigs/3",
        "eventType": "OBJECT_FINALIZE",
        "payloadFormat": "JSON_API_V1",
        "bucketId": "foo",
        "objectId": "bar",
        "objectGeneration": 123456,
        "eventTime": "2021-01-15T01:30:15.01Z"
      },
    "data": "ewogImtpbm",
    "messageId": "2070443601311540",
    "message_id": "2070443601311540",
    "orderingKey": "key",
    "publishTime": "2021-02-26T19:13:55.749Z",
    "publish_time": "2021-02-26T19:13:55.749Z"
    },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

回應碼

下表說明物件變更通知和 Pub/Sub 通知的回應代碼解讀差異：

功能 回應碼 解釋 動作
物件變更通知
102、200、201、202、204 成功 已處理訊息
500、502、503、504 無法處理 稍後再試
逾時、連線失敗、沒有回應 無法處理 稍後再試
任何其他 HTTP 狀態碼。例如：404 Permanent failure 不要重新傳送訊息
Pub/Sub 通知
102、200、201、202、204 成功 訊息已確認
所有其他回應代碼、逾時和連線失敗 失敗 稍後再試

後續步驟