使用 Pub/Sub 通知和 BigQuery 监控作业状态

本文档介绍了如何通过设置 Pub/Sub 通知来监控作业和任务状态变化。您可以将通知用于各种用例,例如,本文档介绍了如何将通知流式传输到 BigQuery 表,以便您分析数据。如需详细了解 Pub/Sub 通知的用例,请参阅 Pub/Sub 文档中的选择订阅类型

或者,如果您想将作业的所有信息导出到 BigQuery,请参阅导出作业信息

准备工作

  1. 如果您之前未使用过 Batch,请查看开始使用 Batch 并完成项目和用户的前提条件,以启用 Batch。
  2. 如果您想为批量作业设置 Pub/Sub 通知,请执行以下操作:
    1. Enable the Pub/Sub API.

      Enable the API

    2. 如需获得配置 Pub/Sub 主题和订阅所需的权限,请让您的管理员为您授予项目的 Pub/Sub Editor (roles/pubsub.editor) IAM 角色。 如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限

      您也可以通过自定义角色或其他预定义角色来获取所需的权限。

  3. 其他要求因您决定配置的订阅类型而异。例如,如果您想将通知流式传输到 BigQuery 表并进行分析,则必须执行以下操作:
    1. Enable the BigQuery API.

      Enable the API

    2. 为了确保 Pub/Sub 服务账号拥有将 Pub/Sub 通知流式传输到 BigQuery 所需的权限,请让管理员向 Pub/Sub 服务账号授予 Pub/Sub 主题所在项目的 BigQuery Data Editor (roles/bigquery.dataEditor) IAM 角色。

      如需详细了解如何分配此角色,请参阅为 Pub/Sub 服务账号分配 BigQuery 角色

    3. 确保您希望在 BigQuery 中分析通知的所有用户都拥有所需权限。

      如需获得在 BigQuery 中查询 Pub/Sub 通知所需的权限,请让管理员为您授予以下 IAM 角色:

为 Batch 设置 Pub/Sub 通知

Batch 支持针对作业和任务状态更改的 Pub/Sub 通知,您可将其用于提醒、可观测性或分析。

如需为一个或多个 Batch 作业设置 Pub/Sub 通知,请完成以下部分中所述的步骤:

  1. 为您的 Batch 作业创建或确定 Pub/Sub 主题
  2. 为主题创建至少一个订阅,以便接收和使用其通知
  3. 配置作业以向您的主题发送通知

为 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 状态通知的作业页面上的说明操作。具体来说,请执行以下操作:

  1. 如果尚未完成此操作,请让管理员授予作业向您的 Pub/Sub 主题发送通知所需的所有权限。 这些权限列在该页面的所需角色部分中。
  2. 创建并运行作业,通过定义作业的 notifications 字段来启用 Pub/Sub 通知。

示例:在 BigQuery 中接收和使用 Pub/Sub 通知

以下部分将介绍一个在 BigQuery 中接收和使用 Pub/Sub 通知的用例示例。通过配置将主题的 Pub/Sub 通知流式传输到 BigQuery 表的订阅,您可以保留作业和任务状态更改的历史记录,并查询这些更改。

配置将通知流式传输到 BigQuery 的订阅

通过执行以下操作,配置一个 Pub/Sub 订阅,该订阅可将主题中的通知流式传输到 BigQuery 表:

  1. 如果您尚未创建,请为 Batch 创建或确定一个 Pub/Sub 主题

  2. 如果您还没有 BigQuery 数据集,请创建一个

  3. 创建具有以下架构定义的 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"
      }
    ]
    
  4. 创建流式传输到 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`

后续步骤