Publicar eventos diretamente

Avançado

É possível publicar um evento do CloudEvents diretamente em um barramento Eventarc Advanced em um formato compatível usando a CLI do Google Cloud ou enviando uma solicitação para a API REST de publicação do Eventarc. Você também pode usar as bibliotecas de cliente do Eventarc para acessar as APIs do Eventarc em uma linguagem compatível.

Antes de começar

Antes de começar, verifique se você concluiu as etapas a seguir:

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.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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 role (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 Eventarc and Eventarc Publishing 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

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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 role (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 Eventarc and Eventarc Publishing 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

Publicar diretamente

A mensagem de evento que você publica diretamente precisa estar em conformidade com a especificação do CloudEvents.

gcloud

1. Abra um terminal.

2. É possível publicar eventos em um barramento usando o comando gcloud eventarc message-buses publish. Exemplo:

   gcloud eventarc message-buses publish BUS_NAME \
       --avro-message=AVRO_MESSAGE

   Ou:
   gcloud eventarc message-buses publish BUS_NAME \
       --json-message=JSON_MESSAGE

   Ou:
   gcloud eventarc message-buses publish BUS_NAME \
       --event-data=DATA_PAYLOAD \
       --event-id=EVENT_ID \
       --event-source=EVENT_SOURCE \
       --event-type=EVENT_TYPE \
       --event-attributes=EVENT_ATTRIBUTE

   Substitua:

   • BUS_NAME: o ID ou identificador totalmente qualificado do barramento em que o evento será publicado.

   Use apenas uma das seguintes opções:

   • AVRO_MESSAGE: a mensagem de evento em um formato Avro de acordo com esta especificação.
   • JSON_MESSAGE: a mensagem de evento em formato JSON de acordo com esta especificação.
   • DATA_PAYLOAD: os dados de um evento publicado.

   Se você usar a flag --event-data, também precisará usar o seguinte:

   • EVENT_ID: o identificador do evento. Os produtores de eventos precisam garantir que source + id seja exclusivo para cada evento distinto.
   • EVENT_SOURCE: a origem do evento de um evento publicado.
   • EVENT_TYPE: o tipo de evento relacionado à ocorrência de origem.

   Se você estiver usando a flag --event-data, poderá usar as seguintes opções:

   • EVENT_ATTRIBUTE: os atributos de um evento publicado. Você pode repetir a flag --event-attributes para adicionar mais atributos.

     Os eventos podem incluir qualquer número de atributos personalizados adicionais do CloudEvents com nomes distintos, também conhecidos como atributos de extensão.

Exemplos:

gcloud eventarc message-buses publish my-bus \
    --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"

gcloud eventarc message-buses publish my-bus --json-message='{
    "specversion" : "1.0",
    "type" :"com.example.someevent",
    "source" : "google.cloud.storage.object.v1.finalized",
    "id" : "A234-1234-1234",
    "time" : "2024-04-05T17:31:00Z",
    "bucket" : "bucketName",
    "datacontenttype" : "application/json",
    "data":{"key": "value"}
}'

API REST

Para publicar um evento em um barramento, use o método projects.locations.messageBuses.publish.

Observação: no ProtoMessage do corpo da solicitação, o campo protoData só funciona como esperado quando o payload é especificamente um tipo de mensagem CloudEvent e não pode ser usado para mensagens arbitrárias de buffer de protocolo. Para qualquer outro tipo de buffer de protocolo, é necessário serializar a mensagem proto em bytes e usar o campo binaryData.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• O nome completo do recurso do ônibus no formato projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME

  Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud para o projeto de ônibus.
  • LOCATION: a região em que o barramento é implantado, por exemplo, us-central1.
  • BUS_NAME: o nome do barramento em que o evento será publicado.
• SPEC_VERSION: a versão da especificação CloudEvents que o evento usa. Por exemplo, 1.0.
• EVENT_TYPE: o tipo de evento relacionado à ocorrência de origem.
• EVENT_SOURCE: a origem do evento de um evento publicado.
• EVENT_ID: o identificador do evento. Os produtores precisam garantir que source + id seja exclusivo para cada evento distinto.
• CONTENT_TYPE (opcional): o tipo de conteúdo do valor data. Se um evento no formato JSON não tiver um atributo datacontenttype, será considerado que os dados são um valor JSON em conformidade com o tipo de mídia application/json.
• DATA_PAYLOAD (opcional): o payload do evento codificado no formato de mídia especificado por datacontenttype e seguindo dataschema quando esses atributos estão presentes.

Corpo JSON da solicitação:

{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://eventarcpublishing.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME:publish"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://eventarcpublishing.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME:publish" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Se a solicitação for bem-sucedida, o servidor vai retornar um código de status HTTP 200 OK e o corpo da resposta vazio no formato JSON:

200 OK

{}

A seguir

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