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 los trabajos y las tareas configurando 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.

Antes de comenzar

  1. Si nunca usaste Batch, revisa Cómo comenzar 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 por lotes, haz lo siguiente:

    1. Habilita la API de Pub/Sub si aún no está habilitada.

      Roles necesarios para habilitar las APIs

      Para habilitar 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 más 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 a través de 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 en una tabla de BigQuery, debes hacer lo siguiente:

    1. Habilita la API de BigQuery si aún no está habilitada.

      Roles necesarios para habilitar las APIs

      Para habilitar 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 más 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 quieras 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 los trabajos y las tareas, que puedes usar para alertas, observabilidad o análisis.

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

  1. Crea o identifica un tema de Pub/Sub para tus trabajos por lotes.
  2. Crea al menos una suscripción para que tu tema reciba y use 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 de forma opcional. Puedes recibir notificaciones cada vez que cambien los estados de los trabajos o las tareas, o bien puedes filtrar las notificaciones para que solo se muestren los estados de trabajos o tareas específicos. En particular, Pub/Sub no envía notificaciones sobre el primer estado en el que ingresa un trabajo o una tarea; 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íe 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 existente de Pub/Sub que quieras usar para las notificaciones por lotes.

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 que transmita 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 el ejemplo para recibir y usar 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íe notificaciones de estado de Pub/Sub. Específicamente, 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 obligatorios 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 ejemplo de caso de uso para recibir y usar notificaciones de Pub/Sub en BigQuery. Si configuras una suscripción que transmita las notificaciones de Pub/Sub de tu tema a una tabla de BigQuery, podrás conservar el historial de los cambios de estado de los trabajos y las tareas, y consultar esos cambios.

Configura una suscripción que transmita notificaciones a BigQuery

Para configurar una suscripción a Pub/Sub que transmita notificaciones desde 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 a Pub/Sub que transmita datos 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 que envíen 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 columna attributes 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 trabajo:

  • JobUID
  • JobName
  • NewJobState
  • Region
  • Type

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

select attributes.JobUID from `example-table`

¿Qué sigue?