Configura le notifiche di BigQuery

Cloud Build può inviarti notifiche sugli aggiornamenti delle build inviando notifiche ai canali desiderati, ad esempio Slack o al server SMTP. In questa pagina viene spiegato come configurare le notifiche utilizzando il strumento di notifica BigQuery.

Il notifier di BigQuery ti consente di specificare i filtri in base alle build da archiviare nel database. Ad esempio, puoi raggruppare le build per ID trigger, tag o valori di sostituzione. Inoltre, il notificatore BigQuery scrive i dati in BigQuery in un formato standardizzato che include campi calcolati non immediatamente accessibili dall'oggetto Build, come le dimensioni dell'immagine o la durata dell'esecuzione. Per informazioni su come esportare le voci di log in BigQuery o in un'altra destinazione, vedi Esportazione dei log con la console Google Cloud.

Prima di iniziare

Abilita le API Cloud Build, Cloud Run, Pub/Sub, and BigQuery.
Abilita le API

Installa Google Cloud CLI.

Configurazione delle notifiche di BigQuery

La seguente sezione spiega come configurare manualmente le notifiche HTTP utilizzando il notifier BigQuery. Se invece vuoi automatizzare la configurazione, vedi Automazione della configurazione per le notifiche.

Per configurare le notifiche di BigQuery:

Concedi al tuo account di servizio Cloud Run l'autorizzazione per creare e scrivere tabelle BigQuery, recuperare i dati Artifact Registry relativi alla tua build e accedere in lettura e scrittura ai bucket Cloud Storage:
1. Vai alla pagina IAM nella console Google Cloud:
  
  Apri la pagina IAM
2. Individua l'account di servizio predefinito di Compute Engine associato al progetto:
  
  Il tuo account di servizio predefinito di Compute Engine sarà simile al seguente:
```
project-number-compute@developer.gserviceaccount.com
```
3. Fai clic sull'icona a forma di matita nella riga contenente l'account di servizio predefinito di Compute Engine. Visualizzerai la scheda Modifica accesso.
4. Fai clic su Aggiungi un altro ruolo.
5. Aggiungi i seguenti ruoli:
  - Lettore Artifact Registry
  - Editor dati BigQuery
  - Visualizzatore oggetti Storage
  Il ruolo Lettore Artifact Registry consente di recuperare i dati per le immagini. L'editor dati di BigQuery consente l'accesso in lettura e scrittura ai dati. Il visualizzatore oggetti Storage fornisce accesso in lettura agli oggetti Cloud Storage.
  
  Nota: se vuoi concedere autorizzazioni a livello di bucket anziché a livello di progetto, aggiungi il ruolo Proprietario oggetti legacy Storage al bucket quando ne crei uno. Per saperne di più, vedi Confronto tra ruoli a livello di progetto e ruoli a livello di bucket.
6. Fai clic su Salva.
Scrivi un file di configurazione del notificante per configurare il notificatore BigQuery e filtrare gli eventi di build:

Nel seguente esempio di file di configurazione dell'avviso, il campo filter utilizza il Common Expression Language con la variabile build per filtrare gli eventi di build con un ID trigger specificato:
```
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
```
Dove:
- buildStatus è un parametro definito dall'utente. Questo parametro assume il valore di ${build.status}, lo stato della build.
- project-id è l'ID del tuo progetto Google Cloud.
- dataset-name è il nome che vuoi assegnare al tuo set di dati.
- table-name è il nome che vuoi assegnare alla tua tabella.
- Il campo uri fa riferimento al file bq.json. Questo file fa riferimento a un modello JSON ospitato su Cloud Storage e rappresenta le informazioni da inserire nella tabella BigQuery.
  
  Sperimentale - Customizing notifications using templates
  
  Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.
Per visualizzare un esempio di file di modello, vedi il file bq.json nel repository cloud-build-notifiers-repository.

Il table-name nel file di configurazione del notificante può fare riferimento a:
- una tabella inesistente
- una tabella vuota senza uno schema
- una tabella esistente con uno schema corrispondente alle specifiche dello schema nello strumento di notifica BigQuery
  
  Nota: i riferimenti a una tabella esistente con una specifica dello schema non corrispondente al notificatore BigQuery genereranno un errore.
Ti consigliamo di specificare l'ID trigger di build come filtro poiché specificare l'ID trigger di build ti consente di correlare i dati di build per i tuoi trigger. Puoi anche specificare più ID attivatore in un elenco: build.build_trigger_id in ["example-id-123", "example-id-456"].

Per ottenere l'ID trigger, esegui questo comando, dove trigger-name è il nome del trigger:

I trigger di build gcloud descrivono trigger-name

Il comando elenca i campi associati al trigger, incluso l'ID trigger.

Nota: i dati vengono archiviati solo per gli eventi di build con uno stato di terminale come SUCCESS o FAILURE.

Per visualizzare l'esempio, vedi il file di configurazione del generatore di notifiche per BigQuery.

Per i campi aggiuntivi in base ai quali puoi filtrare, consulta la risorsa Crea. Per ulteriori esempi di filtro, consulta la sezione Utilizzare CEL per filtrare gli eventi di build.
Carica il file di configurazione del notificante in un bucket Cloud Storage:
1. Se non hai un bucket Cloud Storage, esegui questo comando per creare un bucket, dove bucket-name è il nome che vuoi assegnare al bucket, soggetto ai requisiti di denominazione.
```
gsutil mb gs://bucket-name/
```
2. Carica il file di configurazione del notificatore nel bucket:
```
gsutil cp config-file-name gs://bucket-name/config-file-name
```
  Dove:
  - bucket-name è il nome del bucket.
  - config-file-name è il nome del file di configurazione delle notifiche.
Esegui il deployment del notificante in 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
```
Dove:
- service-name è il nome del servizio Cloud Run in cui esegui il deployment dell'immagine.
  
  Nota: service-name fa riferimento al nuovo servizio di notifica che stai creando.
- config-path è il percorso del file di configurazione per il notificatore BigQuery, gs://bucket-name/config-file-name.
- project-id è l'ID del tuo progetto Google Cloud.
Il comando gcloud run deploy esegue il pull dell'ultima versione dell'immagine creata da Artifact Registry. Cloud Build supporta le immagini di notifica per nove mesi. Dopo nove mesi, Cloud Build elimina la versione dell'immagine. Se vuoi utilizzare una versione immagine precedente, devi specificare la versione semantica completa del tag immagine nell'attributo image del comando gcloud run deploy. Le versioni e i tag precedenti delle immagini sono disponibili in Artifact Registry.

Nota: durante l'esecuzione di questo comando, ti potrebbe essere richiesto di specificare argomenti aggiuntivi come --region o --platform. Per saperne di più sui parametri che puoi passare al comando gcloud run deploy, consulta la pagina relativa al deployment in Cloud Run. Se non riesci a eseguire il deployment del notificante utilizzando questo comando, consulta la guida alla risoluzione dei problemi di Cloud Run per trovare soluzioni su come risolvere gli errori di deployment.
Concedi le autorizzazioni Pub/Sub per creare token di autenticazione nel tuo progetto:
```
 gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
```
Dove:
- project-id è l'ID del tuo progetto Google Cloud.
- project-number è il numero del tuo progetto Google Cloud.
Nota: se l'account di servizio Pub/Sub non esiste nel progetto, vedi Creare e utilizzare le sottoscrizioni.
Crea un account di servizio per rappresentare l'identità della sottoscrizione Pub/Sub:
```
gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"
```
Puoi utilizzare cloud-run-pubsub-invoker o un nome univoco all'interno del tuo progetto Google Cloud.
Concedi all'account di servizio cloud-run-pubsub-invoker l'autorizzazione Invoker di Cloud Run:
```
gcloud run services add-iam-policy-binding service-name \
   --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
   --role=roles/run.invoker
```
Dove:
- service-name è il nome del servizio Cloud Run in cui esegui il deployment dell'immagine.
- project-id è l'ID del tuo progetto Google Cloud.
Crea l'argomento cloud-builds per ricevere messaggi di aggiornamento della build per l'autore delle notifiche:
```
gcloud pubsub topics create cloud-builds
```
Crea un sottoscrittore push Pub/Sub per l'autore delle notifiche:
```
 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
```
Dove:
- subscriber-id è il nome che vuoi assegnare al tuo abbonamento.
- service-url è l'URL generato da Cloud Run per il tuo nuovo servizio.
- project-id è l'ID del tuo progetto Google Cloud.

Le notifiche per il tuo progetto Cloud Build sono state configurate.

La prossima volta che richiami una build, la tabella verrà aggiornata con i dati più recenti che corrispondono al filtro configurato per il notificatore BigQuery.

Visualizzazione dei dati della build

Per visualizzare i dati della build in BigQuery:

Apri la pagina della console BigQuery:

Apri la pagina di BigQuery
In Risorse, fai clic sull'ID progetto che utilizzi per configurare il notificatore BigQuery.
Fai clic sul nome del set di dati.
Fai clic sul nome della tabella.

Ora puoi visualizzare informazioni relative alla tabella, tra cui lo schema, e un'anteprima dei dati della build come elencato nella tabella.

Accesso ai dati della build

Puoi eseguire query sui dati della tua tabella utilizzando lo strumento a riga di comando bq o la console BigQuery.

CLI

Per eseguire query sui dati della tabella utilizzando lo strumento a riga di comando bq, esegui questo comando nel terminale, dove sql-query è la query:

bq query sql-query

Se prevedi di utilizzare gli esempi di query in questa pagina, assicurati di specificare il flag --nouse_legacy_sql nel comando. Lo strumento a riga di comando bq utilizza l'SQL precedente, a differenza delle query di esempio. Esegui questo comando nel terminale per eseguire query sui dati senza SQL precedente:

bq query sql-query --nouse_legacy_sql

Console

Per eseguire query sui dati della tabella utilizzando la console BigQuery:

Apri la pagina della console BigQuery:

Apri la pagina di BigQuery
In Risorse, fai clic sul nome della tabella su cui vuoi eseguire una query.
Scrivi la query SQL nell'Editor query.

Utilizzo delle query per accedere ai dati della build

Le query di esempio seguenti mostrano come accedere ai dati della build per l'evento di build, secondo la configurazione del notificatore BigQuery:

Cronologia generale delle build

SELECT * FROM `projectID.datasetName.tableName`

Conteggi delle build raggruppati per stato

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

Frequenza di deployment giornaliera per la settimana corrente

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

Per visualizzare altri esempi di query, consulta il file README di Cloud Build BigQuery Notification nel repository cloud-build-notifiers su GitHub. Per scoprire di più su come eseguire query sui dati utilizzando BigQuery, vedi Esecuzione di query e visualizzazione dei dati.

Utilizzo di CEL per filtrare gli eventi di build

Cloud Build utilizza CEL con la variabile build nei campi elencati nella risorsa Build per accedere ai campi associati al tuo evento di build, come l'ID trigger, l'elenco di immagini o i valori di sostituzione. Puoi utilizzare la stringa filter per filtrare gli eventi di build nel file di configurazione della build utilizzando qualsiasi campo elencato nella risorsa Crea. Per trovare l'esatta sintassi associata al campo, consulta il file cloudbuild.proto.

Filtro per ID attivatore

Per filtrare in base all'ID attivatore, specifica il valore dell'ID attivatore nel campo filter utilizzando build.build_trigger_id, dove trigger-id è l'ID attivatore come stringa:

filter: build.build_trigger_id == trigger-id

Filtro per stato

Per filtrare in base allo stato, specifica lo stato della build in base a cui vuoi applicare il filtro nel campo filter utilizzando build.status.

L'esempio seguente mostra come filtrare gli eventi di build con uno stato SUCCESS utilizzando il campo filter:

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

Puoi anche filtrare le build con stati diversi. L'esempio seguente mostra come filtrare gli eventi di build con stato SUCCESS, FAILURE o TIMEOUT utilizzando il campo filter:

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

Per visualizzare i valori di stato aggiuntivi in base ai quali puoi filtrare, consulta Stato nel riferimento della risorsa build.

Filtro per tag

Per filtrare in base al tag, specifica il valore del tag nel campo filter utilizzando build.tags, dove tag-name è il nome del tag:

filter: tag-name in build.tags

Puoi filtrare in base al numero di tag specificato nell'evento di build utilizzando size. Nell'esempio seguente, il campo filter filtra gli eventi di build che hanno esattamente due tag specificati con un tag specificato come v1:

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

Filtro per immagini

Per filtrare in base alle immagini, specifica il valore dell'immagine nel campo filter utilizzando build.images, dove image-name è il nome completo dell'immagine elencato in Artifact Registry, ad esempio us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Nell'esempio seguente, filter filtra in base agli eventi di build che hanno us-east1-docker.pkg.dev/my-project/docker-repo/image-one o us-east1-docker.pkg.dev/my-project/docker-repo/image-two specificati come nomi di immagini:

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

Filtro per data/ora

Puoi filtrare gli eventi build in base all'ora di creazione, all'ora di inizio o di fine di una build specificando una delle seguenti opzioni nel campo filter: build.create_time, build.start_time o build.finish_time.

Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con l'ora della richiesta per creare la build il 20 luglio 2020 alle 06:00:

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

Puoi anche filtrare in base agli eventi di build in base ai confronti temporali. Nell'esempio seguente, il campo filter utilizza timestamp per filtrare gli eventi di build con un'ora di inizio compresa tra il 20 luglio 2020 alle 06:00 e il 30 luglio 2020 alle 06:00.

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

Per scoprire di più su come i fusi orari sono espressi in CEL, consulta la definizione della lingua per i fusi orari.

Per filtrare in base alla durata di una build, puoi utilizzare duration per confrontare i timestamp. Nell'esempio seguente, il campo filter utilizza duration per filtrare gli eventi di build con una build eseguita per almeno cinque minuti:

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

Filtro per sostituzione

Puoi filtrare in base alla sostituzione specificando la variabile di sostituzione nel campo filter utilizzando build.substitutions. Nell'esempio seguente, il campo filter elenca le build che contengono la variabile di sostituzione substitution-variable e verifica se substitution-variable corrisponde al substitution-value specificato:

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

Dove:

substitution-variable è il nome della variabile di sostituzione.
substitution-value è il nome del valore di sostituzione.

Puoi anche filtrare in base ai valori predefiniti della variabile di sostituzione. Nell'esempio seguente, il campo filter elenca le build che hanno il nome del ramo master e quelle che hanno il nome repository github.com/user/my-example-repo. Le variabili di sostituzione predefinite BRANCH_NAME e REPO_NAME vengono passate come chiavi al build.substitutions:

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

Se vuoi filtrare in base alle stringhe utilizzando espressioni regolari, puoi utilizzare la funzione matches integrata. Nell'esempio riportato di seguito, il campo filter filtra le build con stato ERRORE o TIMEOUT e che hanno anche una variabile di sostituzione della build TAG_NAME con un valore corrispondente all'espressione regolare 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}$")`

Per visualizzare un elenco dei valori di sostituzione predefiniti, consulta la sezione Utilizzare le sostituzioni predefinite.

Passaggi successivi

Scopri di più sui notifiche di Cloud Build.
Scopri come iscriverti per ricevere notifiche sulle build.
Scopri come scrivere un file di configurazione di compilazione di Cloud Build.