Configura le notifiche HTTP

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

Prima di iniziare

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

    Enable the APIs

Configurazione delle notifiche HTTP

La sezione seguente spiega come configurare manualmente le notifiche HTTP utilizzando HTTP notifier per inviare richieste POST all'URL di un determinato destinatario. Se invece vuoi automatizzare la configurazione, consulta la sezione Automatizzare la configurazione per le notifiche.

Per configurare le notifiche HTTP:

Per utilizzare HTTP notifier per inviare POST richieste all'URL di un determinato destinatario:

  1. Concedi all'account di servizio Cloud Run l'autorizzazione a leggere dai 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 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. Viene visualizzata la scheda Accesso in modifica.

    4. Fai clic su Aggiungi un altro ruolo.

    5. Aggiungi il seguente ruolo:

      • Storage Object Viewer
    6. Fai clic su Salva.

  2. Scrivi un file di configurazione del notificatore per configurare il notificatore HTTP e filtrare in base agli eventi di compilazione:

    Nel seguente file di configurazione dell'autore della notifica, il campo filter utilizza Common Expression Language con la variabile disponibile build per filtrare gli eventi di build con lo stato SUCCESS:

    apiVersion: cloud-build-notifiers/v1
    kind: HTTPNotifier
    metadata:
      name: example-http-notifier
    spec:
      notification:
        filter: build.status == Build.Status.SUCCESS
        params:
          buildStatus: $(build.status)
        delivery:
          # The `http(s)://` protocol prefix is required.
          url: url
        template:
          type: golang
          uri: gs://example-gcs-bucket/http.json
    

    Dove:

    • buildStatus è un parametro definito dall'utente. Questo parametro assume il valore di $(build.status), lo stato della build.
    • url è la variabile di configurazione utilizzata in questo esempio per specificare l'URL per la richiesta.
    • url è l'URL da specificare come server di destinazione.
    • Il campo uri fa riferimento al file http.json. Questo file fa riferimento a un modello JSON ospitato su Cloud Storage e rappresenta il payload json all'endpoint webhook.

      Per visualizzare un esempio di file modello, vedi il file http.json nel repository cloud-build-notifiers.

    Per visualizzare l'esempio, consulta il file di configurazione delle notifiche per il protocollo notificatore.

    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.

  3. 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 da assegnare al bucket, in base ai 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 tuo bucket.
      • config-file-name è il nome del file di configurazione dell'autore della notifica.
  4. Esegui il deployment del notifier in Cloud Run:

     gcloud run deploy service-name \
       --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/http:latest \
       --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.

    • config-path è il percorso del file di configurazione del notifier HTTP, 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'immagine ospitata dall'Artifact Registry di proprietà di Cloud Build. Cloud Build supporta le immagini di notifica 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 e i tag delle immagini precedenti sono disponibili in Artifact Registry.

  5. 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.
  6. 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.

  7. 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.
  8. Crea l'argomento cloud-builds per ricevere i messaggi di aggiornamento della compilazione per il tuo notifier:

    gcloud pubsub topics create cloud-builds
    
  9. 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. Il prossimo volta che richiami una build, il server HTTP di destinazione all'URL specificato riceverà Payload JSON che corrispondono al file Build risorsa se la build corrisponde al filtro 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 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 tuo campo, consulta le cloudbuild.proto .

Filtro per ID trigger

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

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 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 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 compilazione in base ai confronti di tempo. 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 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. 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 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 includono 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 visualizzare un elenco dei valori di sostituzione predefiniti, consulta Utilizzare le sostituzioni predefinite.

Passaggi successivi