Publique e receba eventos criando um barramento e uma inscrição (CLI gcloud)

Publique e receba eventos criando um barramento e uma inscrição (CLI gcloud)

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 autocarro permite-lhe centralizar o fluxo de mensagens através do seu sistema e funciona como um router. Recebe mensagens de eventos de uma origem de mensagens ou publicadas por um fornecedor e avalia-as de acordo com uma inscrição.

• Uma inscrição identifica uma subscrição de um barramento específico e define os critérios de correspondência para mensagens, fazendo com que sejam encaminhadas em conformidade para um ou mais destinos.

Neste início rápido, vai:

1. Crie um repositório padrão do Artifact Registry.

2. Implemente um serviço de receção de eventos no Cloud Run.

3. Crie um barramento avançado do Eventarc.

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

5. Publicar uma mensagem de evento no barramento.

6. Veja os dados de eventos nos registos do Cloud Run.

Pode concluir este guia de início rápido através da CLI gcloud. Para concluir os passos através da Google Cloud consola, consulte Publique e receba eventos criando um barramento e uma inscrição (consola).

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 Artifact Registry, Cloud Build, Cloud Run, Compute Engine, 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 artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com 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 Artifact Registry, Cloud Build, Cloud Run, Compute Engine, 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 artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com 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.

4. Se for o criador do projeto, é-lhe atribuída 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).

   Tenha em atenção que, por predefinição, as autorizações do Cloud Build incluem autorizações para carregar e transferir artefactos do Artifact Registry.

   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:

   • Editor do Cloud Build (roles/cloudbuild.builds.editor)
   • Administrador do Cloud Run (roles/run.admin)
   • 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. Conceda as seguintes funções no projeto à conta de serviço predefinida do Compute Engine. Estas funções são necessárias quando cria e implementa a sua imagem de contentor:
   • Escritor do Artifact Registry: para carregar artefactos do Artifact Registry
   • Escritor de registos: para escrever registos no Cloud Logging
   • Utilizador do objeto de armazenamento: para aceder a objetos do Cloud Storage

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/artifactregistry.writer
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/logging.logWriter
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/storage.objectUser

   Substitua PROJECT_NUMBER pelo seu Google Cloud número do projeto. Pode encontrar o número do projeto na página Boas-vindas da Google Cloud consola ou executando o seguinte comando:

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

6. Por predefinição, apenas os proprietários do projeto, os editores do projeto e os administradores e invocadores do Cloud Run podem chamar serviços do Cloud Run.
   Para configurar a autenticação, conceda a função de invocador do Cloud Run (run.invoker) no seu Google 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

   Tenha em atenção que pode configurar quem pode aceder ao seu serviço do Cloud Run de uma das seguintes formas:

   • Conceda autorização a contas de serviço ou grupos selecionados para permitir o acesso ao serviço. Todos os pedidos têm de ter um cabeçalho de autorização HTTP que contenha um token do OpenID Connect assinado pela Google para uma das contas de serviço autorizadas. Esta é a forma como o acesso é configurado neste início rápido.
   • Conceda autorização a allUsers para permitir o acesso não autenticado.

   Para mais informações, consulte o artigo Controlo de acesso para o Cloud Run.

Crie um repositório padrão do Artifact Registry

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

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

Substitua REPOSITORY por um nome exclusivo para o repositório do Artifact Registry, por exemplo, my-repo.

Implemente um serviço de receção de eventos no Cloud Run

Implemente um serviço do Cloud Run que regista o conteúdo de um evento. São suportados outros destinos de eventos, como um tópico do Pub/Sub, fluxos de trabalho ou um ponto final de HTTP. Para mais informações, consulte Fornecedores e destinos de eventos.

1. Clone o repositório do GitHub:

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

2. Altere para o diretório que contém o código de exemplo do Cloud Run:

   cd eventarc-samples/eventarc-advanced-quickstart/

3. Crie uma imagem de contentor do Docker e envie a imagem para o seu repositório:

   gcloud builds submit \
       --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1

4. Implemente a imagem do contentor no Cloud Run:

   gcloud run deploy SERVICE_NAME \
       --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --platform managed \
       --ingress all \
       --no-allow-unauthenticated \
       --region=$REGION

   Substitua SERVICE_NAME pelo nome do seu serviço, por exemplo, my-service.

   A definição de entrada de all permite todos os pedidos, incluindo pedidos diretamente da Internet para o URL run.app. Para mais informações, consulte o artigo Restrinja a entrada de rede para o Cloud Run.

   A flag --no-allow-unauthenticated configura o serviço para permitir apenas invocações autenticadas.

Quando vir o URL do serviço do Cloud Run, a implementação está concluída. Anote este URL para o poder usar num passo subsequente.

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 ou identificador totalmente qualificado do seu autocarro, por exemplo, my-bus.

Crie uma inscrição avançada do Eventarc

Uma inscrição determina as mensagens que são encaminhadas para um destino e também especifica o pipeline usado para configurar um destino para as mensagens de eventos.

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='CLOUD_RUN_SERVICE_URL',google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --location=$REGION

   Substitua o seguinte:

   • PIPELINE_NAME: o ID do pipeline ou um nome totalmente qualificado.
   • CLOUD_RUN_SERVICE_URL: o URL totalmente qualificado do seu serviço do Cloud Run, por exemplo, https://SERVICE_NAME-abcdef-uc.a.run.app. Este é o destino das mensagens de eventos.

   Tenha em atenção que a chave google_oidc_authentication_service_account especifica um endereço de email da conta de serviço que é usado para gerar um token OIDC.

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.

   • 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, pode usar o comando gcloud eventarc message-buses publish ou enviar 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, que é 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

Pode publicar 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

Pode publicar 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 barramento avançado do Eventarc, pode verificar os registos do seu serviço 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: '2024-10-10T17:03:35.424659450Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
     }'"
   timestamp: '2024-10-10T17:03:35.177606Z'
   

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

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 serviço de receção de eventos.

Limpar

Quando concluir as tarefas descritas neste início rápido, pode evitar a faturação contínua eliminando os recursos que criou:

1. Elimine um repositório do Artifact Registry.

2. Elimine um serviço do Cloud Run.

3. Elimine recursos avançados do Eventarc:

   1. Elimine uma inscrição.

   2. Elimine um pipeline.

   3. Elimine um autocarro.

Em alternativa, pode eliminar o seu Google Cloud projeto para evitar incorrer em 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