Formato CloudEvents: vinculação de protocolo HTTP

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

O Eventarc entrega eventos ao receptor de eventos no formato CloudEvents por uma solicitação HTTP.

Formato de solicitação HTTP

Os serviços de destino recebem eventos dos roteadores de eventos como solicitações POST HTTP formatadas para a especificação de vinculação de protocolo HTTP do CloudEvents versão 1.0. Cada solicitação HTTP contém cabeçalhos específicos de eventos e um corpo, e é enviada ao caminho do URL raiz (/) do serviço.

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

Header	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 de especificação do CloudEvents usada para este evento.	`1.0`
ce-type	O tipo de dados de evento.	`google.cloud.pubsub.topic.v1.messagePublished`
ce-time	Hora da geração do evento, no formato RFC 3339 (opcional).	`2020-12-20T13:37:33.647Z`

Formato de payload HTTP

Registros de auditoria do Cloud

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 do Google para o serviço que está emitindo o evento (bigquery.googleapis.com, por exemplo) para eventos do BigQuery.
PROJECT_ID: o ID do projeto do GCP.
MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: gerada pelo sistema.

Texto

O payload é um objeto JSON que detalha o evento dos registros de auditoria do Cloud. Em protoPayload, você pode encontrar os valores resourceName, serviceName e methodName. Para mais informações, consulte Determinar filtros de evento para registros 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 em que o evento foi publicado.
MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: gerada pelo sistema.

Texto

O payload é uma mensagem push do Pub/Sub. No campo data, é possível encontrar a mensagem como uma string codificada em Base64. Veja o exemplo neste documento.

Código aberto

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

Ele contém os seguintes itens para ajudar você a entender e usar os dados do CloudEvents na sua linguagem de programação:

Buffers de protocolo do Google para payloads de dados do CloudEvents
Esquemas JSON gerados
Um catálogo público de esquema JSON

Links para bibliotecas de cliente também estão incluídos.

Eventos comuns

Buffers de protocolo (ou protobufs) representam os dados dentro de eventos que são gerados pelo Eventarc. Os buffers de protocolo para CloudEvents são fornecidos como esquemas legíveis por máquina, permitindo que bibliotecas de tipos de dados sejam criadas e facilitam o consumo de eventos.

Há duas mensagens protobuf relevantes para qualquer tipo de CloudEvent:

A mensagem do envelope que representa o CloudEvent completo, incluindo quaisquer atributos de extensão; por exemplo, AuditLogWrittenEvent.
A mensagem data; por exemplo, LogEntryData ou StorageObjectData.

Muitos tipos do CloudEvent podem usar a mesma mensagem de dados. Por exemplo, todos os eventos associados a um objeto do Cloud Storage usam StorageObjectData como a mensagem de dados. Cada mensagem do envelope especifica o tipo do CloudEvent ao qual está associado por meio de uma anotação proto. Para mais informações, consulte Relação entre mensagens protobuf e tipos de CloudEvent.

As tabelas a seguir detalham os componentes de alguns eventos comuns:

Registros de auditoria do Cloud

Arquivos proto	google/events/cloud/audit/v1/events.proto google/events/cloud/audit/v1/data.proto
Mensagem do envelope	`google.events.cloud.audit.v1.AuditLogWrittenEvent`
Mensagem de dados	`google.events.cloud.audit.v1.LogEntryData`
Tipo de evento (quando uma entrada de registro de auditoria é gravada)	`google.cloud.audit.log.v1.written`
Extensões de evento	`serviceName` `methodName` `resourceName`
Exemplo	Registro de auditoria do Pub/Sub Registro de auditoria do BigQuery

Cloud Storage

Arquivos proto	google/events/cloud/storage/v1/events.proto google/events/cloud/storage/v1/data.proto
Mensagens do envelope	`google.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 dados	`google.events.cloud.storage.v1.StorageObjectData`
Recurso	`Objects`
Tipos de evento (quando um job do Cloud Storage é finalizado, arquivado, excluído, atualizado)	`google.cloud.storage.object.v1.finalized` `google.cloud.storage.object.v1.archived` `google.cloud.storage.object.v1.deleted` `google.cloud.storage.object.v1.metadataUpdated`
Examples	Simples Complexo

Pub/Sub

Arquivos proto	google/events/cloud/pubsub/v1/events.proto google/events/cloud/pubsub/v1/data.proto
Mensagem do envelope	`google.events.cloud.pubsub.v1.MessagePublishedEvent`
Mensagem de dados	`google.events.cloud.pubsub.v1.MessagePublishedData`
Recurso	`PubsubMessage`
Tipo de evento (quando uma mensagem do Pub/Sub é publicada)	`google.cloud.pubsub.topic.v1.messagePublished`
Examples	Texto