Crie um pipeline de processamento do BigQuery com o Eventarc

Padrão

---

Este tutorial mostra como usar o Eventarc para criar um pipeline de processamento que agende consultas a um conjunto de dados público do BigQuery, gere gráficos com base nos dados e partilhe links para os gráficos por email.

Objetivos

Neste tutorial, vai criar e implementar três serviços do Cloud Run que permitem o acesso não autenticado e que recebem eventos através do Eventarc:

1. Query Runner: acionado quando as tarefas do Cloud Scheduler publicam uma mensagem num tópico do Pub/Sub. Este serviço usa a API BigQuery para obter dados de um conjunto de dados público da COVID-19 e guarda os resultados numa nova tabela do BigQuery.
2. Chart Creator: acionado quando o serviço Query Runner publica uma mensagem num tópico do Pub/Sub, este serviço gera gráficos através da biblioteca de representação gráfica Python, Matplotlib, e guarda os gráficos num contentor do Cloud Storage.
3. Notifier: acionado pelos registos de auditoria quando o serviço Chart Creator armazena um gráfico num contentor do Cloud Storage. Este serviço usa o serviço de email, SendGrid, para enviar links para os gráficos para um endereço de email.

O diagrama seguinte mostra a arquitetura de alto nível:

Nota: todos os serviços do Cloud Run são implementados de forma privada por predefinição, o que significa que não é possível aceder aos mesmos sem fornecer credenciais de autenticação no pedido. Para projetos com políticas organizacionais de partilha restrita por domínio, use um serviço de destino do Cloud Run autenticado em vez de um que permita o acesso público (não autenticado).

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• BigQuery
• Cloud Build
• Cloud Run
• Cloud Scheduler
• Cloud Storage
• Eventarc
• Pub/Sub

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir a conclusão dos seguintes passos. Para informações de resolução de problemas, consulte o artigo Desenvolva aplicações num ambiente Google Cloud restrito.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Logging, Cloud Run, Cloud Scheduler, Eventarc, and Pub/Sub APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com cloudscheduler.googleapis.com eventarc.googleapis.com logging.googleapis.com pubsub.googleapis.com run.googleapis.com

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Logging, Cloud Run, Cloud Scheduler, Eventarc, and Pub/Sub APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com cloudscheduler.googleapis.com eventarc.googleapis.com logging.googleapis.com pubsub.googleapis.com run.googleapis.com

1. Para o Cloud Storage, ative o registo de auditoria para os tipos de acesso aos dados ADMIN_READ, DATA_WRITE e DATA_READ.
   1. Leia a Política de gestão de identidade e de acesso (IAM) associada ao seu Google Cloud projeto, pasta ou organização e armazene-a num ficheiro temporário:

      gcloud projects get-iam-policy PROJECT_ID > /tmp/policy.yaml

   2. Num editor de texto, abra /tmp/policy.yaml e adicione ou altere apenas a configuração do registo de auditoria na secção auditConfigs:
      Atenção: tem de preservar as secções bindings: e etag: sem alterações. A alteração de partes da sua política não relacionadas com o registo de auditoria pode tornar o seu Google Cloud projeto inacessível
      .

      
        auditConfigs:
        - auditLogConfigs:
          - logType: ADMIN_READ
          - logType: DATA_WRITE
          - logType: DATA_READ
          service: storage.googleapis.com
        bindings:
        - members:
        [...]
        etag: BwW_bHKTV5U=
        version: 1

   3. Escreva a sua nova Política IAM:

      gcloud projects set-iam-policy PROJECT_ID /tmp/policy.yaml

      Se o comando anterior comunicar um conflito com outra alteração, repita estes passos, começando pela leitura da política de IAM. Para mais informações, consulte o artigo Configure registos de auditoria de acesso aos dados com a API.

2. Conceda a função eventarc.eventReceiver à conta de serviço do Compute Engine:

   export PROJECT_NUMBER="$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')"
   
   gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
       --member=serviceAccount:${PROJECT_NUMBER}[e-mail] \
       --role='roles/eventarc.eventReceiver'

3. Se ativou a conta de serviço do Pub/Sub a 8 de abril de 2021 ou antes, conceda a função iam.serviceAccountTokenCreator à conta de serviço do Pub/Sub:

   gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
       --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com"\
       --role='roles/iam.serviceAccountTokenCreator'

4. Defina as predefinições usadas neste tutorial:

   export REGION=REGION
   gcloud config set run/region ${REGION}
   gcloud config set run/platform managed
   gcloud config set eventarc/location ${REGION}

   Substitua REGION pela localização do Eventarc suportada à sua escolha.

Crie uma chave da API SendGrid

O SendGrid é um fornecedor de email baseado na nuvem que lhe permite enviar emails sem ter de manter servidores de email.

1. Inicie sessão no SendGrid e aceda a Settings > API Keys.
2. Clique em Criar chave da API.
3. Selecione as autorizações para a chave. No mínimo, a chave tem de ter autorizações de Envio de correio para enviar emails.
4. Atribua um nome à chave e, para a criar, clique em Guardar.
5. O SendGrid gera uma nova chave. Esta é a única cópia da chave, por isso, certifique-se de que a copia e a guarda para mais tarde.

Crie um repositório padrão do Artifact Registry

Crie um repositório padrão do Artifact Registry para armazenar a imagem do contentor Docker:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Substitua REPOSITORY por um nome exclusivo para o repositório.

Crie um contentor do Cloud Storage

Crie um contentor do Cloud Storage único para guardar os gráficos. Certifique-se de que o contentor e os gráficos estão disponíveis publicamente e na mesma região que o seu serviço do Cloud Run:

export BUCKET="$(gcloud config get-value core/project)-charts"
gcloud storage buckets create gs://${BUCKET} --location=$(gcloud config get-value run/region)
gcloud storage buckets update gs://${BUCKET} --uniform-bucket-level-access
gcloud storage buckets add-iam-policy-binding gs://${BUCKET} --member=allUsers --role=roles/storage.objectViewer

Implemente o serviço Notifier

Implemente um serviço do Cloud Run que receba eventos do Chart Creator e use o SendGrid para enviar por email links para os gráficos gerados.

1. Clone o repositório do GitHub e mude para o diretório notifier/python:

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples
   cd eventarc-samples/processing-pipelines/bigquery/notifier/python/

2. Crie e envie a imagem de contentor:

   export SERVICE_NAME=notifier
   docker build -t $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1 .
   docker push $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1

3. Implemente a imagem do contentor no Cloud Run, transmitindo um endereço para o qual enviar emails e a chave da API SendGrid:

   export TO_EMAILS=EMAIL_ADDRESS
   export SENDGRID_API_KEY=YOUR_SENDGRID_API_KEY
   gcloud run deploy ${SERVICE_NAME} \
       --image $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1 \
       --update-env-vars TO_EMAILS=${TO_EMAILS},SENDGRID_API_KEY=${SENDGRID_API_KEY},BUCKET=${BUCKET} \
       --allow-unauthenticated

   Substitua o seguinte:

   • EMAIL_ADDRESS com um endereço de email para enviar os links para os gráficos gerados
   • YOUR_SENDGRID_API_KEY com a chave da API SendGrid que anotou anteriormente

Quando vir o URL do serviço, a implementação está concluída.

Nota: pode demorar alguns minutos até que as autorizações sejam propagadas ao serviço e antes de poder criar um acionador.

Crie um acionador para o serviço Notifier

O acionador do Eventarc para o serviço Notifier implementado no Cloud Run filtra os registos de auditoria do Cloud Storage onde methodName é storage.objects.create.

1. Crie o acionador:

   gcloud eventarc triggers create trigger-${SERVICE_NAME} \
       --destination-run-service=${SERVICE_NAME} \
       --destination-run-region=${REGION} \
       --event-filters="type=google.cloud.audit.log.v1.written" \
       --event-filters="serviceName=storage.googleapis.com" \
       --event-filters="methodName=storage.objects.create" \
       --service-account=${PROJECT_NUMBER}[e-mail]

   Esta ação cria um acionador denominado trigger-notifier.

Implemente o serviço Chart Creator

Implemente um serviço do Cloud Run que receba eventos do Query Runner, obtenha dados de uma tabela do BigQuery para um país específico e, em seguida, gere um gráfico, através do Matplotlib, a partir dos dados. O gráfico é carregado para um contentor do Cloud Storage.

1. Altere para o diretório chart-creator/python:

   cd ../../chart-creator/python

2. Crie e envie a imagem de contentor:

   export SERVICE_NAME=chart-creator
   docker build -t $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1 .
   docker push $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1

3. Implemente a imagem do contentor no Cloud Run, transmitindo BUCKET:

   gcloud run deploy ${SERVICE_NAME} \
       --image $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1 \
       --update-env-vars BUCKET=${BUCKET} \
       --allow-unauthenticated

Quando vir o URL do serviço, a implementação está concluída.

Crie um acionador para o serviço Chart Creator

O acionador do Eventarc para o serviço Chart Creator implementado no Cloud Run filtra mensagens publicadas num tópico do Pub/Sub.

1. Crie o acionador:

   gcloud eventarc triggers create trigger-${SERVICE_NAME} \
       --destination-run-service=${SERVICE_NAME} \
       --destination-run-region=${REGION} \
       --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished"

   Esta ação cria um acionador denominado trigger-chart-creator.

2. Defina a variável de ambiente do tópico Pub/Sub.

   export TOPIC_QUERY_COMPLETED=$(basename $(gcloud eventarc triggers describe trigger-${SERVICE_NAME} --format='value(transport.pubsub.topic)'))

Implemente o serviço Query Runner

Implemente um serviço do Cloud Run que receba eventos do Cloud Scheduler, obtenha dados de um conjunto de dados público da COVID-19 e guarde os resultados numa nova tabela do BigQuery.

1. Altere para o diretório processing-pipelines:

   cd ../../..

2. Crie e envie a imagem de contentor:

   export SERVICE_NAME=query-runner
   docker build -t $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1 -f Dockerfile .
   docker push $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1

3. Implemente a imagem de contentor no Cloud Run, transmitindo PROJECT_ID e TOPIC_QUERY_COMPLETED:

   gcloud run deploy ${SERVICE_NAME} \
       --image $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/${SERVICE_NAME}:v1 \
       --update-env-vars PROJECT_ID=$(gcloud config get-value project),TOPIC_ID=${TOPIC_QUERY_COMPLETED} \
       --allow-unauthenticated

Quando vir o URL do serviço, a implementação está concluída.

Crie um acionador para o serviço Query Runner

O acionador do Eventarc para o serviço Query Runner implementado no Cloud Run filtra mensagens publicadas num tópico do Pub/Sub.

1. Crie o acionador:

   gcloud eventarc triggers create trigger-${SERVICE_NAME} \
       --destination-run-service=${SERVICE_NAME} \
       --destination-run-region=${REGION} \
       --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished"

   Esta ação cria um acionador denominado trigger-query-runner.

2. Defina uma variável de ambiente para o tópico do Pub/Sub.

   export TOPIC_QUERY_SCHEDULED=$(gcloud eventarc triggers describe trigger-${SERVICE_NAME} --format='value(transport.pubsub.topic)')

Agende as tarefas

O pipeline de processamento é acionado por duas tarefas do Cloud Scheduler.

1. Crie uma app do App Engine que é necessária para o Cloud Scheduler e especifique uma localização adequada:

   export APP_ENGINE_LOCATION=LOCATION
   gcloud app create --region=${APP_ENGINE_LOCATION}

2. Crie duas tarefas do Cloud Scheduler que publiquem num tópico do Pub/Sub uma vez por dia:

   gcloud scheduler jobs create pubsub cre-scheduler-uk \
       --schedule="0 16 * * *" \
       --topic=${TOPIC_QUERY_SCHEDULED} \
       --message-body="United Kingdom"

   gcloud scheduler jobs create pubsub cre-scheduler-cy \
       --schedule="0 17 * * *" \
       --topic=${TOPIC_QUERY_SCHEDULED} \
       --message-body="Cyprus"

   A programação é especificada no formato unix-cron. Por exemplo, 0 16 * * * significa que as tarefas são executadas às 16:00 (16:00) UTC todos os dias.

Execute a pipeline

1. Primeiro, confirme se todos os acionadores foram criados com êxito:

   gcloud eventarc triggers list

   Nota: pode demorar até dois minutos para que os acionadores fiquem totalmente funcionais.

   O resultado deve ser semelhante ao seguinte:

   NAME: trigger-chart-creator
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: Cloud Run service: chart-creator
   ACTIVE: Yes
   LOCATION: us-central1
   
   NAME: trigger-notifier
   TYPE: google.cloud.audit.log.v1.written
   DESTINATION: Cloud Run service: notifier
   ACTIVE: Yes
   LOCATION: us-central1
   
   NAME: trigger-query-runner
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: Cloud Run service: query-runner
   ACTIVE: Yes
   LOCATION: us-central1
   

2. Recupere os IDs das tarefas do Cloud Scheduler:

   gcloud scheduler jobs list

   O resultado deve ser semelhante ao seguinte:

   ID                LOCATION      SCHEDULE (TZ)         TARGET_TYPE  STATE
   cre-scheduler-cy  us-central1   0 17 * * * (Etc/UTC)  Pub/Sub      ENABLED
   cre-scheduler-uk  us-central1   0 16 * * * (Etc/UTC)  Pub/Sub      ENABLED
   

3. Embora as tarefas estejam agendadas para serem executadas diariamente às 16:00 e às 17:00, também pode executar as tarefas do Cloud Scheduler manualmente:

   gcloud scheduler jobs run cre-scheduler-cy
   gcloud scheduler jobs run cre-scheduler-uk

4. Após alguns minutos, confirme que existem dois gráficos no contentor do Cloud Storage:

   gcloud storage ls gs://${BUCKET}

   O resultado deve ser semelhante ao seguinte:

   gs://BUCKET/chart-cyprus.png
   gs://BUCKET/chart-unitedkingdom.png
   

Parabéns! Também deve receber dois emails com links para as tabelas.

Limpar

Se criou um novo projeto para este tutorial, elimine-o. Se usou um projeto existente e quiser mantê-lo sem as alterações adicionadas neste tutorial, elimine os recursos criados para o tutorial.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimine recursos de tutoriais

1. Elimine todos os serviços do Cloud Run que implementou neste tutorial:

   gcloud run services delete SERVICE_NAME

   Onde SERVICE_NAME é o nome do serviço escolhido.

   Também pode eliminar serviços do Cloud Run a partir da Google Cloud consola.

2. Remova todas as configurações predefinidas da CLI Google Cloud que adicionou durante a configuração do tutorial.

   gcloud config unset project
   gcloud config unset run/region
   gcloud config unset run/platform
   gcloud config unset eventarc/location

3. Elimine todos os acionadores do Eventarc que criou neste tutorial:

    gcloud eventarc triggers delete TRIGGER_NAME
    

   Substitua TRIGGER_NAME pelo nome do seu acionador.

4. Elimine as imagens do Artifact Registry.

   gcloud artifacts docker images delete $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/notifier:v1
   gcloud artifacts docker images delete $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/chart-creator:v1
   gcloud artifacts docker images delete $REGION-docker.pkg.dev/$(gcloud config get-value project)/REPOSITORY/query-runner:v1

5. Elimine o contentor, juntamente com todos os objetos no contentor:

   gcloud storage rm --recursive gs://${BUCKET}/

6. Elimine as tarefas do Cloud Scheduler:

   gcloud scheduler jobs delete cre-scheduler-cy
   gcloud scheduler jobs delete cre-scheduler-uk

O que se segue?

• Saiba mais sobre o Eventarc
• Saiba mais sobre o Cloud Run