Publicar eventos em um job do Cloud Run

Publicar eventos em um job do Cloud Run

Avançado

Neste guia de início rápido, mostramos como publicar e receber mensagens de eventos criando um barramento do Eventarc Advanced e fazendo a inscrição no seu projeto do Google Cloud.

• Um barramento atua como um roteador central, recebendo mensagens de fontes de eventos ou publicadas por provedores.

• Um registro encaminha as mensagens recebidas pelo barramento para um ou mais destinos por um pipeline de processamento.

Neste guia de início rápido, você fará as seguintes tarefas:

1. Implante um job do Cloud Run.

2. Crie um barramento do Eventarc Advanced.

3. Crie uma inscrição no Eventarc Advanced.

4. Publique uma mensagem de evento no barramento.

5. Confira os dados do evento nos registros e confirme se o job do Cloud Run foi executado com êxito.

Conclua este guia de início rápido usando a CLI gcloud.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir que você conclua as etapas a seguir. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito de Google Cloud .

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.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, 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.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, 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 gcloud:

   gcloud components update

2. Faça login usando sua conta:

   gcloud auth login

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

   REGION=REGION

   Substitua REGION por um local compatível para o ônibus, por exemplo, us-central1.

4. Se você for o criador do projeto, vai receber o papel de proprietário básico (roles/owner). Por padrão, esse papel do Identity and Access Management (IAM) inclui as permissões necessárias para acesso total à maioria dos recursos do Google Cloud, e você pode pular esta etapa.

   Se você não é o criador do projeto, as permissões necessárias precisam ser concedidas ao principal apropriado. Por exemplo, um principal pode ser uma Conta do Google (para usuários finais) ou uma conta de serviço (para aplicativos e cargas de trabalho de computação).

   Permissões necessárias

   Para conseguir as permissões necessárias a fim de concluir o guia de início rápido, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

   • Desenvolvedor do Cloud Run (roles/run.developer)
   • Desenvolvedor do Eventarc (roles/eventarc.developer)
   • Administrador de barramento de mensagem do Eventarc (roles/eventarc.messageBusAdmin)
   • Acessador de exibição de registros (roles/logging.viewAccessor)
   • Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
   • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
   • Usuário da conta de serviço (roles/iam.serviceAccountUser)
   • Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)

   Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

5. Para conceder ao Eventarc Advanced as permissões necessárias para executar um job do Cloud Run, peça ao administrador para conceder o papel do IAM de Invocador do Cloud Run (roles/run.invoker) no seu projetoGoogle Cloud a uma conta de serviço:
   1. Crie uma conta de serviço. Para fins de teste, você vai anexar essa conta de serviço a um pipeline do Eventarc Advanced para representar a identidade do pipeline.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

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

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

Implantar um job do Cloud Run

Implante um job do Cloud Run como destino do evento. Ao contrário de um serviço do Cloud Run, que detecta e atende a solicitações, um job do Cloud Run só executa as tarefas e sai quando termina. Um job não detecta nem exibe solicitações.

Outros destinos de eventos, como um tópico do Pub/Sub, Workflows ou outro endpoint HTTP, são aceitos. Para mais informações, consulte Provedores e destinos de eventos.

Implante um job de um contêiner de exemplo usando o 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 o job do Cloud Run, por exemplo, my-job.

Criar um barramento do Eventarc Advanced

Um barramento recebe mensagens de eventos de uma fonte de mensagens ou publicadas por um provedor e atua como um roteador de mensagens.

Para mais informações, consulte Criar um barramento para rotear mensagens.

Observação: é possível criar um barramento por Google Cloud projeto por região compatível.

Crie um barramento do Eventarc Advanced no seu projeto usando o comando gcloud eventarc message-buses create:

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

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

Criar uma inscrição no Eventarc Advanced

Uma inscrição determina quais mensagens são encaminhadas para um destino. Ele também especifica o pipeline usado para configurar o destino das mensagens de evento. Nesse caso, o destino é um job do Cloud Run.

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

Observação: a criação de um pipeline pode levar mais de 10 minutos.

Ao usar a CLI gcloud, primeiro crie um pipeline e depois crie uma inscrição:

1. Crie um pipeline usando 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:

   • PIPELINE_NAME: o ID do pipeline ou um nome totalmente qualificado, por exemplo, my-pipeline.
   • PROJECT_NUMBER: o número do projeto Google Cloud . Para recuperar o número do projeto, execute o seguinte comando:

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

   Observe o seguinte:

   • A chave http_endpoint_message_binding_template transforma o evento no formato esperado pela API Cloud Run Admin. Ao definir uma vinculação de mensagem, é necessário configurar um formato de entrada para acessar o payload.
   • A chave oauth_token_authentication_service_account especifica um e-mail de conta de serviço. Esse e-mail é usado para gerar um token OAuth, geralmente usado apenas ao chamar APIs do Google hospedadas em *.googleapis.com.

2. Crie uma inscrição usando o 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:

   • 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 CEL. Por exemplo:

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

Publicar uma mensagem de evento no barramento

Para publicar uma mensagem diretamente no barramento, use o comando gcloud eventarc message-buses publish ou envie uma solicitação para a API REST de publicação do Eventarc. Para mais informações, consulte Publicar eventos diretamente.

A mensagem precisa estar no formato CloudEvents, uma especificação para descrever dados de eventos de uma maneira comum. O elemento data é a payload do seu evento. Qualquer JSON bem formado pode ser inserido nesse campo. Para mais informações sobre atributos de contexto do CloudEvents, consulte Formato de evento.

Confira a seguir exemplos de publicação direta de um evento em um barramento do Eventarc Advanced:

Exemplo 1

Publique um evento em um barramento usando a CLI gcloud e um --event-data e outras flags de atributo de evento:

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 em um barramento como uma mensagem JSON usando a CLI gcloud e 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, você vai receber uma mensagem informando que ele foi publicado com sucesso.

Ver os dados de eventos nos registros do Cloud Run

Depois de publicar um evento no barramento do Eventarc Advanced, verifique os registros do seu job do Cloud Run para verificar se o evento foi recebido conforme o esperado.

1. Filtre as entradas de registro e retorne a saída usando o comando gcloud logging read:

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

2. Procure uma entrada de registro semelhante a esta:

   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'
   

   Observação: se não aparecer uma entrada de registro, aguarde alguns minutos e tente novamente o comando gcloud logging read.

3. Confirme se o job do Cloud Run foi executado com sucesso usando o comando gcloud run jobs describe:

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

   Será exibida uma saída semelhante à exibida a seguir.

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

Você criou um barramento e um registro do Eventarc Advanced, publicou uma mensagem de evento no barramento e verificou o resultado esperado nos registros do receptor de eventos.

Limpar

Para evitar o faturamento contínuo depois de concluir este guia de início rápido, exclua os recursos criados:

1. Exclua um job do Cloud Run.

2. Exclua os recursos do Eventarc Advanced:

   1. Excluir um registro.

   2. Excluir um pipeline.

   3. Excluir um ônibus.

Se preferir, exclua o Google Cloud projeto para evitar cobranças. A exclusão do projeto Google Cloud interrompe o faturamento de todos os recursos usados nele.

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

A seguir

• Publicar eventos de fontes do Google
• Publicar eventos diretamente
• Transformar eventos recebidos
• Formatar eventos recebidos