Questa pagina è stata tradotta dall'API Cloud Translation.

Configura le notifiche di BigQuery

Cloud Build può inviarti notifiche sugli aggiornamenti della build tramite inviare notifiche ai canali desiderati, ad esempio Slack o il tuo server SMTP. Questa pagina spiega come configurare le notifiche utilizzando BigQuery notifier.

Il Notifier di BigQuery fornisce la funzionalità per specificare i filtri su le build che vuoi archiviare nel database. Ad esempio, puoi raggruppare le build per ID trigger, tag o valori di sostituzione. Inoltre, BigQuery Notifier scrive i dati in BigQuery in un formato standardizzato che include i campi calcolati non immediatamente accessibile nell'oggetto Build, ad esempio dimensioni dell'immagine o dell'esecuzione. Se vuoi scoprire come esportare le voci di log in BigQuery o in un'altra destinazione, consulta 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 sezione seguente spiega come configurare manualmente le notifiche HTTP utilizzando BigQuery notifier. Se invece vuoi automatizzare la configurazione, vedi 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, autorizzazione per recuperare i dati di Artifact Registry correlati alla tua build e 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 a con il tuo 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 il tuo account di servizio predefinito di Compute Engine. Verrà visualizzata la scheda Accesso in modifica.
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 ti consente di recuperare i dati per le tue immagini. L'editor dati di BigQuery ti consente di accedere in lettura e scrittura ai dati. Il Visualizzatore oggetti Storage ti dà accesso in lettura a Cloud Storage di oggetti strutturati.
  
  Nota: se vuoi concedere le autorizzazioni a livello di bucket anziché a livello di progetto, aggiungi il ruolo Proprietario oggetti legacy Storage al bucket quando crei uno. Per saperne di più, vedi Ruoli a livello di progetto e ruoli a livello di bucket.
6. Fai clic su Salva.
Scrivi un file di configurazione delle notifiche per configurare lo strumento di notifica BigQuery e filtrare in base a creare eventi:

Nel seguente file di configurazione dell'autore della notifica, il campo filter utilizza 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 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, vedi il file bq.json nel repository cloud-build-notifiers-repository.

L'elemento table-name nel file di configurazione della notifica 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 di BigQuery
  
  Nota: fa riferimento a una tabella esistente con una specifica dello schema se il server di notifica BigQuery non corrisponde, verrà visualizzato un errore.
Ti consigliamo di specificare l'ID trigger di build come filtro poiché hai specificato l'ID trigger di build consente di correlare i dati di build per i trigger. Puoi anche specificare più ID trigger 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 di gcloud descrivono trigger-name

Il comando elencherà i campi associati al tuo trigger, incluso l'ID trigger.

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

Per visualizzare l'esempio, vedi il file di configurazione delle notifiche per BigQuery notificatore.

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

Nota: durante l'esecuzione di questo comando, ti potrebbe essere chiesto di specificare argomenti aggiuntivi come --region o --platform. Per scoprire di più su parametri che puoi passare al comando gcloud run deploy, consulta 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 le soluzioni 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 su del tuo progetto, consulta Creare e utilizzare gli abbonamenti.
Crea un account di servizio per rappresentare l'identità dell'abbonamento 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 a 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 build per l'autore della notifica:
```
gcloud pubsub topics create cloud-builds
```
Crea un sottoscrittore push di Pub/Sub per l'autore della notifica:
```
 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 ora configurate.

La prossima volta che richiami una build, la tabella verrà aggiornata con corrispondenti al filtro che hai configurato per l'avviso di BigQuery.

Visualizzazione dei dati della build

Per visualizzare i dati della build in BigQuery:

Apri la pagina della console BigQuery:

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

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

Accesso ai dati della build

Puoi eseguire query sui dati della 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 questo comando: nel terminale dove sql-query è query:

bq query sql-query

Se prevedi di utilizzare gli esempi di query su questa pagina, assicurati di specificare il parametro --nouse_legacy_sql nel tuo comando. Lo strumento a riga di comando bq utilizza SQL precedente al contrario delle query di esempio. Esegui questo comando 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 BigQuery
In Risorse, fai clic sul nome della tabella su cui eseguire la query.
Scrivi la query SQL nell'Editor query.

Utilizzo di query per accedere ai dati della build

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

Cronologia build generale

SELECT * FROM `projectID.datasetName.tableName`

Numero di build 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 visualizzare altri esempi di query, vedi il file README di BigQuery Notification di Cloud Build nel repository cloud-build-notifiers su GitHub. Per scoprire di più su come eseguire query sui dati utilizzando BigQuery, consulta Esecuzione di query e visualizzazione i tuoi dati.

Utilizzo di CEL per filtrare gli eventi di build

Cloud Build utilizza la tecnologia CEL con la variabile build nei campi elencato nella sezione Build per accedere ai campi associati all'evento di build, ad esempio l'ID trigger, l'elenco di immagini o i valori di sostituzione. Puoi usare filter stringa per filtrare gli eventi di build nel file di configurazione di compilazione utilizzando in tutti i campi elencati nella sezione Build risorsa. Per trovare la sintassi esatta associata al tuo campo, consulta le cloudbuild.proto .

Filtro per ID trigger

Per filtrare in base all'ID trigger, specifica il valore dell'ID trigger nel campo filter campo utilizzando build.build_trigger_id, dove trigger-id è l'ID trigger 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 al quale applicare il filtro nel campo filter utilizzando build.status.

L'esempio seguente mostra come filtrare gli eventi di build con un 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 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 in base ai quali puoi filtrare, consulta la sezione Stato nella sezione Build come riferimento delle risorse.

Filtro per tag

Per filtrare in base al tag, specifica il valore del tag nel campo filter campo utilizzando build.tags, dove tag-name è il nome del tuo 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, i filtri di campo filter crea eventi che abbiano 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 come elencato in Artifact Registry, us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Nell'esempio seguente, filter applica un filtro agli eventi di build con 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

Filtro per ora

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

Nell'esempio seguente, il campo filter utilizza timestamp per filtrare eventi di build con un'ora di 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 gli 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 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 dei 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 con build che vengono eseguite 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. Nell'esempio seguente, Il campo filter elenca le build che contengono la variabile di sostituzione substitution-variable e verifica se substitution-variable corrisponde al valore 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 delle variabili di sostituzione. Nel seguente Ad esempio, il campo filter elenca le build con il nome ramo master e le build che hanno il nome del repository github.com/user/my-example-repo. La vengono passate le variabili di sostituzione predefinite BRANCH_NAME e REPO_NAME come chiavi per 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, i filtri di campo filter per le build con stato ERRORE o TIMEOUT e che hanno anche una build variabile di sostituzione TAG_NAME con un valore che corrisponde 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 un elenco dei valori di sostituzione predefiniti, consulta la sezione Utilizzo di sostituzioni predefinite.

Passaggi successivi

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