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 不再具有向主题发布通知的权限时,或者拥有该主题的项目超出发布配额时,通知可能会递送失败。