本文档介绍了如何通过设置 Pub/Sub 通知来监控作业和任务状态变化。您可以将通知用于各种用例,例如,本文档介绍了如何将通知流式传输到 BigQuery 表,以便您分析数据。如需详细了解 Pub/Sub 通知的用例,请参阅 Pub/Sub 文档中的选择订阅类型。
或者,如果您想将作业的所有信息导出到 BigQuery,请参阅导出作业信息。
准备工作
- 如果您之前未使用过 Batch,请查看开始使用 Batch 并完成项目和用户的前提条件,以启用 Batch。
- 如果您想为批量作业设置 Pub/Sub 通知,请执行以下操作:
-
Enable the Pub/Sub API.
-
如需获得配置 Pub/Sub 主题和订阅所需的权限,请让您的管理员为您授予项目的 Pub/Sub Editor (
roles/pubsub.editor
) IAM 角色。 如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
-
- 其他要求因您决定配置的订阅类型而异。例如,如果您想将通知流式传输到 BigQuery 表并进行分析,则必须执行以下操作:
-
Enable the BigQuery API.
-
为了确保 Pub/Sub 服务账号拥有将 Pub/Sub 通知流式传输到 BigQuery 所需的权限,请让管理员向 Pub/Sub 服务账号授予 Pub/Sub 主题所在项目的 BigQuery Data Editor (
roles/bigquery.dataEditor
) IAM 角色。如需详细了解如何分配此角色,请参阅为 Pub/Sub 服务账号分配 BigQuery 角色。
- 确保您希望在 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 通知,您可将其用于提醒、可观测性或分析。
如需为一个或多个 Batch 作业设置 Pub/Sub 通知,请完成以下部分中所述的步骤:
为 Batch 设置 Pub/Sub 通知后,您可以选择将每个作业配置为发送特定通知。您可以随时接收作业或任务状态变更通知,也可以过滤通知,以便仅接收特定作业或任务状态的通知。值得注意的是,Pub/Sub 不会针对作业或任务进入的第一个状态发送通知;Pub/Sub 仅在作业从一种状态转移到另一种状态时发送通知。
如需详细了解可为 Pub/Sub 通知配置的属性,请参阅创建并运行发送 Pub/Sub 状态通知的作业。
为 Batch 创建或确定 Pub/Sub 主题
创建新的 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 数据集,请创建一个。
-
[ { "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 分析。