本文档介绍了如何通过设置 Pub/Sub 通知来监控作业和任务状态的变化。您可以将通知用于各种用例。例如,本文档介绍了如何将通知流式传输到 BigQuery 表,您可以使用该表分析数据。如需详细了解 Pub/Sub 通知的用例,请参阅 Pub/Sub 文档中的选择订阅类型。
准备工作
- 如果您之前未使用过 Batch,请查看 Batch 使用入门,并通过完成项目和用户的前提条件来启用 Batch。
- 如果要为 Batch 作业设置 Pub/Sub 通知,请执行以下操作:
-
启用 Pub/Sub API。
-
如需获取配置 Pub/Sub 主题和订阅所需的权限,请让管理员为您授予项目的 Pub/Sub Editor (
roles/pubsub.editor
) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限。
-
- 其他要求因您决定配置的订阅类型而异。例如,如果要流式传输和分析 BigQuery 表的通知,您必须执行以下操作:
-
启用 BigQuery API。
-
为了确保 Pub/Sub 服务帐号具有将 Pub/Sub 通知流式传输到 BigQuery 所需的权限,请让管理员向 Pub/Sub 服务帐号授予 Pub/Sub 主题项目的 BigQuery Data Editor (
roles/bigquery.dataEditor
) IAM 角色。如需详细了解如何分配此角色,请参阅将 BigQuery 角色分配给 Pub/Sub 服务帐号。
- 确保您想要在 BigQuery 中分析通知的任何用户都拥有所需的权限。
如需获取在 BigQuery 中查询 Pub/Sub 通知所需的权限,请让管理员授予您以下 IAM 角色:
-
BigQuery 表项目的 BigQuery Job User (
roles/bigquery.jobUser
) -
针对 BigQuery 表的 BigQuery Data Viewer (
roles/bigquery.dataViewer
)
-
BigQuery 表项目的 BigQuery Job User (
-
为 Batch 设置 Pub/Sub 通知
Batch 支持在作业和任务状态更改时通过 Pub/Sub 发出通知,并将其用于提醒、可观测性或分析。
如需为一个或多个批量作业设置 Pub/Sub 通知,请完成以下各部分中介绍的步骤:
为 Batch 设置 Pub/Sub 通知后,您可以选择将每项作业配置为发送特定通知。您可以在作业或任务状态的任何变化时接收通知,也可以过滤特定作业或任务状态的通知。值得注意的是,Pub/Sub 不会针对作业或任务进入的第一个状态发送通知;Pub/Sub 仅在作业从一种状态变为另一种状态时才会发送通知。如需详细了解您可以为 Pub/Sub 通知配置的属性,请参阅创建并运行发送 Pub/Sub 状态通知的作业。
为 Batch 创建或识别 Pub/Sub 主题
创建新的 Pub/Sub 主题或标识要用于批量通知的现有 Pub/Sub 主题。
如本文档后面部分所述,在您的管理员授予允许的其他权限之前,作业无法向此 Pub/Sub 主题发送通知。
创建订阅以接收和使用通知
如需接收和使用发布到 Pub/Sub 主题的消息,您必须至少创建一个对该主题的订阅。
例如,一种选项是配置主题以将其通知流式传输到 BigQuery。然后,当您运行用于发布通知的作业时,可以接收和分析 BigQuery 表中的通知。如需了解详情,请参阅本文档中的示例:在 BigQuery 中接收和使用 Pub/Sub 通知。
否则,如需详细了解订阅和其他订阅选项,请参阅 Pub/Sub 文档中的订阅概览。
配置作业以向您的主题发送通知
如需配置向您的主题发送 Pub/Sub 通知的作业,请按照创建和运行发送 Pub/Sub 状态通知的作业页面上的说明操作。具体而言,请执行以下操作:
- 如果您尚未授予作业向您的 Pub/Sub 主题发送通知所需的所有权限,请让管理员授予。该页面的所需角色部分列出了这些权限。
- 通过定义作业的
notifications
字段来创建并运行启用 Pub/Sub 通知的作业。
示例:在 BigQuery 中接收和使用 Pub/Sub 通知
以下部分介绍了在 BigQuery 中接收和使用 Pub/Sub 通知的示例用例。通过配置订阅以将主题的 Pub/Sub 通知流式传输到 BigQuery 表,您可以保留作业和任务状态更改的历史记录,并查询这些更改。
配置将通知流式传输到 BigQuery 的订阅
执行以下操作来配置 Pub/Sub 订阅,将来自主题的通知流式传输到 BigQuery 表:
如果您尚未为 Batch 创建或标识 Pub/Sub 主题,请执行此操作。
如果您还没有 BigQuery 数据集,请创建一个。
使用以下架构定义创建 BigQuery 表:
[ { "name": "data", "type": "STRING" }, { "name": "subscription_name", "type": "STRING" }, { "name": "message_id", "type": "STRING" }, { "name": "attributes", "type": "JSON" }, { "name": "publish_time", "type": "TIMESTAMP", "mode": "NULLABLE" } ]
创建流式传输到 BigQuery 的 Pub/Sub 订阅并指定以下选项:
- 主题:为 Batch 选择 Pub/Sub 主题。
- 项目:选择 BigQuery 表所属的项目。
- 数据集:选择 BigQuery 表所属的数据集。
- 表格:选择您在上一步中创建的表格。
- 选择使用主题架构。
- 选择写入元数据。
现在,每当 Pub/Sub 通知发送到该主题时,Pub/Sub 都会将该通知流式传输到 BigQuery 表。将作业配置为发送 Pub/Sub 通知后,您可以在 BigQuery 中分析通知。
在 BigQuery 中分析通知
在为您的主题配置对 BigQuery 表的订阅后,您可以分析 BigQuery 中的通知,并运行向主题发送通知的作业。如需分析 BigQuery 中的通知,请对 BigQuery 表的 attributes
列运行查询。可以查询的属性取决于您是为任务还是为作业配置了通知。
您可以查询任务通知的以下属性:
JobUID
NewTaskState
Region
TaskName
TaskUID
Type
您可以查询作业通知的以下属性:
JobUID
JobName
NewJobState
Region
Type
例如,以下查询会显示与每个通知关联的 JobUID
:
select attributes.JobUID from `example-table`
后续步骤
- 了解如何创建和运行发送 Pub/Sub 状态通知的作业。
- 详细了解 Pub/Sub 订阅。
- 详细了解 BigQuery 分析。