Formato CloudEvents: associação do protocolo HTTP

O CloudEvents (cloudevents.io) é uma especificação para descrever dados de eventos de uma forma comum. A especificação está sob a Cloud Native Computing Foundation (CNCF) e é organizada pelo Serverless Working Group da CNCF.

O Eventarc envia eventos para o recetor de eventos no formato CloudEvents através de um pedido HTTP.

Cabeçalhos de pedidos HTTP

Os serviços de destino recebem eventos de routers de eventos como pedidos HTTP POST formatados para a versão 1.0 da especificação de associação do protocolo HTTP. Cada pedido HTTP contém cabeçalhos e um corpo específicos do evento e é enviado para o caminho do URL raiz (/) do serviço.

Além de outros cabeçalhos HTTP, todos os eventos têm os seguintes cabeçalhos HTTP CloudEvents:

Cabeçalho Descrição Exemplo
ce-id Identificador exclusivo do evento 1096434104173400
ce-source Identifica a origem do evento //pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion A versão da especificação CloudEvents usada para este evento 1.0
ce-type O tipo de dados de eventos google.cloud.pubsub.topic.v1.messagePublished
ce-time Hora de geração do evento, no formato RFC 3339 (opcional) 2020-12-20T13:37:33.647Z

Formato de payload HTTP

Cloud Audit Logs

Os eventos do tipo google.cloud.audit.log.v1.written têm o seguinte formato:

Cabeçalhos

ce-specversion: 1.0
ce-type: google.cloud.audit.log.v1.written
ce-source: //SERVICE_NAME/projects/PROJECT_ID
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • SERVICE_NAME: o URI da API Google para o serviço que emite o evento; por exemplo, bigquery.googleapis.com para eventos do BigQuery.
  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: gerado pelo sistema.

Corpo

O payload é um objeto JSON que detalha o evento dos registos de auditoria da nuvem. Em protoPayload, pode encontrar os valores resourceName, serviceName e methodName. Para mais informações, consulte o artigo Determine os filtros de eventos para os registos de auditoria do Cloud.

Pub/Sub

Os eventos do tipo google.cloud.pubsub.topic.v1.messagePublished têm o seguinte formato:

Cabeçalhos

ce-specversion: 1.0
ce-type: google.cloud.pubsub.topic.v1.messagePublished
ce-source: //pubsub.googleapis.com/TOPIC
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • TOPIC: o tópico do Pub/Sub no qual o evento foi publicado.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: gerado pelo sistema.

Corpo

A carga útil é uma mensagem push do Pub/Sub. No campo data, pode encontrar a mensagem como uma string codificada em Base64. Consulte o exemplo neste documento.

Repositório de código aberto

A estrutura do corpo HTTP para todos os eventos está disponível no repositório do GitHub CloudEvents.

O repositório contém o seguinte para ajudar a compreender e usar os dados do CloudEvents na sua linguagem de programação:

  • Buffers de protocolo da Google para payloads de dados de CloudEvents
  • Esquemas JSON gerados
  • Um catálogo de esquemas JSON público

Também estão incluídos links para bibliotecas cliente.

Eventos comuns

Os Protocol Buffers (ou protobufs) representam os dados nos eventos gerados pelo Eventarc. Os Protocol Buffers para CloudEvents são fornecidos como esquemas legíveis por máquina, o que permite criar bibliotecas de tipos de dados e facilita o consumo de eventos.

Existem duas mensagens protobuf relevantes para qualquer tipo de CloudEvent:

  • A mensagem envelope que representa o CloudEvent completo, incluindo quaisquer atributos de extensão; por exemplo, AuditLogWrittenEvent.
  • A mensagem de dados; por exemplo, LogEntryData ou StorageObjectData.
Muitos tipos de CloudEvent podem usar a mesma mensagem de dados. Por exemplo, todos os eventos associados a um objeto do Cloud Storage usam StorageObjectData como mensagem de dados. Cada mensagem de envelope especifica o tipo de CloudEvent ao qual está associada através de uma anotação proto. Para mais informações, consulte o artigo Relação entre mensagens protobuf e tipos de CloudEvent.

As tabelas seguintes detalham os componentes de alguns eventos comuns:

Cloud Audit Logs

Ficheiros Protogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Mensagem de envelopegoogle.events.cloud.audit.v1.AuditLogWrittenEvent
Mensagem de dadosgoogle.events.cloud.audit.v1.LogEntryData
Tipo de evento
(quando é escrita uma entrada do registo de auditoria)		 google.cloud.audit.log.v1.written
Extensões de eventos
  • serviceName
  • methodName
  • resourceName
Consulte a lista de tipos de eventos que usam os registos de auditoria do Cloud.
Exemplos Registo de auditoria do Pub/Sub
Registo de auditoria do BigQuery
Mais informações Crie um acionador do Eventarc para um evento dos registos de auditoria da nuvem
Determine os filtros de eventos para os registos de auditoria da nuvem
Google Cloud serviços com registos de auditoria

Cloud Storage

Ficheiros Proto google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
Mensagens de envelopegoogle.events.cloud.storage.v1.ObjectFinalizedEvent
google.events.cloud.storage.v1.ObjectArchivedEvent
google.events.cloud.storage.v1.ObjectDeletedEvent
google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
Mensagem de dadosgoogle.events.cloud.storage.v1.StorageObjectData
Recurso Objects
Tipos de eventos
 Consulte a lista de tipos de eventos diretos.
Exemplos Simples
Complexo
Mais informações Crie um acionador do Eventarc para um evento do Cloud Storage
Receba eventos do Cloud Storage num serviço do Cloud Run

Firestore

Ficheiros Proto google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
Mensagens de envelopegoogle.events.cloud.firestore.v1.DocumentCreatedEvent
google.events.cloud.firestore.v1.DocumentUpdatedEvent
google.events.cloud.firestore.v1.DocumentDeletedEvent
google.events.cloud.firestore.v1.DocumentWrittenEvent
Mensagem de dadosgoogle.events.cloud.firestore.v1.DocumentEventData
Recurso Document
Tipos de eventos Consulte a lista de tipos de eventos diretos.
Exemplos Simples
Complexo
Mais informações Crie um acionador do Eventarc para um evento do Firestore
Crie arquiteturas orientadas por eventos com o Eventarc e o Firestore
Faça a extensão com funções do Cloud Run para processar eventos acionados por alterações no Firestore

Pub/Sub

Ficheiros Proto google/events/cloud/pubsub/v1/events.proto
google/events/cloud/pubsub/v1/data.proto
Mensagem de envelopegoogle.events.cloud.pubsub.v1.MessagePublishedEvent
Mensagem de dadosgoogle.events.cloud.pubsub.v1.MessagePublishedData
Recurso PubsubMessage
Tipo de evento
(quando é publicada uma mensagem Pub/Sub)		 google.cloud.pubsub.topic.v1.messagePublished
Exemplo Texto
Mais informações Receba eventos num serviço do Cloud Run através de mensagens do Pub/Sub
Acione um fluxo de trabalho através de mensagens do Pub/Sub

O que se segue?

Saiba mais sobre os trajetos de eventos.