Surveiller l'état des tâches à l'aide de notifications Pub/Sub et de BigQuery

Ce document explique comment surveiller les changements d'état des tâches et des jobs en configurant des notifications Pub/Sub. Vous pouvez utiliser les notifications pour différents cas d'utilisation. Par exemple, ce document explique comment diffuser les notifications dans une table BigQuery, que vous pouvez utiliser pour analyser les données. Pour en savoir plus sur les cas d'utilisation des notifications Pub/Sub, consultez la section Choisir un type d'abonnement dans la documentation Pub/Sub.

Si vous souhaitez exporter toutes les informations sur un job vers BigQuery, consultez plutôt la section Exporter des informations sur un job.

Avant de commencer

  1. Si vous n'avez jamais utilisé Batch, consultez la section Premiers pas avec Batch et activez Batch en remplissant les conditions préalables pour les projets et les utilisateurs.
  2. Si vous souhaitez configurer des notifications Pub/Sub pour vos jobs Batch, procédez comme suit :

    1. Activez l'API Pub/Sub.

      Rôles requis pour activer les API

      Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

      Activer l'API

    2. Pour obtenir les autorisations nécessaires pour configurer un sujet et un abonnement Pub/Sub, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Pub/Sub (roles/pubsub.editor) sur un projet. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer l'accès aux projets, aux dossiers et aux organisations.

      Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

  3. Les exigences supplémentaires varient en fonction du type d'abonnement que vous décidez de configurer. Par exemple, si vous souhaitez diffuser et analyser des notifications dans une table BigQuery, vous devez procéder comme suit :

    1. Activez l'API BigQuery.

      Rôles requis pour activer les API

      Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

      Activer l'API

    2. Pour vous assurer que le compte de service Pub/Sub dispose des autorisations nécessaires pour diffuser des notifications Pub/Sub vers BigQuery, demandez à votre administrateur d'accorder le rôle IAM Éditeur de données BigQuery (roles/bigquery.dataEditor) au compte de service Pub/Sub sur le projet du sujet Pub/Sub.

      Pour en savoir plus sur l'attribution de ce rôle, consultez la section Attribuer des rôles BigQuery au compte de service Pub/Sub.

    3. Assurez-vous que tous les utilisateurs qui souhaitent analyser les notifications dans BigQuery disposent des autorisations requises.

      Pour obtenir les autorisations nécessaires pour interroger les notifications Pub/Sub dans BigQuery, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Configurer des notifications Pub/Sub pour Batch

Batch est compatible avec les notifications Pub/Sub pour les modifications apportées aux états des tâches et des jobs, que vous pouvez utiliser pour les alertes, l'observabilité ou l'analyse.

Pour configurer des notifications Pub/Sub pour un ou plusieurs jobs Batch, suivez les étapes décrites dans les sections suivantes :

  1. Créez ou identifiez un sujet Pub/Sub pour vos jobs Batch.
  2. Créez au moins un abonnement pour votre sujet afin de recevoir et d'utiliser ses notifications.
  3. Configurez les jobs pour qu'ils envoient des notifications à votre sujet.

Une fois que vous avez configuré les notifications Pub/Sub pour Batch, vous pouvez éventuellement configurer chaque job pour qu'il envoie des notifications spécifiques. Vous pouvez recevoir des notifications chaque fois que l'état d'un job ou d'une tâche change, ou vous pouvez filtrer les notifications pour des états de job ou de tâche spécifiques. Notez que Pub/Sub n'envoie pas de notifications pour le premier état dans lequel un job ou une tâche entre. Pub/Sub n'envoie des notifications que lorsqu'un job passe d'un état à un autre.

Pour en savoir plus sur les attributs que vous pouvez configurer pour les notifications Pub/Sub, consultez la section Créer et exécuter un job qui envoie des notifications d'état Pub/Sub.

Créer ou identifier un sujet Pub/Sub pour Batch

Créez un sujet Pub/Sub ou identifiez un sujet Pub/Sub existant que vous souhaitez utiliser pour les notifications Batch.

Comme expliqué plus loin dans ce document, les jobs ne peuvent pas envoyer de notifications à ce sujet Pub/Sub tant que votre administrateur n'a pas accordé d'autorisations supplémentaires pour l'autoriser.

Créer un abonnement pour recevoir et utiliser les notifications

Pour recevoir et utiliser les messages publiés dans un sujet Pub/Sub, vous devez créer au moins un abonnement à ce sujet.

Par exemple, vous pouvez configurer votre sujet pour diffuser ses notifications vers BigQuery. Ensuite, lorsque vous exécutez des jobs qui publient des notifications, vous pouvez recevoir et analyser les notifications dans une table BigQuery. Pour en savoir plus, consultez la section Exemple : Recevoir et utiliser des notifications Pub/Sub dans BigQuery dans ce document.

Sinon, pour en savoir plus sur les abonnements et les autres options d'abonnement, consultez la section Présentation des abonnements dans la documentation Pub/Sub.

Configurer les jobs pour qu'ils envoient des notifications à votre sujet

Pour configurer des jobs qui envoient des notifications Pub/Sub à votre sujet, suivez les instructions de la page Créer et exécuter un job qui envoie des notifications d'état Pub/Sub. Plus précisément, procédez comme suit :

  1. Si vous ne l'avez pas déjà fait, demandez à votre administrateur d'accorder toutes les autorisations requises pour que les jobs puissent envoyer des notifications à votre sujet Pub/Sub. Ces autorisations sont listées dans la section Rôles requis de cette page.
  2. Créez et exécutez un job qui active les notifications Pub/Sub en définissant le champ notifications du job.

Exemple : Recevoir et utiliser des notifications Pub/Sub dans BigQuery

Les sections suivantes présentent un exemple de cas d'utilisation pour recevoir et utiliser des notifications Pub/Sub dans BigQuery. En configurant un abonnement qui diffuse les notifications Pub/Sub de votre sujet dans une table BigQuery, vous pouvez conserver l'historique des changements d'état des tâches et des jobs, et interroger ces changements.

Configurer un abonnement qui diffuse des notifications vers BigQuery

Configurez un abonnement Pub/Sub qui diffuse les notifications d'un sujet vers une table BigQuery en procédant comme suit :

  1. Si vous ne l'avez pas déjà fait, créez ou identifiez un sujet Pub/Sub pour Batch.

  2. Si vous n'en avez pas déjà un, créez un ensemble de données BigQuery.

  3. Créez une table BigQuery avec la définition de schéma suivante :

    [
  {
    "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. Créez un abonnement Pub/Sub qui diffuse des données vers BigQuery et spécifiez les options suivantes :

    • Sujet : sélectionnez le sujet Pub/Sub pour Batch.
    • Projet : sélectionnez le projet qui contient votre table BigQuery.
    • Ensemble de données : sélectionnez l'ensemble de données qui contient votre table BigQuery.
    • Table : sélectionnez la table que vous avez créée à l'étape précédente.
    • Sélectionnez Utiliser un schéma avec sujet.
    • Sélectionnez Écrire des métadonnées.

Désormais, chaque fois qu'une notification Pub/Sub est envoyée à ce sujet, Pub/Sub la diffuse dans la table BigQuery. Une fois que vous avez configuré les jobs pour qu'ils envoient des notifications Pub/Sub, vous pouvez analyser les notifications dans BigQuery.

Analyser les notifications dans BigQuery

Vous pouvez analyser les notifications dans BigQuery après avoir configuré un abonnement à une table BigQuery pour votre sujet et exécuté des jobs qui envoient des notifications à votre sujet. Pour analyser les notifications dans BigQuery, exécutez une requête sur la colonne attributes de la table BigQuery. Les attributs que vous pouvez interroger dépendent du fait que vous ayez configuré des notifications pour des tâches ou des jobs.

Vous pouvez interroger les attributs suivants des notifications de tâche :

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

Vous pouvez interroger les attributs suivants des notifications de job :

  • JobUID
  • JobName
  • NewJobState
  • Region
  • Type

Par exemple, la requête suivante affiche le JobUID associé à chaque notification :

select attributes.JobUID from `example-table`

Étape suivante