O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configurar notificações HTTP

O Cloud Build pode notificar você sobre atualizações de build enviando notificações para os canais selecionados, como o Slack ou seu servidor SMTP. Esta página explica como configurar notificações usando o Notificador do HTTP.

Antes de começar

Ative as APIs Cloud Build, Cloud Run e Pub/Sub.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pela função Proprietário (roles/owner). Caso contrário, você pode receber essa permissão pela função Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder funções.
Ativar as APIs

Instale a Google Cloud CLI.

Como configurar notificações HTTP

A seção a seguir explica como configurar notificações HTTP manualmente usando o notificador HTTP para enviar solicitações POST a um determinado URL de destinatário. Se você quiser automatizar a configuração, consulte Como automatizar a configuração de notificações.

Para configurar notificações HTTP:

Para usar o notificador do HTTP e enviar solicitações POST para um determinado URL de destinatário:

Conceda permissão à conta de serviço do Cloud Run para ler os buckets do Cloud Storage:
1. Acesse a página IAM no Google Cloud console:
  
  Abrir a página do IAM
2. Localize a conta de serviço padrão do Compute Engine associada ao seu projeto:
  
  Sua conta de serviço padrão do Compute Engine será semelhante a esta:
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
3. Clique no ícone de lápis na linha que contém sua conta de serviço padrão do Compute Engine. A guia Editar acesso será exibida.
4. Clique em Adicionar outro papel.
5. Adicione o seguinte papel:
  - Leitor de objetos do Storage
  Observação: se você quiser conceder permissões no nível do bucket e não no nível do projeto, adicione o papel Proprietário do objeto legado do Storage quando você criar um bucket. Para saber mais, consulte Diferença entre papéis do projeto e papéis no nível do bucket.
6. Clique em Save.
Grave um arquivo de configuração para configurar seu notificador do HTTP e filtrar eventos de build:

No exemplo de arquivo de configuração do notificador de exemplo, o campo filter usa Common Expression Language com a variável disponível, build, para filtrar os eventos de build com um status 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 usuário. Esse parâmetro assume o valor de $(build.status), o status do build.
- url é a variável de configuração usada neste exemplo para especificar o URL da solicitação.
- BUCKET_NAME é o nome do bucket.
- URL é o URL que você quer especificar como seu servidor destinatário.
- O campo uri faz referência ao arquivo http.json. Esse arquivo se refere a um modelo JSON hospedado no Cloud Storage e representa o payload JSON para o endpoint do webhook.
  
  Experimental : como personalizar notificações usando modelos
  
  Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.
  
  Para conferir um exemplo de arquivo de modelo, consulte o http.json arquivo no repositório cloud-build-notifiers.
Para ver o exemplo, consulte o notificador do arquivo de configuração para o HTTP notificador.

Para ver outros campos que podem ser filtrados, consulte o recurso Build. Para ver mais exemplos de filtragem, consulte Como usar a CEL para filtrar eventos do build.
Faça o upload do arquivo de configuração do notificador em um bucket do Cloud Storage:
1. Se você não tiver um bucket do Cloud Storage, execute o seguinte comando para criar um bucket, em que BUCKET_NAME é o nome que você quer dar ao bucket, sujeito aos requisitos de nomenclatura.
```
gcloud storage buckets create gs://BUCKET_NAME/
```
2. Faça o upload do arquivo de configuração do notificador para o bucket:
```
gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME
```
  Onde:
  - BUCKET_NAME é o nome do bucket.
  - CONFIG_FILE_NAME é o nome do arquivo de configuração do notificador.
Implante o notificador no Cloud Run.
```
 gcloud run deploy SERVICE_NAME \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/http: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 em que você está implantando a imagem;
- CONFIG_PATH é o caminho para o arquivo de configuração do notificador do HTTP notificador, gs://BUCKET_NAME/CONFIG_FILE_NAME.
- PROJECT_ID é o ID do projeto do Google Cloud .
O comando gcloud run deploy extrai a versão mais recente da imagem hospedada do Artifact Registry de propriedade do Cloud Build. O Cloud Build oferece suporte a imagens do notificador por nove meses. Após nove meses, o Cloud Build exclui a versão da imagem. Se quiser usar uma versão de imagem anterior, você precisará especificar a versão semântica completa da tag de imagem no atributo image do seu comando gcloud run deploy. Versões e tags de imagem anteriores podem ser encontradas no Artifact Registry.

Observação: ao executar esse comando, talvez seja necessário especificar outros argumentos, como --region ou --platform. Para saber mais sobre parâmetros que podem ser transmitidos ao comando gcloud run deploy, consulte Como implantar no Cloud Run. Se você não conseguir implantar o notificador usando esse comando, consulte o guia de solução de problemas do Cloud Run para saber como resolver erros de implantação.
Crie uma conta de serviço para representar sua identidade de assinatura do Pub/Sub:
```
gcloud iam service-accounts create SUB_IDENTITY_SERVICE_ACCOUNT \
  --display-name "SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME"
```
Onde:
- SUB_IDENTITY_SERVICE_ACCOUNT é um nome para a conta de serviço.
- SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME é um nome de exibição para a conta de serviço.
Observação: Essa conta de serviço é diferente da conta de serviço do Pub/Sub, que Google Cloud é criada quando você cria uma assinatura do Pub/Sub pela primeira vez. A conta de serviço do Pub/Sub tem um endereço de service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.

Conceda à conta de serviço de identidade de assinatura do Pub/Sub as permissões necessárias para criar tokens de autenticação no seu Google Cloud projeto.

gcloud iam service-accounts add-iam-policy-binding \
    SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iiam.gserviceaccount.com \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Onde:

PROJECT_ID é o ID do projeto do Google Cloud .
PROJECT_NUMBER é o número do Google Cloud projeto.

Conceda à conta de serviço SUB_IDENTITY_SERVICE_ACCOUNT a função Invoker do Cloud Run:
```
gcloud run services add-iam-policy-binding SERVICE_NAME \
   --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/run.invoker
```
Onde:
- SERVICE_NAME é o nome do serviço do Cloud Run em que você está implantando a imagem;
- PROJECT_ID é o ID do projeto do Google Cloud .
Crie o tópico cloud-builds para receber mensagens de atualização da build para seu notificador:
```
gcloud pubsub topics create cloud-builds
```
Também é possível definir um nome de tópico personalizado no arquivo de configuração do build para que as mensagens sejam enviadas ao tópico personalizado. Nesse caso, crie um tópico com o mesmo nome de tópico personalizado:
```
gcloud pubsub topics create topic-name
```
Para mais informações, consulte Tópicos do Pub/Sub para notificações de build.
Crie um assinante de push do Pub/Sub para seu notificador:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=SERVICE_URL \
       --push-auth-service-account=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

Onde: + SUBSCRIBER_ID é o nome que você quer dar à sua assinatura. + SERVICE_URL é o URL gerado pelo Cloud Run para o novo serviço. + PROJECT_ID é o ID do Google Cloud projeto.

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

Agora as notificações do seu projeto do Cloud Build estão configuradas. Na próxima vez que você invocar um build, o servidor HTTP de destino no URL especificado receberá payloads JSON que correspondem ao recurso Build caso a versão corresponder ao filtro que você configurou.

Como usar a CEL para filtrar eventos de build

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

Como filtrar por ID do acionador

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

filter: build.build_trigger_id == trigger-id

Como filtrar por status

Para filtrar por status, especifique o status do build que você quer filtrar no campo filter usando build.status.

O exemplo a seguir mostra como filtrar eventos de build com um status SUCCESS usando o campo filter:

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

Também é possível filtrar builds com status variados. O exemplo a seguir mostra como filtrar eventos de build com um status SUCCESS, FAILURE ou TIMEOUT usando o campo filter:

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

Para ver valores de status adicionais pelos quais você pode filtrar, consulte Status na referência do recurso do Build.

Como filtrar por tag

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

filter: tag-name in build.tags

É possível filtrar com base no número de tags especificadas no evento de build usando size. No exemplo a seguir, o campo filter filtra eventos de build que têm exatamente duas tags especificadas, uma delas como v1:

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

Como filtrar por imagens

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

filter: image-name in build.images

No exemplo a seguir, o filter filtra eventos de build com 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 imagem:

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

Como filtrar por tempo

É possível filtrar eventos de build com base no tempo de criação, horário de início ou horário de término de um build especificando uma das seguintes opções no campo filter: build.create_time, build.start_time ou build.finish_time.

No exemplo a seguir, o campo filter usa timestamp para filtrar eventos de build com um horário de solicitação para criar o build em 20 de julho de 2020, às 6h:

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

Também é possível filtrar eventos de build por comparações de tempo. No exemplo a seguir, o campo filter usa timestamp para filtrar eventos de versão com um horário de início entre 6 de julho de 2020, às 6h, e 30 de julho de 2020, às 6h.

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

Para saber mais sobre como os fusos horários são expressos em CEL, consulte a definição de linguagem para fusos horários.

Para filtrar por duração de um build, use duration para comparar carimbos de data/hora. No exemplo a seguir, o campo filter usa duration para filtrar eventos de build com um build executado por pelo menos cinco minutos:

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

Como filtrar por substituição

É possível filtrar por substituição especificando a variável de substituição no campo filter usando build.substitutions. No exemplo a seguir, o campo filter lista versõ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

Em que:

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

Também é possível filtrar por padrão os valores das variáveis de substituição. No exemplo a seguir, o campo filter lista os builds que têm o nome da ramificação master e os builds que têm o nome de repositório github.com/user/my-example-repo. As variáveis de substituição padrão 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 você quiser filtrar strings usando expressões regulares, use a função integrada matches. No exemplo abaixo, o campo filter filtra as criações com status FALHA ou TEMPO LIMITE e também tem uma variável de substituição de versão TAG_NAME com um valor correspondente à 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 de valores de substituição padrão, consulte Como usar substituições padrão.

A seguir

Saiba mais sobre os notificadores do Cloud Build.
Saiba como se inscrever para criar notificações.
Saiba como escrever um arquivo de configuração do build do Cloud Build.