CloudEvents: formato de evento JSON

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. O alvo de destino, por exemplo, o serviço do Workflows, converte o evento em um objeto JSON (seguindo a especificação do CloudEvents) e transmite o evento para a execução do fluxo de trabalho como um argumento do ambiente de execução do fluxo de trabalho.

Formato de payload JSON

O serviço de destino recebe eventos de roteadores de eventos e aplica a eles o formato de evento JSON do CloudEvents versão 1.0.1 com os seguintes atributos do CloudEvents:

Atributo Descrição Exemplo
dados O payload dos dados de eventos. 

{
  "subscription": "projects/my-project/subscriptions/my-sub",
  "message": {
    "attributes": {
      "attr1":"attr1-value"
    },
    "data": "aGVsbG8gd29ybGQ=",
    "messageId": "2070443601311540",
    "publishTime":"2021-02-26T19:13:55.749Z"
  }
}
datacontenttype O tipo de dados transmitidos application/json
id O identificador exclusivo do evento 2070443601311540
source A origem do evento //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion A versão de especificação do CloudEvents usada para este evento. 1.0
tipo O tipo de dados de evento. google.cloud.pubsub.topic.v1.messagePublished
tempo Hora da geração do evento, no formato RFC 3339 (opcional) 2020-12-20T13:37:33.647Z

Dependendo do tipo de evento, o formato do payload será conforme a seguir:

Registros de auditoria do Cloud

O argumento do ambiente de execução é um objeto JSON que detalha o evento dos Registros de auditoria do Cloud. Neste documento, consulte o Exemplo de eventos comuns. No objeto JSON, é possível encontrar os valores resourceName, serviceName e methodName. Para mais informações, consulte Determinar filtros de evento para registros de auditoria do Cloud.

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

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//cloudaudit.googleapis.com/projects/PROJECT_ID/logs/data_access",
  "specversion": "1.0",
  "type": "google.cloud.audit.log.v1.written",
  "time": "EVENT_GENERATION_TIME",
  "dataschema": "https://googleapis.github.io/google-cloudevents/jsonschema/google/events/cloud/audit/v1/LogEntryData.json",
  "methodName": "jobservice.jobcompleted",
  "resourceName": "projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1",
  "serviceName": "bigquery.googleapis.com",
  "subject": "bigquery.googleapis.com/projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1"
}
  • EVENT_DATA: o conteúdo da mensagem decodificada no formato JSON. Para mais informações, consulte Eventos comuns neste documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: gerados pelo sistema.
  • PROJECT_ID: é seu ID do projeto no Google Cloud.
  • dataschema, methodName, resourceName, serviceName, subject: atributos específicos do tipo de evento.

Cloud Storage

Os argumentos do ambiente de execução são alterações feitas no Cloud Storage. No campo data, é possível encontrar a alteração no bucket do Cloud Storage. Neste documento, consulte o Exemplo de eventos comuns.

Os eventos do tipo google.cloud.storage.object.v1.finalized têm o seguinte formato:

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json",
  "id": "MESSAGE_ID",
  "source": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME",
  "specversion": "1.0",
  "type": "google.cloud.storage.object.v1.finalized",
  "time": "EVENT_GENERATION_TIME",
  "subject": "objects/my-file.txt"
}
  • EVENT_DATA: o conteúdo da mensagem decodificada no formato JSON. Para mais informações, consulte Eventos comuns neste documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: gerados pelo sistema.
  • BUCKET_NAME: o nome do bucket do Cloud Storage que é atualizado.
  • subject: atributo específico do tipo de evento.

Pub/Sub

O argumento do ambiente de execução é uma mensagem push do Pub/Sub. No campo data, é possível encontrar a mensagem como uma string codificada em Base64. Neste documento, consulte o Exemplo de eventos comuns.

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

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//pubsub.googleapis.com/TOPIC_NAME",
  "specversion": "1.0",
  "type": "google.cloud.pubsub.topic.v1.messagePublished",
  "time": "EVENT_GENERATION_TIME"
}
  • EVENT_DATA: o conteúdo da mensagem decodificada no formato JSON. Para mais informações, consulte Eventos comuns neste documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: gerados pelo sistema.
  • TOPIC_NAME: o nome do tópico do Pub/Sub em que o evento foi publicado.

Repositório de 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 protogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Mensagem do envelopegoogle.events.cloud.audit.v1.AuditLogWrittenEvent
Mensagem de dadosgoogle.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
Confira a lista de tipos de eventos que usam os Registros de auditoria do Cloud.
Examples Registro de auditoria do Pub/Sub
Registro de auditoria do BigQuery
Mais informações Crie um gatilho do Eventarc para um evento dos Registros de auditoria do Cloud
Determine filtros de eventos para registros de auditoria do Cloud
Google Cloud serviços com registros de auditoria

Cloud Storage

Arquivos proto google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
Mensagens do 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
Resource Objects
Tipos de evento
 Consulte a lista de tipos de eventos diretos compatíveis.
Examples Simples
Complexo
Mais informações Criar um gatilho do Eventarc para um evento do Cloud Storage
Receber eventos do Cloud Storage em um serviço do Cloud Run

Firestore

Arquivos proto google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
Mensagens do 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
Resource Document
Tipos de evento Consulte a lista de tipos de eventos diretos compatíveis.
Examples Simples
Complexo
Mais informações Crie um gatilho do Eventarc para um evento do Firestore
Crie arquiteturas orientadas a eventos com o Eventarc e o Firestore
Amplie com Cloud Functions para processar eventos acionados por alterações no Firestore

Pub/Sub

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