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