Configurer les notifications BigQuery

Cloud Build peut vous informer des mises à jour de votre compilation en vous envoyant des notifications aux canaux souhaités, tels que Slack ou votre serveur SMTP. Cette page explique comment configurer les notifications à l'aide du système d'alerte BigQuery.

Le système d'alerte BigQuery vous permet de spécifier des filtres sur les compilations que vous souhaitez stocker dans votre base de données. Par exemple, vous pouvez regrouper les compilations par ID de déclencheur, par tag ou suivant des valeurs de substitution. Le système d'alerte BigQuery écrit également les données dans BigQuery dans un format standardisé, incluant des champs calculés qui ne sont pas immédiatement accessibles sur l'objet Build, comme la taille de l'image ou la durée d'exécution. Si vous souhaitez savoir comment exporter des entrées de journal vers BigQuery ou une autre destination, consultez la page Exporter des journaux avec la console Google Cloud.

Avant de commencer

Activer les API Cloud Build, Cloud Run, Pub/Sub, and BigQuery.
Activer les API

Installez Google Cloud CLI.

Configurer des notifications BigQuery

La section suivante explique comment configurer manuellement les notifications HTTP à l'aide du système d'alerte BigQuery. Si vous préférez automatiser la configuration, consultez la page Automatiser la configuration des notifications.

Pour configurer les notifications BigQuery, procédez comme suit :

Autorisez votre compte de service Cloud Run à créer et à écrire des tables BigQuery. Accordez-lui également l'autorisation de récupérer les données Artifact Registry associées à votre compilation, et d'accéder en lecture et en écriture aux buckets Cloud Storage :
1. Accédez à la page "IAM" de la console Google Cloud :
  
  Ouvrir la page IAM
2. Recherchez le compte de service Compute Engine par défaut associé à votre projet :
  
  Votre compte de service Compute Engine par défaut ressemble à ceci :
```
project-number-compute@developer.gserviceaccount.com
```
3. Cliquez sur l'icône en forme de crayon sur la ligne contenant votre compte de service Compute Engine par défaut. L'onglet Modifier l'accès s'affiche.
4. Cliquez sur Ajouter un autre rôle.
5. Ajoutez les rôles suivants :
  - Lecteur Artifact Registry
  - Éditeur de données BigQuery
  - Lecteur des objets Storage
  Le rôle Lecteur Artifact Registry vous permet d'extraire des données pour vos images. L'éditeur de données BigQuery vous offre un accès en lecture et en écriture à vos données. Le lecteur des objets Storage vous donne un accès en lecture aux objets Cloud Storage.
  
  Remarque : Si vous souhaitez accorder des autorisations au niveau du bucket plutôt qu'au niveau du projet, ajoutez le rôle Propriétaire des anciens objets Storage au bucket lors de sa création. Pour en savoir plus, consultez la section Rôles au niveau du projet et rôles au niveau du bucket.
6. Cliquez sur Enregistrer.
Rédigez un fichier de configuration du système d'alerte pour configurer votre système d'alerte BigQuery et filtrer les événements de compilation :

Dans l'exemple de fichier de configuration du système d'alerte suivant, le champ filter utilise Common Expression Language avec la variable build pour filtrer les événements de compilation avec un ID de déclencheur spécifié :
```
apiVersion: cloud-build-notifiers/v1
kind: BigQueryNotifier
metadata:
  name: example-bigquery-notifier
spec:
  notification:
    filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000"
    params:
      buildStatus: $(build.status)
    delivery:
      table: projects/project-id/datasets/dataset-name/tables/table-name
    template:
      type: golang
      uri: gs://example-gcs-bucket/bq.json
```
Où :
- buildStatus est un paramètre défini par l'utilisateur. Ce paramètre prend la valeur de ${build.status}, l'état de la compilation.
- project-id est l'ID du projet Google Cloud.
- dataset-name est le nom que vous souhaitez donner à l'ensemble de données.
- table-name est le nom que vous souhaitez donner à la table.
- Le champ uri fait référence au fichier bq.json. Ce fichier fait référence à un modèle JSON hébergé sur Cloud Storage et représente les informations à insérer dans votre table BigQuery.
  
  Expérimental — Customizing notifications using templates
  
  Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.
Pour voir un exemple de fichier de modèle, consultez le fichier bq.json dans le dépôt cloud-build-notifiers-repository.

Le table-name du fichier de configuration de votre système d'alerte peut se référer à :
- une table inexistante ;
- une table vide sans schéma ;
- une table existante avec un schéma qui correspond aux spécifications de schéma du système d'alerte BigQuery.
  
  Remarque :Les références à une table existante dont la spécification de schéma ne correspond pas au système d'alerte BigQuery génèrent une erreur.
Nous vous recommandons de spécifier l'ID de déclencheur de compilation en tant que filtre, car l'ID du déclencheur de compilation vous permet de mettre en corrélation les données de compilation pour vos déclencheurs. Vous pouvez également spécifier plusieurs ID de déclencheur dans une liste : build.build_trigger_id in ["example-id-123", "example-id-456"].

Pour obtenir l'ID du déclencheur, exécutez la commande suivante, où trigger-name correspond au nom du déclencheur.

Les déclencheurs de compilation gcloud décrivent trigger-name

La commande répertorie les champs associés à votre déclencheur, y compris son ID.

Remarque :Les données ne sont stockées que pour les événements de compilation ayant un état final tel que SUCCESS ou FAILURE.

Pour afficher cet exemple, consultez le fichier de configuration du système d'alerte pour le système d'alerte BigQuery.

Pour en savoir plus sur les champs supplémentaires que vous pouvez filtrer, consultez la ressource Build. Pour obtenir d'autres exemples de filtrage, consultez la section Utiliser le CEL pour filtrer les événements de compilation.
Importez votre fichier de configuration du système d'alerte dans un bucket Cloud Storage :
1. Si vous n'avez pas de bucket Cloud Storage, exécutez la commande suivante pour créer un bucket, où bucket-name est le nom que vous souhaitez attribuer au bucket, sous réserve des règles de dénomination.
```
gsutil mb gs://bucket-name/
```
2. Importez le fichier de configuration du système d'alerte dans votre bucket :
```
gsutil cp config-file-name gs://bucket-name/config-file-name
```
  Où :
  - bucket-name est le nom du bucket.
  - config-file-name est le nom de votre fichier de configuration de système d'alerte.
Déployez votre système d'alerte dans Cloud Run :
```
 gcloud run deploy service-name \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/bigquery:latest \
   --no-allow-unauthenticated \
   --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
```
Où :
- service-name correspond au nom du service Cloud Run dans lequel vous déployez l'image.
  
  Remarque :service-name fait référence au nouveau service d'alerte que vous créez.
- config-path est le chemin d'accès au fichier de configuration de votre système d'alerte BigQuery, gs://bucket-name/config-file-name.
- project-id est l'ID du projet Google Cloud.
La commande gcloud run deploy extrait la dernière version de votre image compilée à partir d'Artifact Registry. Cloud Build est compatible avec les images de système d'alerte pendant neuf mois. Après neuf mois, Cloud Build supprime la version de l'image. Si vous souhaitez utiliser une version d'image antérieure, vous devez spécifier la version sémantique complète du tag d'image dans l'attribut image de votre commande gcloud run deploy. Vous pouvez trouver les versions et les tags d'image précédents dans Artifact Registry.

Remarque : Lorsque vous exécutez cette commande, vous pouvez être invité à spécifier des arguments supplémentaires tels que --region ou --platform. Pour en savoir plus sur les paramètres que vous pouvez transmettre à la commande gcloud run deploy, consultez la page Déployer dans Cloud Run. Si vous ne parvenez pas à déployer votre système d'alerte à l'aide de cette commande, consultez le guide de dépannage Cloud Run pour savoir comment résoudre les erreurs de déploiement.
Accordez des autorisations Pub/Sub pour créer des jetons d'authentification dans votre projet :
```
 gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
```
Où :
- project-id est l'ID du projet Google Cloud.
- project-number est le numéro de votre projet Google Cloud.
Remarque :Si le compte de service Pub/Sub n'existe pas dans votre projet, consultez la section Créer et utiliser des abonnements.
Créez un compte de service pour représenter l'identité de votre abonnement Pub/Sub :
```
gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"
```
Vous pouvez utiliser cloud-run-pubsub-invoker ou utiliser un nom unique dans votre projet Google Cloud.
Accordez au compte de service cloud-run-pubsub-invoker l'autorisation Cloud Run Invoker :
```
gcloud run services add-iam-policy-binding service-name \
   --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
   --role=roles/run.invoker
```
Où :
- service-name correspond au nom du service Cloud Run dans lequel vous déployez l'image.
- project-id est l'ID du projet Google Cloud.
Créez le sujet cloud-builds pour recevoir des messages de mise à jour de compilation pour votre système d'alerte :
```
gcloud pubsub topics create cloud-builds
```
Créez un abonné push Pub/Sub pour votre système d'alerte :
```
 gcloud pubsub subscriptions create subscriber-id \
   --topic=cloud-builds \
   --push-endpoint=service-url \
   --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
```
Où :
- subscriber-id est le nom que vous souhaitez donner à votre abonnement.
- service-url est l'URL générée par Cloud Run pour votre nouveau service.
- project-id est l'ID du projet Google Cloud.

Les notifications pour votre projet Cloud Build sont maintenant configurées.

La prochaine fois que vous invoquerez une compilation, votre table sera mise à jour avec les dernières données correspondant au filtre que vous avez configuré pour votre système d'alerte BigQuery.

Afficher les données de compilation

Pour afficher les données de compilation dans BigQuery, procédez comme suit :

Ouvrez la page de la console BigQuery :

Ouvrir la page BigQuery
Sous Ressources, cliquez sur l'ID du projet que vous utilisez pour configurer votre système d'alerte BigQuery.
Cliquez sur le nom de votre ensemble de données.
Cliquez sur le nom de votre table.

Vous pouvez maintenant afficher les informations sur votre table, y compris son schéma et un aperçu de vos données de compilation, comme indiqué dans la table.

Accéder aux données de compilation

Vous pouvez interroger les données de votre table à l'aide de l'outil de ligne de commande bq ou de la console BigQuery.

CLI

Pour interroger des données dans votre table à l'aide de l'outil de ligne de commande bq, exécutez la commande suivante dans votre terminal, où sql-query correspond à votre requête :

bq query sql-query

Si vous envisagez d'utiliser les exemples de requête sur cette page, veillez à spécifier l'option --nouse_legacy_sql dans votre commande. Contrairement aux exemples de requête, l'outil de ligne de commande bq utilise l'ancien SQL. Exécutez la commande suivante dans votre terminal pour interroger des données sans l'ancien SQL :

bq query sql-query --nouse_legacy_sql

Console

Pour interroger des données dans votre table à l'aide de la console BigQuery, procédez comme suit :

Ouvrez la page de la console BigQuery :

Ouvrir la page BigQuery
Sous Ressources, cliquez sur le nom de la table à interroger.
Écrivez votre requête SQL dans l'éditeur de requête.

Utiliser des requêtes pour accéder aux données de compilation

Les exemples de requêtes suivants montrent comment accéder aux données de compilation d'un événement de compilation, en suivant la configuration du système d'alerte BigQuery :

Historique de compilation général

SELECT * FROM `projectID.datasetName.tableName`

Nombre de compilations regroupées par état

SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS

Fréquence de déploiement quotidienne pour la semaine en cours

SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
      DATETIME_TRUNC(CreateTime, DAY) AS DAY,
      STATUS
      FROM `projectID.datasetName.tableName`
      WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY

Pour voir plus d'exemples de requêtes, consultez le fichier README du système d'alerte BigQuery Cloud Build dans le dépôt cloud-build-notifiers de GitHub. Pour en savoir plus sur l'interrogation de données à l'aide de BigQuery, consultez la section Interroger et afficher des données.

Utiliser le CEL pour filtrer les événements de compilation

Cloud Build utilise le CEL avec la variable, build, sur les champs répertoriés dans la ressource Compilation afin d'accéder aux champs associés à votre événement de compilation, tels que votre ID de déclencheur, votre liste d'images, ou vos valeurs de substitution. Vous pouvez utiliser la chaîne filter pour filtrer les événements de compilation dans votre fichier de configuration de compilation à l'aide de n'importe quel champ répertorié dans la ressource Compilation. Pour trouver la syntaxe exacte associée à votre champ, consultez le fichier cloudbuild.proto.

Filtrer par ID de déclencheur

Pour filtrer par ID de déclencheur, spécifiez la valeur de votre ID de déclencheur dans le champ filter à l'aide de build.build_trigger_id, où trigger-id est votre ID de déclencheur sous forme de chaîne :

filter: build.build_trigger_id == trigger-id

Filtrer par état

Pour filtrer par état, spécifiez l'état de la compilation que vous souhaitez filtrer dans le champ filter à l'aide de build.status.

L'exemple suivant montre comment filtrer les événements de compilation dotés de l'état SUCCESS à l'aide du champ filter :

filter: build.status == Build.Status.SUCCESS

Vous pouvez également filtrer les compilations présentant des états différents. L'exemple suivant montre comment filtrer les événements de compilation dont l'état est SUCCESS, FAILURE ou TIMEOUT à l'aide du champ filter :

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Pour afficher des valeurs d'état supplémentaires que vous pouvez filtrer, consultez la section État dans la documentation de référence sur les ressources de compilation.

Filtrer par tag

Pour filtrer par tag, spécifiez la valeur de votre tag dans le champ filter à l'aide de build.tags, où tag-name est le nom de votre tag :

filter: tag-name in build.tags

Vous pouvez appliquer un filtre en fonction du nombre de tags spécifiés dans votre événement de compilation à l'aide de size. Dans l'exemple suivant, le champ filter filtre les événements de compilation comportant exactement deux tags spécifiés, avec un tag spécifié en tant que v1 :

filter: size(build.tags) == 2 && "v1" in build.tags

Filtrer par images

Pour filtrer par images, spécifiez la valeur de votre image dans le champ filter à l'aide de build.images, où image-name correspond au nom complet de votre image, tel que répertorié dans Artifact Registry, par exemple us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Dans l'exemple suivant, filter filtre les événements de compilation dont les noms d'image sont us-east1-docker.pkg.dev/my-project/docker-repo/image-one ou us-east1-docker.pkg.dev/my-project/docker-repo/image-two:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images

Filtrer par date et heure

Vous pouvez filtrer les événements de compilation en fonction de la date et l'heure de création, de début ou de fin d'une compilation en spécifiant l'une des options suivantes dans votre champ filter : build.create_time, build.start_time ou build.finish_time

Dans l'exemple suivant, le champ filter utilise timestamp pour filtrer les événements de compilation dont la date et l'heure de requête pour créer la compilation sont fixées au 20 juillet 2020 à 6h00 :

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Vous pouvez également filtrer les événements de compilation par comparaisons horaires. Dans l'exemple suivant, le champ filter utilise timestamp pour filtrer les événements de compilation dont le début est compris entre le 20 juillet 2020 à 6h00 et le 30 juillet 2020 à 6h00.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Pour en savoir plus sur la façon dont les fuseaux horaires sont exprimés dans le CEL, consultez la définition de langage pour les fuseaux horaires.

Pour filtrer par durée de compilation, vous pouvez utiliser duration pour comparer les horodatages. Dans l'exemple suivant, le champ filter utilise duration pour filtrer les événements de compilation dont la compilation a duré au moins cinq minutes :

filter: build.finish_time - build.start_time >= duration("5m")

Filtrer par substitution

Vous pouvez filtrer par substitution en spécifiant la variable de substitution dans le champ filter à l'aide de build.substitutions. Dans l'exemple suivant, le champ filter répertorie les compilations contenant la variable de substitution substitution-variable et vérifie si substitution-variable correspond à l'élément substitution-value spécifié :

filter: build.substitutions[substitution-variable] == substitution-value

Où :

substitution-variable est le nom de votre variable de substitution.
substitution-value est le nom de votre valeur de substitution.

Vous pouvez également filtrer par valeur de variable de substitution par défaut. Dans l'exemple suivant, le champ filter répertorie les compilations portant le nom de branche master et les compilations portant le nom de dépôt github.com/user/my-example-repo. Les variables de substitution par défaut BRANCH_NAME et REPO_NAME sont transmises sous forme de clés à build.substitutions :

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Si vous souhaitez filtrer les chaînes à l'aide d'expressions régulières, vous pouvez utiliser la fonction matches intégrée. Dans l'exemple ci-dessous, le champ filter filtre les compilations dont l'état est FAILURE ou TIMEOUT, et qui disposent également d'une variable de substitution de compilation TAG_NAME avec une valeur correspondant à l'expression régulière v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

Pour afficher la liste des valeurs de substitution par défaut, consultez la section Utiliser des substitutions par défaut.

Étapes suivantes

Apprenez-en plus sur les systèmes d'alerte Cloud Build.
Découvrez comment vous abonner aux notifications de compilation.
Découvrez comment écrire un fichier de configuration de compilation Cloud Build.