Esta página foi traduzida pela API Cloud Translation.

Configure as notificações SMTP

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

Antes de começar

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

Instale a CLI do Google Cloud.

Configurar notificações por email

Para enviar notificações por email, precisa de um servidor SMTP em funcionamento e acesso a uma conta nesse servidor, incluindo o nome de utilizador e a palavra-passe da conta que vão ser usados para enviar notificações. Pode usar qualquer servidor SMTP existente, mas precisa de acesso ao nome do servidor e à porta. Por exemplo, o nome do servidor do Gmail é smtp.gmail.com e a porta é 587. Certifique-se de que as quotas de entrega do servidor SMTP conseguem processar o volume de emails que espera gerar.

A secção seguinte explica como pode configurar manualmente as notificações por email através do notificador SMTP. Se preferir automatizar a configuração, consulte o artigo Automatizar a configuração das notificações.

Para configurar notificações por email:

Armazenar a palavra-passe da conta de email do remetente no Secret Manager. Tenha em atenção que, para o Gmail, tem de usar a palavra-passe da app em vez da palavra-passe de início de sessão da conta.
1. Abra a página Secret Manager na Google Cloud consola:
  
  Abra a página Secret Manager
2. Clique em Criar segredo.
3. Introduza um nome para o segredo.
4. Em Valor secreto, adicione a palavra-passe da conta de email do remetente.
5. Para guardar o segredo, clique em Criar segredo.
Embora a sua conta de serviço do Cloud Run possa ter a função de Editor para o seu projeto, a função de Editor não é suficiente para aceder ao seu segredo no Secret Manager. Para conceder à conta de serviço do Cloud Run acesso ao seu segredo, faça o seguinte:
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
```
  Tome nota da conta de serviço predefinida do Compute Engine.
  
  Nota: por predefinição, o Cloud Run executa as suas imagens do notificador com a conta de serviço predefinida do Compute Engine e usa-a para obter o seu segredo. Para saber mais sobre as contas de serviço do Runtime, consulte o artigo Conta de serviço do Runtime.
3. Abra a página Secret Manager na Google Cloud consola:
  
  Abra a página Secret Manager
4. Clique no nome do segredo que contém o segredo da palavra-passe da conta de email do remetente.
5. No separador Permissões, clique em Adicionar membro.
6. Adicione a conta de serviço predefinida do Compute Engine associada ao seu projeto como membro.
7. Selecione a autorização Secret Manager Secret Accessor como função.
8. Clique em Guardar.
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 Atribuir funções ao nível do projeto, do contentor ou da pasta gerida.
6. Clique em Guardar.
Escreva um ficheiro de configuração do notificador para configurar o notificador SMTP e filtre os 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: 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://bucket_name/smtp.html
  secrets:
  - name: smtp-password
    value: projects/project-id/secrets/secret-name/versions/latest
```
Onde:
- buildStatus é um parâmetro definido pelo utilizador. Este parâmetro assume o valor de $(build.status), o estado da compilação.
- bucket-name é o nome do seu contentor.
- server-host-name é o endereço do seu servidor SMTP.
- port é a porta que processa os pedidos SMTP. Este valor deve ser especificado como uma string.
- sender-email é o endereço de email da conta do remetente que é visto pelo server-host-name especificado.
- from-email é o endereço de email que os destinatários veem.
- recipient-email é uma lista de um ou mais endereços de email para receber mensagens do remetente.
- smtp-password é a variável de configuração usada neste exemplo para fazer referência à palavra-passe da conta de email do remetente armazenada no Secret Manager. O nome da variável que especificar aqui deve corresponder ao campo name em secrets.
- project-id é o ID do seu Google Cloud projeto.
- secret-name é o nome do seu segredo que contém a palavra-passe da conta de email do remetente.
- O campo uri faz referência ao ficheiro smtp.html. Este ficheiro refere-se a um modelo HTML alojado no Cloud Storage e representa o seu email de notificação.
  
  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 o exemplo, consulte o ficheiro de configuração do notificador para o notificador SMTP.

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.
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. Da próxima vez que invocar uma compilação, o endereço de email especificado recipients recebe um email com uma notificação 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.