Pub/Sub 通知

完成 Storage Transfer Service 转移后，您可能需要启动另一项任务，处理转移过程中遇到的错误，或记录发生了转移。Pub/Sub 提供了一个队列，可供您的程序订阅以便在转移完成时接收消息。这样，您就可以重复使用代码，并根据转移状态对后续步骤进行编程。

如需详细了解 Pub/Sub，请参阅什么是 Cloud Pub/Sub

前提条件

在使用此功能之前，请先执行以下操作：

  1. 启用 Pub/Sub API，以便项目接收 Pub/Sub 通知。

    启用该 API

  2. 存在要向其发送通知的 Pub/Sub 主题。

  3. 获取与您的 Storage Transfer Service 存储桶所属项目关联的服务账号的电子邮件地址。

    1. 向服务账号授予所需 Pub/Sub 主题的 IAM 角色 roles.pubsub.publisher。

配置通知设置

要配置 Storage Transfer Service Pub/Sub 通知设置，请使用 Storage Transfer Service 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 Transfer Service 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 主题名称

通知所有完成的转移

要通知所有已完成的转移，无论其状态如何，请提交 TransferJob，其中 NotificationConfig 不带 EventType 过滤器：

// 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 Functions 函数并配以Cloud Functions 后台函数创建 Pub/Sub 通知。如需了解详情，请参阅 Cloud Pub/Sub 教程。

任意操作的示例包括：

送达保证

Storage Transfer Service 会在您添加通知配置后就任何启动的 TransferOperations 发送通知，并保证至少向 Pub/Sub 递送一次。Pub/Sub 也会向收件人至少送达一次通知，这意味着，您可能会收到多条消息，这些消息具有多个 ID，但它们均代表同一 Storage Transfer Service 事件。

我们不保证按照 Pub/Sub 接收通知的顺序发布通知。

如果通知始终无法送达 Pub/Sub 主题，Storage Transfer Service 可能会在 7 天后删除通知。当 Pub/Sub 主题不再存在时，Storage Transfer Service 不再具有向主题发布通知的权限时，或者拥有该主题的项目超出发布配额时，通知可能会递送失败。