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 酬載會以 JSON 回應格式，在 application/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 主題名稱

在所有完成的轉移作業中發出通知

如要通知所有已完成的轉移作業 (無論狀態為何)，請提交包含 NotificationConfig 但不含 EventType 篩選器的 TransferJob：

// 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 函式搭配背景雲端函式建立 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 不再具有發布主題的權限，或擁有主題的專案超過發布配額。