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

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

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

准备工作

  1. 如果您之前未使用过 Batch，请查看 Batch 使用入门 ，并完成 项目和用户的前提条件，以启用 Batch。
  2. 如果您想为 Batch 作业设置 Pub/Sub 通知，请执行以下操作：

    1. 启用 Pub/Sub API。

      启用 API 所需的角色

      如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

      启用 API

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

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

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

    1. 启用 BigQuery API。

      启用 API 所需的角色

      如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

      启用 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 主题或 确定要用于 Batch 通知的现有 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 的订阅

通过执行以下操作，配置将主题中的通知流式传输到 BigQuery 表的 Pub/Sub 订阅：

  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`

后续步骤