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 do código-fonte.

2. Crie um barramento do Eventarc Advanced.

3. Crie um registro do Eventarc Advanced.

4. Publique uma mensagem de evento no barramento.

5. Confirme se o job do Cloud Run foi executado com sucesso.

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 .

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a CLI do Google Cloud.

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

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Artifact Registry, Cloud Build, Cloud Run e Eventarc:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

Instale a CLI do Google Cloud.

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

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Artifact Registry, Cloud Build, Cloud Run e Eventarc:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com 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:
   Observação: para executar um job que substitui a configuração do job (por exemplo, ao definir uma vinculação de mensagem), conceda o papel do IAM de Desenvolvedor do Cloud Run (roles/run.developer) ou Executor de jobs do Cloud Run com substituições (roles/run.jobsExecutorWithOverrides). Para mais informações, consulte Substituir a configuração do job para uma execução específica.
   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 do código-fonte

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.

Crie um job com o código-fonte Python usando o comando gcloud run jobs deploy. Seu código é automaticamente empacotado em uma imagem de contêiner, enviado para o Artifact Registry e implantado no Cloud Run.

1. Crie um diretório chamado jobs e navegue até ele:

   mkdir jobs
   cd jobs
   

2. Crie um arquivo main.py e copie o seguinte exemplo de código nele:

   import os
   
   TASK_INDEX = os.getenv("CLOUD_RUN_TASK_INDEX", 0)
   
   def main():
       """
       This job prints "Hello world"
       """
       print(f"Starting task #{TASK_INDEX}...")
       print("Hello world")
       print(f"Completed task #{TASK_INDEX}.")
   
   # Start script
   if __name__ == "__main__":
       main()
   

3. Crie um arquivo de texto chamado Procfile sem extensão de arquivo e copie o seguinte texto nele:

   web: python3 main.py
   

4. Implante o job:

   gcloud run jobs deploy JOB_NAME \
       --source . \
       --tasks 1 \
       --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 origem 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.

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

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

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

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='JOB_URI',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.

   • JOB_URI: o URI do job do Cloud Run no seguinte formato:

     https://REGION-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/PROJECT_NUMBER/jobs/JOB_NAME:run

     Para recuperar o número do projeto, execute o comando a seguir:

     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, configure um formato de entrada para acessar o payload. Por exemplo: {"body": ""}.
   • 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 seu 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.

Confirme se o job do Cloud Run foi executado com sucesso

Depois de publicar um evento no barramento avançado do Eventarc, verifique os registros do job do Cloud Run para verificar se ele foi executado com sucesso e se "Hello world" foi impresso. Pode levar alguns minutos para que o job seja executado e concluído.

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

   gcloud logging read 'textPayload: "Hello world"'
   

2. Procure uma entrada de registro semelhante a esta:

   insertId: 693c8dd0000cb2976d7966b8
   ...
   labels:
       job_name: JOB_NAME
       location: REGION
       project_id: PROJECT_ID
   type: cloud_run_job
   textPayload: Hello world
   timestamp: '2025-12-12T21:49:04.832151Z'
   

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

3. Você também pode confirmar 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 do Google Cloud interrompe o faturamento de todos os recursos usados nele.

Cuidado: a exclusão de 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.

Excluir um projeto do Google Cloud :

gcloud projects delete PROJECT_ID

A seguir

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