Publique eventos num trabalho do Cloud Run

Publique eventos num trabalho do Cloud Run

Avançadas

Este início rápido mostra como publicar e receber mensagens de eventos criando um bus avançado do Eventarc e uma inscrição no seu projeto Google Cloud.

• Um bus funciona como um router central, recebendo mensagens de origens de eventos ou publicadas por fornecedores.

• Uma inscrição encaminha as mensagens recebidas pelo barramento para um ou mais destinos através de um pipeline de processamento.

Neste início rápido, vai:

1. Implemente uma tarefa do Cloud Run.

2. Crie um barramento avançado do Eventarc.

3. Crie uma inscrição avançada do Eventarc.

4. Publicar uma mensagem de evento no barramento.

5. Veja os dados de eventos nos registos e confirme que a tarefa do Cloud Run foi executada com êxito.

Pode concluir este guia de início rápido através da CLI gcloud.

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.

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 Cloud Run and Eventarc 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 eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

Install the Google Cloud CLI.

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 Cloud Run and Eventarc 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 eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

1. Atualize os componentes de gcloud:

   gcloud components update

2. Inicie sessão com a sua conta:

   gcloud auth login

3. Defina a variável de configuração usada neste início rápido:

   REGION=REGION

   Substitua REGION por uma localização suportada para o autocarro, por exemplo, us-central1.

4. Se criou o projeto, tem a função básica de proprietário (roles/owner). Por predefinição, esta função do Identity and Access Management (IAM) inclui as autorizações necessárias para acesso total à maioria dos Google Cloud recursos, e pode ignorar este passo.

   Se não for o criador do projeto, as autorizações necessárias têm de ser concedidas no projeto ao principal adequado. Por exemplo, um principal pode ser uma Conta Google (para utilizadores finais) ou uma conta de serviço (para aplicações e cargas de trabalho de computação).

   Autorizações necessárias

   Para receber as autorizações de que precisa para concluir este início rápido, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:

   • Cloud Run Developer (roles/run.developer)
   • Eventarc Developer (roles/eventarc.developer)
   • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
   • Aceder à vista de registos (roles/logging.viewAccessor)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
   • Utilizador da conta de serviço (roles/iam.serviceAccountUser)
   • Administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin)

   Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

   Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

5. Para conceder ao Eventarc Advanced as autorizações necessárias para executar uma tarefa do Cloud Run, peça ao seu administrador para conceder a função IAM Cloud Run Invoker (roles/run.invoker) no seuGoogle Cloud projeto a uma conta de serviço:
   1. Crie uma conta de serviço. Para fins de teste, vai anexar esta conta de serviço a um pipeline avançado do Eventarc para representar a identidade do pipeline.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Substitua SERVICE_ACCOUNT_NAME por um nome para a sua conta de serviço.
   2. Conceda a função de IAM à conta de serviço:roles/run.invoker

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/run.invoker

Implemente uma tarefa do Cloud Run

Implemente um trabalho do Cloud Run como destino do evento. Ao contrário de um serviço do Cloud Run, que ouve e serve pedidos, uma tarefa do Cloud Run só executa as respetivas tarefas e termina quando concluída. Um trabalho não escuta nem responde a pedidos.

Outros destinos de eventos, como um tópico do Pub/Sub, fluxos de trabalho ou outro ponto final HTTP, são suportados. Para mais informações, consulte o artigo Fornecedores e destinos de eventos.

Implemente uma tarefa a partir de um contentor de exemplo através do comando gcloud run jobs deploy.

gcloud run jobs deploy JOB_NAME --image us-docker.pkg.dev/cloudrun/container/job:latest \
    --region=$REGION

Substitua JOB_NAME por um nome exclusivo para a tarefa do Cloud Run, por exemplo, my-job.

Crie um bus avançado do Eventarc

Um barramento recebe mensagens de eventos de uma origem de mensagens ou publicadas por um fornecedor e funciona como um router de mensagens.

Para mais informações, consulte o artigo Crie um autocarro para encaminhar mensagens.

Nota: pode criar um autocarro por Google Cloud projeto por região suportada.

Crie um bus avançado do Eventarc no seu projeto através do comando gcloud eventarc message-buses create:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

Substitua BUS_NAME pelo ID do seu autocarro ou por um nome totalmente qualificado, por exemplo, my-bus.

Crie uma inscrição avançada do Eventarc

Uma inscrição determina que mensagens são encaminhadas para um destino. Também especifica o pipeline usado para configurar o destino das mensagens de eventos. Neste caso, o destino é uma tarefa do Cloud Run.

Para mais informações, consulte o artigo Crie uma inscrição para receber eventos.

Nota: a criação de um pipeline pode demorar mais de 10 minutos.

Quando usa a CLI gcloud, primeiro cria um pipeline e, em seguida, cria uma inscrição:

1. Crie um pipeline com o comando gcloud eventarc pipelines create:

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://REGION-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/PROJECT_NUMBER/jobs/JOB_NAME:run',http_endpoint_message_binding_template='{"body": ""}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   Substitua o seguinte:

   • PIPELINE_NAME: o ID do pipeline ou um nome totalmente qualificado, por exemplo, my-pipeline.
   • PROJECT_NUMBER: o número do seu Google Cloud projeto. Pode obter o número do projeto executando o seguinte comando:

   gcloud projects describe PROJECT_ID --format='value(projectNumber)'

   Tenha em conta o seguinte:

   • A chave http_endpoint_message_binding_template transforma o evento no formato esperado pela API Admin do Cloud Run. Quando define uma associação de mensagens, tem de configurar um formato de entrada para aceder à carga útil.
   • A chave oauth_token_authentication_service_account especifica um email de conta de serviço. Este email é usado para gerar um token OAuth normalmente usado apenas quando chama APIs Google alojadas em *.googleapis.com.

2. Crie uma inscrição através do comando gcloud eventarc enrollments create:

   gcloud eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

   Substitua o seguinte:

   • ENROLLMENT_NAME: o ID da inscrição ou um nome totalmente qualificado, por exemplo, my-enrollment.

   • MATCH_EXPRESSION: a expressão de correspondência para esta inscrição usando o IEC, por exemplo:

     "message.type == 'hello-world-type'"
     

Publicar uma mensagem de evento no barramento

Para publicar diretamente uma mensagem no seu barramento, use o comando gcloud eventarc message-buses publish ou envie um pedido para a API REST Eventarc Publishing. Para mais informações, consulte o artigo Publique eventos diretamente.

A mensagem tem de estar num formato CloudEvents, uma especificação para descrever dados de eventos de forma comum. O elemento data é o payload do seu evento. Qualquer JSON bem formado pode ser colocado neste campo. Para mais informações sobre os atributos de contexto dos CloudEvents, consulte o artigo Formato de eventos.

Seguem-se exemplos de publicação direta de um evento num bus avançado do Eventarc:

Exemplo 1

Publique um evento num barramento através da CLI gcloud e de um --event-data e outras flags de atributos de eventos:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Exemplo 2

Publique um evento num barramento como uma mensagem JSON através da CLI gcloud e de uma flag --json-message:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Depois de publicar um evento, deve receber a mensagem "Evento publicado com êxito".

Veja os dados de eventos nos registos do Cloud Run

Depois de publicar um evento no seu barramento avançado do Eventarc, verifique os registos da sua tarefa do Cloud Run para confirmar que o evento foi recebido conforme esperado.

1. Filtre as entradas do registo e devolva a saída através do comando gcloud logging read:

   gcloud logging read 'textPayload: "hello-world-data"'
   

2. Procure uma entrada de registo semelhante à seguinte:

   insertId: 670808e70002b5c6477709ae
   labels:
   instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
   logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
   receiveTimestamp: '2025-10-06T21:15:22.988264020Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2025-10-06 21:15:22,676] INFO in server: Body: b'{\"key\": \"hello-world-data\"\
     }'"
   timestamp: '2025-10-06T21:15:22.675530Z'
   

   Nota: se não vir uma entrada de registo, aguarde alguns minutos e tente novamente o comando gcloud logging read.

3. Confirme que a tarefa do Cloud Run foi executada com êxito através do comando gcloud run jobs describe:

   gcloud run jobs describe JOB_NAME \
       --region=$REGION
   

   Deve receber um resultado semelhante ao seguinte:

   ✔ Job JOB_NAME in region us-central1
   Executed 1 time
   ...
   

Criou com êxito um barramento avançado do Eventarc e uma inscrição, publicou uma mensagem de evento no barramento e validou o resultado esperado nos registos do recetor de eventos.

Limpar

Para ajudar a evitar a faturação contínua após concluir este início rápido, elimine os recursos que criou:

1. Elimine uma tarefa do Cloud Run.

2. Elimine recursos avançados do Eventarc:

   1. Elimine uma inscrição.

   2. Elimine um pipeline.

   3. Elimine um autocarro.

Em alternativa, elimine o seu Google Cloud projeto para ajudar a evitar a incorrência de custos. A eliminação do seu Google Cloud projeto interrompe a faturação de todos os recursos usados nesse projeto.

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

O que se segue?

• Publique eventos de origens Google
• Publique eventos diretamente
• Transforme eventos recebidos
• Formate os eventos recebidos