Esta página foi traduzida pela API Cloud Translation.

Configure notificações HTTP

O Cloud Build pode enviar-lhe notificações sobre atualizações de compilação para canais selecionados, como o Slack ou o seu servidor SMTP. Esta página explica como configurar notificações através do notificador HTTP.

Antes de começar

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

Instale a CLI do Google Cloud.

Configurar notificações HTTP

A secção seguinte explica como pode configurar manualmente as notificações HTTP usando o notificador HTTP para enviar pedidos POST para um determinado URL do destinatário. Se preferir automatizar a configuração, consulte o artigo Automatizar a configuração para notificações.

Para configurar notificações HTTP:

Para usar o notificador HTTP para enviar pedidos POST para um URL de destinatário específico:

Conceda à sua conta de serviço do Cloud Run autorização para ler a partir de contentores do Cloud Storage:
1. Aceda à página IAM na Google Cloud consola:
  
  Abra a página IAM
2. Localize a conta de serviço predefinida do Compute Engine associada ao seu projeto:
  
  A sua conta de serviço predefinida do Compute Engine vai ser semelhante à seguinte:
```
project-number-compute@developer.gserviceaccount.com
```
3. Clique no ícone de lápis na linha que contém a conta de serviço predefinida do Compute Engine. É apresentado o separador Acesso de edição.
4. Clique em Adicionar outra função.
5. Adicione a seguinte função:
  - Storage Object Viewer
  Nota: se quiser conceder autorizações ao nível do contentor em vez do nível do projeto, adicione a função Proprietário do objeto antigo de armazenamento ao seu contentor quando criar um. Para saber mais, consulte o artigo Funções ao nível do projeto vs. funções ao nível do contentor.
6. Clique em Guardar.
Escreva um ficheiro de configuração do notificador para configurar o notificador HTTP e filtrar eventos de compilação:

No ficheiro de configuração do notificador do exemplo seguinte, o campo filter usa a linguagem de expressão comum com a variável disponível, build, para filtrar eventos de compilação com um estado 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://bucket_name/http.json
```
Onde:
- buildStatus é um parâmetro definido pelo utilizador. Este parâmetro assume o valor de $(build.status), o estado da compilação.
- url é a variável de configuração usada neste exemplo para especificar o URL do seu pedido.
- bucket-name é o nome do seu contentor.
- url é o URL que quer especificar como o seu servidor destinatário.
- O campo uri faz referência ao ficheiro http.json. Este ficheiro refere-se a um modelo JSON alojado no Cloud Storage e representa a carga útil JSON para o ponto final do webhook.
  
  Experimental — Customizing notifications using templates
  
  Esta funcionalidade está sujeita aos "Termos de ofertas de pré-disponibilidade geral" na secção de Termos de Utilização Gerais dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.
  
  Para ver um exemplo de um ficheiro de modelo, consulte o ficheiro http.json no repositório cloud-build-notifiers.
Para ver o exemplo, consulte o ficheiro de configuração do notificador para o notificador HTTP.

Para ver campos adicionais pelos quais pode filtrar, consulte o recurso Build. Para ver exemplos de filtragem adicionais, consulte o artigo Usar o IEC para filtrar eventos de compilação.
Carregue o ficheiro de configuração do notificador para um contentor do Cloud Storage:
1. Se não tiver um contentor do Cloud Storage, execute o seguinte comando para criar um contentor, em que bucket-name é o nome que quer dar ao seu contentor, sujeito aos requisitos de nomenclatura.
```
gcloud storage buckets create gs://bucket-name/
```
2. Carregue o ficheiro de configuração do notificador para o seu contentor:
```
gcloud storage cp config-file-name gs://bucket-name/config-file-name
```
  Onde:
  - bucket-name é o nome do seu contentor.
  - config-file-name é o nome do ficheiro de configuração do notificador.
Implemente o seu serviço de notificação no Cloud Run:
```
 gcloud run deploy service-name \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/slack:latest \
   --no-allow-unauthenticated \
   --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
```
Onde:
- service-name é o nome do serviço do Cloud Run para o qual está a implementar a imagem.
- config-path é o caminho para o ficheiro de configuração do notificador do Slack, gs://bucket-name/config-file-name.
- project-id é o ID do seu Google Cloud projeto.
O comando gcloud run deploy extrai a versão mais recente da imagem alojada do Artifact Registry pertencente ao Cloud Build. O Cloud Build suporta imagens de notificador durante nove meses. Após nove meses, o Cloud Build elimina a versão da imagem. Se quiser usar uma versão anterior da imagem, tem de especificar a versão semântica completa da etiqueta de imagem no atributo image do comando gcloud run deploy. Pode encontrar as versões e as etiquetas de imagens anteriores no Artifact Registry.

Nota: ao executar este comando, pode ser-lhe pedido que especifique argumentos adicionais, como --region ou --platform. Para saber mais acerca dos parâmetros que pode transmitir para o comando gcloud run deploy, consulte o artigo Implementação no Cloud Run. Se não conseguir implementar o seu notificador através deste comando, consulte o guia de resolução de problemas do Cloud Run para ver soluções sobre como resolver erros de implementação.
Conceda autorizações do Pub/Sub para criar tokens de autenticação no seu Google Cloud projeto:
```
 gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
```
Onde:
- project-id é o ID do seu Google Cloud projeto.
- project-number é o número do seu Google Cloud projeto.
Nota: se a conta de serviço do Pub/Sub não existir no seu projeto, consulte o artigo Crie e use subscrições.
Crie uma conta de serviço para representar a identidade da sua subscrição do Pub/Sub:
```
gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"
```
Pode usar cloud-run-pubsub-invoker ou usar um nome único no seu projeto Google Cloud .
Conceda à conta de serviço cloud-run-pubsub-invoker a autorização Invoker do 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
```
Onde:
- service-name é o nome do serviço do Cloud Run para o qual está a implementar a imagem.
- project-id é o ID do seu Google Cloud projeto.
Crie o tópico cloud-builds para receber mensagens de atualização de compilação para o seu notificador:
```
gcloud pubsub topics create cloud-builds
```
Também pode definir um nome de tópico personalizado no ficheiro de configuração de compilação para que as mensagens sejam enviadas para o tópico personalizado. Neste caso, criaria um tópico com o mesmo nome de tópico personalizado:
```
gcloud pubsub topics create topic-name
```
Para mais informações, consulte o artigo Tópicos do Pub/Sub para notificações de compilação.
Crie um subscritor de envio do Pub/Sub para o seu notificador:
```
 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
```
Onde:
- subscriber-id é o nome que quer atribuir à sua subscrição.
- service-url é o URL gerado pelo Cloud Run para o seu novo serviço.
- project-id é o ID do seu Google Cloud projeto.

As notificações para o seu projeto do Cloud Build estão agora configuradas. Na próxima vez que invocar uma compilação, o seu servidor HTTP recetor no URL indicado vai receber payloads JSON que correspondem ao recurso Build se a compilação corresponder ao filtro que configurou.

Usar o IEC para filtrar eventos de compilação

O Cloud Build usa o CEL com a variável build nos campos indicados no recurso Build para aceder aos campos associados ao seu evento de compilação, como o ID do acionador, a lista de imagens ou os valores de substituição. Pode usar a string filter para filtrar eventos de compilação no ficheiro de configuração de compilação usando qualquer campo listado no recurso Build. Para encontrar a sintaxe exata associada ao seu campo, consulte o ficheiro cloudbuild.proto.

Filtrar por ID do acionador

Para filtrar por ID do acionador, especifique o valor do ID do acionador no campo filter usando build.build_trigger_id, em que trigger-id é o ID do acionador como uma string:

filter: build.build_trigger_id == trigger-id

Filtrar por estado

Para filtrar por estado, especifique o estado de compilação pelo qual quer filtrar no campo filter com build.status.

O exemplo seguinte mostra como filtrar eventos de compilação com um SUCCESS status através do campo filter:

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

Também pode filtrar compilações com vários estados. O exemplo seguinte mostra como filtrar eventos de compilação que têm um estado SUCCESS, FAILURE ou TIMEOUT usando o campo filter:

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

Para ver os valores de estado adicionais pelos quais pode filtrar, consulte Estado na referência de recursos de criação.

Filtragem por etiqueta

Para filtrar por etiqueta, especifique o valor da etiqueta no campo filter com build.tags, em que tag-name é o nome da etiqueta:

filter: tag-name in build.tags

Pode filtrar com base no número de etiquetas especificadas no evento de compilação usando size. No exemplo seguinte, o campo filter filtra os eventos de compilação que têm exatamente duas etiquetas especificadas, com uma etiqueta especificada como v1:

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

Filtrar por imagens

Para filtrar por imagens, especifique o valor da sua imagem no campo filter usando build.images, onde image-name é o nome completo da sua imagem, conforme indicado no Artifact Registry, como us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

No exemplo seguinte, os filtros filter são aplicados a eventos de criação que têm us-east1-docker.pkg.dev/my-project/docker-repo/image-one ou us-east1-docker.pkg.dev/my-project/docker-repo/image-two especificados como nomes de imagens:

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

Filtrar por hora

Pode filtrar eventos de compilação com base na hora de criação, na hora de início ou na hora de conclusão de uma compilação, especificando uma das seguintes opções no campo filter: build.create_time, build.start_time ou build.finish_time.

No exemplo seguinte, o campo filter usa timestamp para filtrar eventos de compilação com uma hora de pedido para criar a compilação a 20 de julho de 2020 às 06:00:

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

Também pode filtrar eventos de criação com base em comparações de tempo. No exemplo seguinte, o campo filter usa timestamp para filtrar eventos de criação com uma hora de início entre 20 de julho de 2020 às 06:00 e 30 de julho de 2020 às 06:00.

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

Para saber como os fusos horários são expressos no IEC, consulte a definição de idioma para fusos horários.

Para filtrar por duração de uma compilação, pode usar duration para comparar datas/horas. No exemplo seguinte, o campo filter usa duration para filtrar eventos de compilação com compilações que são executadas durante, pelo menos, cinco minutos:

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

Filtragem por substituição

Pode filtrar por substituição especificando a variável de substituição no campo filter usando build.substitutions. No exemplo seguinte, o campo filter apresenta as compilações que contêm a variável de substituição substitution-variable e verifica se o substitution-variable corresponde ao substitution-value especificado:

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

Onde:

substitution-variable é o nome da variável de substituição.
substitution-value é o nome do valor de substituição.

Também pode filtrar por valores de variáveis de substituição predefinidos. No exemplo seguinte, o campo filter apresenta compilações com o nome do ramo master e compilações com o nome do repositório github.com/user/my-example-repo. As variáveis de substituição predefinidas BRANCH_NAME e REPO_NAME são transmitidas como chaves para o build.substitutions:

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

Se quiser filtrar strings através de expressões regulares, pode usar a função matches incorporada. No exemplo abaixo, o campo filter filtra as compilações com o estado FAILURE ou TIMEOUT e que também têm uma variável de substituição de compilação TAG_NAME com um valor que corresponde à expressão regular 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}$")

Para ver uma lista dos valores de substituição predefinidos, consulte o artigo Usar substituições predefinidas.

O que se segue?

Saiba mais sobre os notificadores do Cloud Build.
Saiba como subscrever notificações de compilação.
Saiba como escrever um ficheiro de configuração de compilação do Cloud Build.