CloudEvents – Formato de evento JSON

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. O destino, por exemplo, o serviço Workflows, converte o evento num objeto JSON (de acordo com a especificação CloudEvents) e passa o evento para a execução do fluxo de trabalho como um argumento de tempo de execução do fluxo de trabalho.

Formato do payload de JSON

O serviço de destino recebe eventos de routers de eventos e formata os eventos para o formato de eventos JSON para a versão 1.0.1 do CloudEvents 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 que foi transmitido application/json
id O identificador exclusivo do evento 2070443601311540
fonte A origem do evento //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion A versão da especificação CloudEvents usada para este evento 1,0
escrever O tipo de dados de eventos google.cloud.pubsub.topic.v1.messagePublished
tempo Hora de geração do evento, no formato RFC 3339 (opcional) 2020-12-20T13:37:33.647Z

Consoante o tipo de evento, o formato da carga útil é o seguinte:

Cloud Audit Logs

O argumento de tempo de execução é um objeto JSON que detalha o evento dos registos de auditoria da nuvem. Neste documento, consulte o Exemplo de eventos comuns. No objeto JSON, 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.

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 descodificado no formato JSON. Para mais informações, consulte a secção Eventos comuns neste documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: gerado pelo sistema.
  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • dataschema, methodName, resourceName, serviceName, subject: atributos específicos do tipo de evento.

Cloud Storage

Os argumentos de tempo de execução são alterações ao Cloud Storage. No campo data, pode encontrar a alteração no contentor 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 descodificado no formato JSON. Para mais informações, consulte a secção Eventos comuns neste documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: gerado pelo sistema.
  • BUCKET_NAME: o nome do contentor do Cloud Storage que é atualizado.
  • subject: atributo específico do tipo de evento.

Pub/Sub

O argumento de tempo de execução é uma mensagem push do Pub/Sub. No campo data pode 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 descodificado no formato JSON. Para mais informações, consulte a secção Eventos comuns neste documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: gerado pelo sistema.
  • TOPIC_NAME: o nome do tópico do Pub/Sub para o qual o evento foi publicado.

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