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 主題的通知包含兩個部分:

  • 屬性:用於說明事件的鍵/值組合。
  • 酬載:如果酬載格式為 JSON,則為包含 TransferOperation 資源的字串。

屬性

屬性是 Storage 移轉服務傳送至 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 酬載會格式化為 JSON 回應,格式為 application/json。

Pub/Sub 通知設定範例

僅在轉移失敗時通知

如要只接收轉移失敗的訊息,請提交 TransferJob,並使用 NotificationConfig 篩選出轉移失敗的訊息:

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

更改下列內容:

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

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

如要針對所有已完成的移轉作業 (不論狀態為何) 傳送通知,請提交 TransferJob,並在其中加入 NotificationConfig,但不加入 EventType 篩選器:

{
   ...
   "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 也會至少傳送一次訊息給收件者,這表示您可能會收到多則訊息,其中包含多個 ID,代表同一個 Storage 移轉服務事件。

通知不一定會按照 Pub/Sub 接收的順序發布。

如果通知持續無法傳送至 Pub/Sub 主題,Storage 移轉服務可能會在 7 天後刪除通知。如果 Pub/Sub 主題已不存在、Storage 移轉服務不再具備發布至主題的權限,或擁有主題的專案超出發布配額,就可能發生傳送失敗的情況。