Supervisa el estado de los trabajos con notificaciones de Pub/Sub y BigQuery

En este documento, se explica cómo puedes supervisar los cambios de estado de trabajos y tareas mediante la configuración de notificaciones de Pub/Sub. Puedes usar las notificaciones para varios casos de uso. Por ejemplo, en este documento, se explica cómo transmitir las notificaciones a una tabla de BigQuery, que puedes usar para analizar los datos. Para obtener más información sobre los casos de uso de las notificaciones de Pub/Sub, consulta Elige un tipo de suscripción en la documentación de Pub/Sub.

Como alternativa, si deseas exportar toda la información sobre un trabajo a BigQuery, consulta Exporta información del trabajo en su lugar.

Antes de comenzar

  1. Si nunca usaste Batch, revisa Comienza a usar Batch y habilita Batch completando los requisitos previos para proyectos y usuarios.
  2. Si deseas configurar las notificaciones de Pub/Sub para tus trabajos de Batch, haz lo siguiente:

    1. Habilita la API de Pub/Sub.

      Roles necesarios para habilitar las APIs

      Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

      Habilitar la API

    2. Para obtener los permisos que necesitas para configurar un tema y una suscripción de Pub/Sub, pídele a tu administrador que te otorgue el rol de IAM de editor de Pub/Sub (roles/pubsub.editor) en un proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

      También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

  3. Los requisitos adicionales varían según el tipo de suscripción que decidas configurar. Por ejemplo, si deseas transmitir y analizar notificaciones a una tabla de BigQuery, debes hacer lo siguiente:

    1. Habilita la API de BigQuery.

      Roles necesarios para habilitar las APIs

      Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

      Habilitar la API

    2. Para garantizar que la cuenta de servicio de Pub/Sub tenga los permisos necesarios para transmitir notificaciones de Pub/Sub a BigQuery, pídele a tu administrador que le otorgue el rol de IAM de editor de datos de BigQuery (roles/bigquery.dataEditor) a la cuenta de servicio de Pub/Sub en el proyecto del tema de Pub/Sub.

      Para obtener más información sobre cómo asignar este rol, consulta Asigna roles de BigQuery a la cuenta de servicio de Pub/Sub.

    3. Asegúrate de que todos los usuarios que desees que analicen las notificaciones en BigQuery tengan los permisos necesarios.

      Para obtener los permisos que necesitas para consultar las notificaciones de Pub/Sub en BigQuery, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Configura las notificaciones de Pub/Sub para Batch

Batch admite notificaciones de Pub/Sub para los cambios en los estados de trabajos y tareas, que puedes usar para alertas, observabilidad o análisis.

Para configurar las notificaciones de Pub/Sub para uno o más trabajos de Batch, completa los pasos que se describen en las siguientes secciones:

  1. Crea o identifica un tema de Pub/Sub para tus trabajos de Batch.
  2. Crea al menos una suscripción para tu tema para recibir y usar sus notificaciones.
  3. Configura trabajos para enviar notificaciones a tu tema.

Después de configurar las notificaciones de Pub/Sub para Batch, puedes configurar cada trabajo para que envíe notificaciones específicas. Puedes recibir notificaciones cada vez que cambien los estados de trabajos o tareas, o puedes filtrar las notificaciones para estados específicos de trabajos o tareas. En particular, Pub/Sub no envía notificaciones para el primer estado en el que ingresa un trabajo o una tarea. Pub/Sub solo envía notificaciones cuando un trabajo pasa de un estado a otro.

Para obtener más información sobre los atributos que puedes configurar para las notificaciones de Pub/Sub, consulta Crea y ejecuta un trabajo que envía notificaciones de estado de Pub/Sub.

Crea o identifica un tema de Pub/Sub para Batch

Crea un tema nuevo de Pub/Sub o identifica un tema de Pub/Sub existente que deseas usar para las notificaciones de Batch.

Como se explica más adelante en este documento, los trabajos no pueden enviar notificaciones a este tema de Pub/Sub hasta que tu administrador otorgue permisos adicionales que lo permitan.

Crea una suscripción para recibir y usar las notificaciones

Para recibir y usar los mensajes publicados en un tema de Pub/Sub, debes crear al menos una suscripción a ese tema.

Por ejemplo, una opción es configurar tu tema para transmitir sus notificaciones a BigQuery. Luego, cuando ejecutes trabajos que publiquen notificaciones, podrás recibir y analizar las notificaciones en una tabla de BigQuery. Para obtener más información, consulta Ejemplo: Recibe y usa notificaciones de Pub/Sub en BigQuery en este documento.

De lo contrario, para obtener más información sobre las suscripciones y otras opciones de suscripción, consulta Descripción general de las suscripciones en la documentación de Pub/Sub.

Configura trabajos para enviar notificaciones a tu tema

Para configurar trabajos que envíen notificaciones de Pub/Sub a tu tema, sigue las instrucciones de la página Crea y ejecuta un trabajo que envía notificaciones de estado de Pub/Sub. En particular, haz lo siguiente:

  1. Si aún no lo hiciste, pídele a tu administrador que otorgue todos los permisos necesarios para que los trabajos envíen notificaciones a tu tema de Pub/Sub. Estos permisos se enumeran en la sección Roles necesarios de esa página.
  2. Crea y ejecuta un trabajo que habilite las notificaciones de Pub/Sub definiendo el campo notifications del trabajo.

Ejemplo: Recibe y usa notificaciones de Pub/Sub en BigQuery

En las siguientes secciones, se explica un caso de uso de ejemplo para recibir y usar notificaciones de Pub/Sub en BigQuery. Si configuras una suscripción que transmite las notificaciones de Pub/Sub de tu tema a una tabla de BigQuery, puedes conservar el historial de los cambios de estado de trabajos y tareas, y consultar esos cambios.

Configura una suscripción que transmita notificaciones a BigQuery

Para configurar una suscripción de Pub/Sub que transmita notificaciones de un tema a una tabla de BigQuery, haz lo siguiente:

  1. Si aún no lo hiciste, crea o identifica un tema de Pub/Sub para Batch.

  2. Si aún no tienes uno, crea un conjunto de datos de BigQuery.

  3. Crea una tabla de BigQuery con la siguiente definición de esquema:

    [
  {
    "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. Crea una suscripción de Pub/Sub que transmita a BigQuery y especifica las siguientes opciones:

    • Tema: Selecciona el tema de Pub/Sub para Batch.
    • Proyecto: Selecciona el proyecto que contiene tu tabla de BigQuery.
    • Conjunto de datos: Selecciona el conjunto de datos que contiene tu tabla de BigQuery.
    • Tabla: Selecciona la tabla que creaste en el paso anterior.
    • Selecciona Usar el esquema de tema.
    • Selecciona Escribir metadatos.

Ahora, cada vez que se envíe una notificación de Pub/Sub a ese tema, Pub/Sub transmitirá esa notificación a la tabla de BigQuery. Después de configurar los trabajos para enviar notificaciones de Pub/Sub, puedes analizar las notificaciones en BigQuery.

Analiza las notificaciones en BigQuery

Puedes analizar las notificaciones en BigQuery después de configurar una suscripción a una tabla de BigQuery para tu tema y ejecutar trabajos que envíen notificaciones a tu tema. Para analizar las notificaciones en BigQuery, ejecuta una consulta en la attributes columna de la tabla de BigQuery. Los atributos que puedes consultar dependen de si configuraste notificaciones para tareas o trabajos.

Puedes consultar los siguientes atributos de las notificaciones de tareas:

  • JobUID
  • NewTaskState
  • Region
  • TaskName
  • TaskUID
  • Type

Puedes consultar los siguientes atributos de las notificaciones de trabajos:

  • JobUID
  • JobName
  • NewJobState
  • Region
  • Type

Por ejemplo, la siguiente consulta muestra el JobUID asociado con cada notificación:

select attributes.JobUID from `example-table`

¿Qué sigue?