Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare le notifiche di BigQuery

Cloud Build può inviarti notifiche sugli aggiornamenti delle build inviandoti notifiche ai canali che preferisci, ad esempio Slack o il tuo server SMTP. Questa pagina spiega come configurare le notifiche utilizzando il notificatore BigQuery.

Il notifier BigQuery fornisce funzionalità per specificare i filtri in base ai quali vuoi archiviare le build nel tuo database. Ad esempio, puoi raggruppare le build in base all'ID attivatore, ai tag o ai valori di sostituzione. Il notificatore BigQuery scrive inoltre i dati in BigQuery in un formato standardizzato che include i campi calcolati non immediatamente accessibili nell'oggetto Build, ad esempio le dimensioni delle immagini o la durata dell'esecuzione. Per scoprire come esportare le voci di log in BigQuery o in un'altra destinazione, consulta Esportare i log con la console Google Cloud.

Prima di iniziare

Enable the Cloud Build, Cloud Run, Pub/Sub, and BigQuery APIs.
Enable the APIs

Installa Google Cloud CLI.

Configurazione delle notifiche di BigQuery

La sezione seguente spiega come configurare manualmente le notifiche HTTP utilizzando il notificatore BigQuery. Se invece vuoi automatizzare la configurazione, consulta Automatizzare la configurazione per le notifiche.

Per configurare le notifiche di BigQuery:

Concedi all'account di servizio Cloud Run l'autorizzazione per creare e scrivere tabelle BigQuery, l'autorizzazione per recuperare i dati di Artifact Registry relativi alla tua compilazione e l'accesso 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 tuo progetto:
  
  Il tuo account di servizio predefinito Compute Engine sarà simile al seguente:
```
project-number-compute@developer.gserviceaccount.com
```
3. Fai clic sull'icona a forma di matita nella riga contenente il service account predefinito di Compute Engine. Viene visualizzata la scheda Accesso in modifica.
4. Fai clic su Aggiungi un altro ruolo.
5. Aggiungi i seguenti ruoli:
  - Artifact Registry Reader
  - BigQuery Data Editor
  - Visualizzatore oggetti Storage
  Il ruolo Lettore di Artifact Registry ti consente di recuperare i dati per le tue immagini. BigQuery Data Editor ti consente di accedere in lettura e scrittura ai tuoi dati. Storage Object Viewer ti consente di accedere in lettura agli oggetti Cloud Storage.
  
  Nota: se vuoi concedere le autorizzazioni a livello di bucket anziché a livello di progetto, aggiungi il ruolo Proprietario oggetti legacy archiviazione al bucket quando lo crei. Per saperne di più, consulta Ruoli a livello di progetto e ruoli a livello di bucket.
6. Fai clic su Salva.
Scrivi un file di configurazione del notifier per configurare il notifier BigQuery e filtrare in base agli eventi di compilazione:

Nel seguente esempio di file di configurazione del notifier, il campo filter utilizza il Common Expression Language con la variabile build per filtrare gli eventi di compilazione con un ID attivatore 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 compilazione.
- project-id è l'ID del tuo progetto Google Cloud .
- dataset-name è il nome che vuoi assegnare al set di dati.
- table-name è il nome che vuoi assegnare alla 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 modello, consulta il file bq.json nel repository cloud-build-notifiers.

Il valore table-name nel file di configurazione del notifier può fare riferimento a:
- una tabella inesistente
- una tabella vuota senza uno schema
- una tabella esistente con uno schema che corrisponde alle specifiche dello schema nel notifier BigQuery
  
  Nota: i riferimenti a una tabella esistente con una specifica dello schema non corrispondente al notifier BigQuery causeranno un errore.
Ti consigliamo di specificare l'ID attivatore della compilazione come filtro, poiché consente di correlare i dati di compilazione per gli attivatori. 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 il seguente comando, dove trigger-name è il nome dell'attivatore:

gcloud builds triggers describe trigger-name

Il comando elencherà i campi associati all'attivatore, incluso l'ID attivatore.

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

Per visualizzare l'esempio, consulta il file di configurazione del notifier per il notifier BigQuery.

Per altri campi in base ai quali puoi filtrare, consulta la risorsa Build. Per altri esempi di filtri, consulta Utilizzo di CEL per filtrare gli eventi di build.
Carica il file di configurazione del notifier in un bucket Cloud Storage:
1. Se non hai un bucket Cloud Storage, esegui il seguente comando per crearne uno, dove bucket-name è il nome che vuoi assegnare al bucket, rispettando i requisiti di denominazione.
```
gcloud storage buckets create gs://bucket-name/
```
2. Carica il file di configurazione del notifier nel bucket:
```
gcloud storage 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 del notifier.
Esegui il deployment del notifier 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 stai eseguendo 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 del notifier BigQuery, gs://bucket-name/config-file-name.
- project-id è l'ID del tuo progetto Google Cloud .
Il comando gcloud run deploy estrae l'ultima versione dell'immagine compilata da Artifact Registry. Cloud Build supporta le immagini di avviso per nove mesi. Dopo nove mesi, Cloud Build elimina la versione dell'immagine. Se vuoi utilizzare una versione dell'immagine precedente, devi specificare la versione semantica completa del tag immagine nell'attributo image del comando gcloud run deploy. Le versioni e i tag delle immagini precedenti sono disponibili in Artifact Registry.

Nota: durante l'esecuzione di questo comando, è possibile che ti venga chiesto di specificare argomenti aggiuntivi come --region o --platform. Per scoprire di più sui parametri che puoi passare al comando gcloud run deploy, consulta Eseguire il deployment in Cloud Run. Se non riesci a eseguire il deployment del notifier 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 tuo progetto, consulta Creare e utilizzare le sottoscrizioni.
Crea un account di servizio per rappresentare l'identità della tua 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 stai eseguendo il deployment dell'immagine.
- project-id è l'ID del tuo progetto Google Cloud .
Crea l'argomento cloud-builds per ricevere i messaggi di aggiornamento della compilazione per il tuo notifier:
```
gcloud pubsub topics create cloud-builds
```
Crea un abbonato push Pub/Sub per il tuo notifier:
```
 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 all'abbonamento.
- service-url è l'URL generato da Cloud Run per il nuovo servizio.
- project-id è l'ID del tuo progetto Google Cloud .

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

La volta successiva che richiami una compilazione, la tabella verrà aggiornata con i dati più recenti corrispondenti al filtro che hai configurato per il notifier BigQuery.

Visualizzazione dei dati di compilazione

Per visualizzare i dati di compilazione in BigQuery:

Apri la pagina della console BigQuery:

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

Ora puoi vedere le informazioni relative alla tabella, incluso lo schema, nonché un'anteprima dei dati di compilazione elencati nella tabella.

Accesso ai dati di compilazione

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

Interfaccia a riga di comando

Per eseguire query sui dati della tabella utilizzando lo strumento a riga di comando bq, esegui il seguente 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 since. Lo strumento a riga di comando bq utilizza SQL precedente, mentre le query di esempio no. Esegui il seguente comando nel terminal per eseguire query sui dati senza SQL Legacy:

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 BigQuery
In Risorse, fai clic sul nome della tabella su cui vuoi eseguire una query.
Scrivi la query SQL nell'editor di query.

Utilizzare le query per accedere ai dati di compilazione

Le query di esempio riportate di seguito mostrano come accedere ai dati di compilazione per il tuo evento di compilazione, dopo la configurazione del notifier BigQuery:

Cronologia delle build complessive

SELECT * FROM `projectID.datasetName.tableName`

Creare conteggi raggruppati per stato

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

Frequenza di deployment giornaliera per la settimana in corso

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 altri esempi di query, consulta il file README di Cloud Build BigQuery Notifier nel repository cloud-build-notifiers su GitHub. Per scoprire di più su come eseguire query sui dati utilizzando BigQuery, consulta Eseguire query e visualizzare i 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 all'evento di compilazione, ad esempio l'ID trigger, l'elenco di immagini o i valori di sostituzione. Puoi utilizzare la stringa filter per filtrare gli eventi di compilazione nel file di configurazione della build utilizzando qualsiasi campo elencato nella risorsa Build. Per trovare la sintassi esatta associata al campo, consulta il file cloudbuild.proto.

Filtrare per ID attivatore

Per filtrare per 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

Filtrare per stato

Per filtrare in base allo stato, specifica lo stato di compilazione in base al quale vuoi filtrare nel campo filter utilizzando build.status.

L'esempio seguente mostra come filtrare gli eventi di compilazione 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 compilazione 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 altri valori di stato per i quali puoi filtrare, consulta Stato nella sezione Riferimento alle risorse di Build.

Filtrare 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 specificati nell'evento di compilazione utilizzando size. Nell'esempio seguente, il campo filter filtra gli eventi di compilazione che hanno esattamente due tag specificati, con un tag specificato come v1:

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

Filtrare per immagini

Per filtrare per immagini, specifica il valore dell'immagine nel campo filter utilizzando build.images, dove image-name è il nome completo dell'immagine come 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 gli eventi di compilazione 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 specificato come nomi delle 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

Filtrare per ora

Puoi filtrare gli eventi di compilazione in base all'ora di creazione, all'ora di inizio o all'ora di fine di una compilazione 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 compilazione con un orario della richiesta per creare la compilazione il 20 luglio 2020 alle 06:00:

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

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

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 vengono espressi in CEL, consulta la definizione di linguaggio per i fusi orari.

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

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

Filtro per sostituzione

Puoi filtrare per sostituzione specificando la variabile di sostituzione nel campo filter utilizzando build.substitutions. Nel seguente esempio, il campo filter elenca le build che contengono la variabile di sostituzione substitution-variable e controlla se substitution-variable corrisponde a 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 sostitutivo.

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

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

Se vuoi filtrare le stringhe utilizzando espressioni regolari, puoi utilizzare la funzione matches integrata. Nell'esempio seguente, il campo filter filtra per le build con stato FAILURE 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 Utilizzare le sostituzioni predefinite.

Passaggi successivi

Scopri di più sui notificatori di Cloud Build.
Scopri come abbonarti alle notifiche di compilazione.
Scopri come scrivere un file di configurazione della build di Cloud Build.