Pub/Sub 通知

完成 Storage 移轉服務移轉作業後，您可能想啟動其他工作、處理移轉期間發生的錯誤，或記錄移轉作業。Pub/Sub 提供佇列，讓程式訂閱，以便在轉移完成時接收訊息。這樣您就能重複使用程式碼，並根據轉移狀態規劃後續步驟。

如要進一步瞭解 Pub/Sub，請參閱「什麼是 Cloud Pub/Sub」

必要條件

如要使用這項功能，請先完成下列步驟：

  1. 為接收 Pub/Sub 通知的專案啟用 Pub/Sub API。

    啟用 API

  2. 擁有現有的 Pub/Sub 主題，可接收您所傳送的通知。

  3. 針對與包含 Storage 移轉服務值區的專案相關聯的服務帳戶，取得服務帳戶的電子郵件地址。

    1. 為所需 Pub/Sub 主題授予服務帳戶 IAM 角色 roles.pubsub.publisher。

設定通知

如要設定 Storage 移轉服務的 Pub/Sub 通知設定，請使用 Storage 移轉服務 transferJobs API 建立 NotificationConfig 訊息。主題會透過設定的 Pub/Sub 管道接收通知。

在 NotificationConfig 訊息中指定下列項目：

  • 要傳送通知的 Pub/Sub 主題
  • 訊息格式，"JSON" 或 "NONE"

  • 與完成的TransferOperation.Statuses相應的所需事件類型：

    • "TRANSFER_OPERATION_SUCCESS"
    • "TRANSFER_OPERATION_FAILED"
    • "TRANSFER_OPERATION_ABORTED"

以下是 NotificationConfig 訊息範例：

{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_SUCCESS"],
     "payloadFormat": "JSON"
   },
   ...
}

更改下列內容：

  • project-id：轉移作業的 Google Cloud 專案 ID
  • topic-id：Pub/Sub 主題名稱

詳情請參閱 Storage 移轉服務 Pub/Sub REST 規格。

通知格式

傳送至 Pub/Sub 主題的通知分為以下兩部分：

  • 屬性：用於說明事件的鍵/值組合。
  • 酬載：含變更物件的中繼資料的字串。

屬性

屬性是 Storage Transfer Service 傳送至 Pub/Sub 主題的所有通知中包含的鍵/值組合。無論通知酬載為何，通知都會包含以下鍵值組合：

如要進一步瞭解 Pub/Sub 訊息格式，請參閱 PubsubMessage。

屬性名稱 範例 說明
eventType TRANSFER_OPERATION_SUCCESS TransferOperation的狀態，從 NotificationConfig.EventType
payloadFormat "JSON" 訊息格式，可以是 "JSON" 或 "NONE"。NotificationConfig.PayloadFormat 起。
projectId project-3 轉移主專案的 ID。
transferJobName transferJobs/123 轉移工作名稱。
transferOperationName transferOperations/456 移轉作業的名稱。

酬載

酬載包含 TransferOperation 中繼資料。建立通知設定時，需要指定該設定觸發的通知中包含的酬載類型。您可以指定以下酬載類型：

酬載類型 說明
NONE 通知不會包含任何酬載。
JSON 酬載會格式化為 application/json 中的 JSON 回應。

Pub/Sub 通知設定範例

僅在轉移失敗時通知

如要只接收轉移失敗的訊息，請提交 TransferJob，並使用 NotificationConfig 篩選器，只篩選轉移失敗的訊息：

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_FAILED"],
     "payloadFormat: "JSON"
   },
   ...
}

更改下列內容：

  • project-id：轉移作業的 Google Cloud 專案 ID
  • topic-id：Pub/Sub 主題名稱

在所有轉移作業完成時通知

如要針對所有完成的轉移作業 (不論狀態為何) 傳送通知，請提交不含 EventType 篩選器的 TransferJob 和 NotificationConfig：

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "payloadFormat: "JSON"
   },
   ...
}

更改下列內容：

  • project-id：轉移作業的 Google Cloud 專案 ID
  • topic-id：Pub/Sub 主題名稱

對轉移作業執行任意動作

如要執行任意動作，請使用具有 Pub/Sub 觸發條件的 Cloud 函式，搭配背景 Cloud 函式建立 Pub/Sub 通知。詳情請參閱 Cloud Pub/Sub 教學課程。

任意動作的例子包括：

關於通知訊息的注意事項

新增通知設定後，Storage 移轉服務會傳送所有TransferOperations啟動的通知，並保證至少向 Pub/Sub 傳送一次。Pub/Sub 也會至少向接收者傳送一次，這表示您可以收到代表相同 Storage Transfer Service 事件、具有多個 ID 的多個訊息。

系統無法保證能以 Pub/Sub 接收通知的順序發布通知。

如果系統持續無法將通知傳送至 Pub/Sub 主題，Storage 移轉服務可能會在 7 天後刪除該項通知。以下的情況可能會導致傳送失敗：Pub/Sub 主題已不存在、Storage Transfer Service 不再具有發布主題的權限，或擁有主題的專案超過發布配額。