Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare le notifiche SMTP

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 SMTP.

Prima di iniziare

Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.
Enable the APIs

Installa Google Cloud CLI.

Configurazione delle notifiche via email

Per inviare notifiche via email, devi disporre di un server SMTP in esecuzione e dell'accesso a un account sul server, includendo nome utente e password dell'account verranno utilizzate per inviare notifiche. Puoi usare qualsiasi server SMTP esistente, avrà bisogno di accedere al nome e alla porta del server. Ad esempio, il nome del server per Gmail è smtp.gmail.com e la porta è 587. Assicurati che il tuo server SMTP le quote di recapito del server possano gestire il volume di email che prevedi di generare.

La sezione seguente spiega come configurare manualmente le notifiche via email utilizzando il notificatore SMTP. Se vuoi automatizzare consulta l'articolo Automatizzare la configurazione delle notifiche.

Per configurare le notifiche via email:

Memorizza la password dell'account email del mittente in Secret Manager. Tieni presente che, per Gmail, devi utilizzare la password per l'app anziché la password di accesso all'account.
1. Apri la pagina Secret Manager nella console Google Cloud:
  
  Apri la pagina Secret Manager
2. Fai clic su Crea secret.
3. Inserisci un nome per il secret.
4. In Valore secret, aggiungi la password dell'account email del mittente.
5. Per salvare il secret, fai clic su Crea secret.
Anche se il tuo account di servizio Cloud Run può avere Editor per il progetto, il ruolo Editor non lo è per accedere al tuo secret in Secret Manager. Dovrai concedere l'accesso al tuo account di servizio Cloud Run al tuo secret:
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
```
  Prendi nota del tuo account di servizio predefinito di Compute Engine.
  
  Nota: per impostazione predefinita, Cloud Run esegue le immagini di notifica con l'account di servizio predefinito di Compute Engine e lo utilizza per recuperare il segreto. Per scoprire di più sugli account di servizio di runtime, consulta Account di servizio di runtime.
3. Apri la pagina Secret Manager nella console Google Cloud:
  
  Apri la pagina di Secret Manager
4. Fai clic sul nome del segreto che contiene il segreto per la password dell'account email del mittente.
5. Nella scheda Autorizzazioni, fai clic su Aggiungi membro.
6. Aggiungi l'account di servizio predefinito di Compute Engine associato al progetto come membro.
7. Seleziona l'autorizzazione Secret Manager Secret Accessor come ruolo.
8. Fai clic su Salva.
Concedi al tuo account di servizio Cloud Run l'autorizzazione per leggere da 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. Verrà visualizzata la scheda Accesso in modifica.
4. Fai clic su Aggiungi un altro ruolo.
5. Aggiungi il seguente ruolo:
  - Visualizzatore oggetti Storage
  Nota: per concedere le autorizzazioni a livello di bucket anziché a livello di progetto, aggiungi il ruolo Proprietario oggetti legacy Storage al tuo bucket quando crei uno. 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 notificatore per configurare il notificatore SMTP 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 disponibile build per filtrare gli eventi di compilazione con uno stato SUCCESS:
```
apiVersion: cloud-build-notifiers/v1
kind: SMTPNotifier
metadata:
  name: example-smtp-notifier
spec:
  notification:
    filter: build.status == Build.Status.SUCCESS
    params:
      buildStatus: $(build.status)
    delivery:
      server: server-host-name
      port: "port"
      sender: sender-email
      from: from-email
      recipients:
        - recipient-email
        # optional: more emails here
      password:
        secretRef: smtp-password
    template:
      type: golang
      uri: gs://example-gcs-bucket/smtp.html
  secrets:
  - name: smtp-password
    value: projects/project-id/secrets/secret-name/versions/latest
```
Dove:
- buildStatus è un parametro definito dall'utente. Questo parametro assume il valore di $(build.status), lo stato della compilazione.
- server-host-name è l'indirizzo del tuo server SMTP.
- port è la porta che gestirà le richieste SMTP. Questo valore deve essere specificato come stringa.
- sender-email è l'indirizzo email dell'account mittente visualizzato da server-host-name specificato.
- from-email è l'indirizzo email visualizzato da destinatari.
- recipient-email è un elenco di uno o più indirizzi email da ricevere i messaggi inviati dal mittente.
- smtp-password è la variabile di configurazione utilizzata in questo esempio per fare riferimento alla password dell'account email del mittente memorizzata in Secret Manager. Il nome della variabile qui specificato deve corrisponde al campo name in secrets.
- project-id è l'ID del tuo progetto Google Cloud.
- secret-name è il nome del tuo secret che contiene la password per l'account email del mittente.
- Il campo uri fa riferimento al file smtp.html. Questo file fa riferimento a un modello HTML ospitato su Cloud Storage e rappresenta l'email di notifica.
  
  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 l'esempio, consulta il file di configurazione delle notifiche per SMTP notificatore.

Per altri 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 notifier in un bucket Cloud Storage:
1. Se non hai un bucket Cloud Storage, esegui questo comando creare un bucket, dove bucket-name è il nome che vuoi assegnare bucket, soggetti ai requisiti di denominazione.
```
gcloud storage buckets create gs://bucket-name/
```
2. Carica il file di configurazione dell'autore della notifica nel tuo 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.
Esegui il deployment del notifier in Cloud Run:
```
gcloud run deploy service-name \
  --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/smtp:latest \
  --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 stai creando.
- config-path è il percorso del file di configurazione del notifier per il notifier SMTP, 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 dell'oggetto da Artifact Registry di proprietà di Cloud Build. Cloud Build supporta le immagini di avviso per nove mesi. Dopo nove mesi, Cloud Build elimina dell'immagine. Per 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 generatore di notifiche utilizzando questo comando, consulta la guida alla risoluzione dei problemi di Cloud Run per le soluzioni relative alla risoluzione degli 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à 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 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 state configurate. La prossima volta che richiami una compilazione, recipients riceverà un'email con una notifica se la compilazione corrisponde al filtro che hai configurato.

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 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 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 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 in base ai quali puoi filtrare, consulta la sezione Stato nella sezione Build come riferimento delle risorse.

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 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 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

Filtro 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 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 di linguaggio 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 build in esecuzione per almeno cinque minuti:

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

Filtrare 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. 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. 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ù sui notificatori di Cloud Build.
Scopri come abbonarti alle notifiche di compilazione.
Scopri come scrivere un file di configurazione della build di Cloud Build.