Configure as notificações do BigQuery

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

O notificador do BigQuery permite-lhe especificar filtros para compilações que quer armazenar na sua base de dados. Por exemplo, pode agrupar as compilações por ID do acionador, etiquetas ou valores de substituição. O notificador do BigQuery também escreve dados no BigQuery num formato padronizado que inclui campos calculados não imediatamente acessíveis no objeto Build, como o tamanho da imagem ou a duração da execução. Se quiser saber como exportar entradas de registo para o BigQuery ou outro destino, consulte o artigo Exportar registos com a Google Cloud consola.

Antes de começar

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

  Enable the APIs

• Instale a CLI do Google Cloud.

Configure as notificações do BigQuery

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

Para configurar notificações do BigQuery:

1. Conceda à sua conta de serviço do Cloud Run autorização para criar e escrever tabelas do BigQuery, autorização para obter dados do Artifact Registry relacionados com a sua compilação e acesso de leitura e escrita a 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[email protected]
      

   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 as seguintes funções:

      • Leitor do Artifact Registry
      • Editor de dados do BigQuery
      • Storage Object Viewer

      A função Leitor do Artifact Registry permite-lhe obter dados para as suas imagens. A função de editor de dados do BigQuery dá-lhe acesso de leitura e escrita aos seus dados. O Storage Object Viewer concede-lhe acesso de leitura a objetos do Cloud Storage.

   6. Clique em Guardar.

2. Escreva um ficheiro de configuração do notificador para configurar o notificador do BigQuery e filtre os eventos de compilação:

   No ficheiro de configuração do notificador de exemplo seguinte, o campo filter usa a linguagem de expressão comum com a variável build para filtrar eventos de compilação com um ID de acionador especificado:

   apiVersion: cloud-build-notifiers/v1
   kind: BigQueryNotifier
   metadata:
     name: example-bigquery-notifier
   spec:
     notification:
       filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000"
       params:
         buildStatus: $(build.status)
       delivery:
         table: projects/project-id/datasets/dataset-name/tables/table-name
       template:
         type: golang
         uri: gs://bucket_name/bq.json
   

   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.
   • project-id é o ID do seu Google Cloud projeto.
   • dataset-name é o nome que quer dar ao seu conjunto de dados.
   • table-name é o nome que quer dar à tabela.

   • O campo uri faz referência ao ficheiro bq.json. Este ficheiro refere-se a um modelo JSON alojado no Cloud Storage e representa as informações a inserir na sua tabela do BigQuery.

   Para ver um exemplo de um ficheiro de modelo, consulte o ficheiro bq.json no repositório cloud-build-notifiers.

   O table-name no ficheiro de configuração do notificador pode referir-se a:

   • uma tabela inexistente
   • uma tabela vazia sem um esquema

   • Uma tabela existente com um esquema que corresponde às especificações do esquema no notificador do BigQuery

   Recomendamos que especifique o ID do acionador de compilação como filtro, uma vez que a especificação do ID do acionador de compilação permite correlacionar os dados de compilação dos acionadores. Também pode especificar vários IDs de acionadores numa lista: build.build_trigger_id in ["example-id-123", "example-id-456"].

   Para obter o ID do acionador, execute o seguinte comando, em que trigger-name é o nome do acionador:

   gcloud builds triggers describe trigger-name

   O comando apresenta os campos associados ao seu acionador, incluindo o ID do acionador.

   Para ver o exemplo, consulte o ficheiro de configuração do notificador para o notificador do BigQuery.

   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.

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

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

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

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

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

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

9. 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, a tabela é atualizada com os dados mais recentes que correspondem ao filtro configurado para o notificador do BigQuery.

Ver dados de compilação

Para ver os dados de compilação no BigQuery:

1. Abra a página da consola do BigQuery:

   Abra a página do BigQuery

2. Em Recursos, clique no ID do projeto que usa para configurar o seu notificador do BigQuery.

3. Clique no nome do conjunto de dados.

4. Clique no nome da tabela.

Agora, pode ver informações relacionadas com a sua tabela, incluindo o respetivo esquema e uma pré-visualização dos dados de compilação, conforme indicado na tabela.

Aceder aos dados de compilação

Pode consultar dados na sua tabela através da ferramenta de linha de comandos bq ou da consola do BigQuery.

bq query sql-query

bq query sql-query --nouse_legacy_sql

Usar consultas para aceder a dados de compilação

As consultas de exemplo seguintes mostram como pode aceder aos dados de compilação do seu evento de compilação após a configuração do notificador do BigQuery:

Histórico de compilação geral

SELECT * FROM `projectID.datasetName.tableName`

Contagens de compilações agrupadas por estado

SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS

Frequência de implementação diária para a semana atual

SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
      DATETIME_TRUNC(CreateTime, DAY) AS DAY,
      STATUS
      FROM `projectID.datasetName.tableName`
      WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY

Para ver mais exemplos de consultas, consulte o README do Cloud Build BigQuery Notifier no repositório cloud-build-notifiers no GitHub. Para saber como consultar dados através do BigQuery, consulte o artigo Consultar e ver dados.

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.