CloudEvents: formato de evento JSON

CloudEvents (cloudevents.io) es una especificación para describir los datos de eventos de una manera común. La especificación pertenece a Cloud Native Computing Foundation (CNCF) y se organiza en el grupo de trabajo sin servidores de la CNCF.

Eventarc entrega eventos al receptor de eventos en el formato de CloudEvents a través de una solicitud HTTP. El objetivo de destino, por ejemplo, el servicio de Workflows, convierte el evento en un objeto JSON (según la especificación de CloudEvents) y pasa el evento a la ejecución del flujo de trabajo como un argumento del entorno de ejecución del flujo de trabajo.

Formato de carga útil de JSON

El servicio de destino recibe eventos de routers de eventos y les da formato a los eventos al formato de evento de JSON para CloudEvents versión 1.0.1 con los siguientes atributos de CloudEvents:

Atributo Descripción Ejemplo
datos La carga útil de los datos 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 El tipo de datos que se pasó application/json
id El identificador único del evento 2070443601311540
source La fuente del evento //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion La versión de la especificación de CloudEvent que se usa para este evento. 1.0
tipo El tipo de datos del evento google.cloud.pubsub.topic.v1.messagePublished
tiempo Hora de generación del evento, en formato RFC 3339 (opcional) 2020-12-20T13:37:33.647Z

Según el tipo de evento, el formato de la carga útil es el siguiente:

Registros de auditoría de Cloud

El argumento del entorno de ejecución es un objeto JSON que detalla el evento de los registros de auditoría de Cloud. En este documento, consulta el ejemplo de eventos comunes. En el objeto JSON, puedes encontrar los valores resourceName, serviceName y methodName. Si deseas obtener más información, consulta Determina los filtros de eventos para los Registros de auditoría de Cloud.

Los eventos de tipo google.cloud.audit.log.v1.written tienen el siguiente 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: Es el contenido del mensaje decodificado en formato JSON. Para obtener más información, en este documento, consulta Eventos comunes.
  • MESSAGE_ID, EVENT_GENERATION_TIME: generado por el sistema.
  • PROJECT_ID: tu ID del proyecto de Google Cloud.
  • dataschema, methodName, resourceName, serviceName y subject: Atributos específicos del tipo de evento.

Cloud Storage

Los argumentos del entorno de ejecución son cambios en Cloud Storage. En el campo data, puedes encontrar el cambio en el bucket de Cloud Storage. En este documento, consulta el ejemplo de eventos comunes.

Los eventos de tipo google.cloud.storage.object.v1.finalized tienen el siguiente 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: Es el contenido del mensaje decodificado en formato JSON. Para obtener más información, en este documento, consulta Eventos comunes.
  • MESSAGE_ID, EVENT_GENERATION_TIME: generado por el sistema.
  • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que se actualiza.
  • subject: Atributo específico del tipo de evento.

Pub/Sub

El argumento del entorno de ejecución es un mensaje de envío de Pub/Sub. En el campo data, puedes encontrar el mensaje como una cadena codificada en base64. En este documento, consulta el ejemplo de eventos comunes.

Los eventos de tipo google.cloud.pubsub.topic.v1.messagePublished tienen el siguiente 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: Es el contenido del mensaje decodificado en formato JSON. Para obtener más información, en este documento, consulta Eventos comunes.
  • MESSAGE_ID, EVENT_GENERATION_TIME: generado por el sistema.
  • TOPIC_NAME: Es el nombre del tema de Pub/Sub en el que se publicó el evento.

Repositorio de código abierto

La estructura del cuerpo HTTP para todos los eventos está disponible en el repositorio de GitHub de CloudEvents.

El repositorio contiene lo siguiente para ayudarte a comprender y usar los datos de CloudEvents en tu lenguaje de programación:

  • Búferes de protocolo de Google para cargas útiles de datos de CloudEvents
  • Esquemas JSON generados
  • Un catálogo de esquemas JSON público

También se incluyen vínculos a bibliotecas cliente.

Eventos comunes

Los búferes de protocolo (o protobufs) representan los datos dentro de los eventos que genera Eventarc. Los búferes de protocolo para CloudEvents se proporcionan como esquemas procesables, lo que permite crear bibliotecas de tipos de datos y facilitar el consumo de eventos.

Hay dos mensajes protobuf que son relevantes para cualquier tipo de CloudEvent determinado:

  • El mensaje de sobre que representa el CloudEvent completo, incluidos los atributos de la extensión. por ejemplo, AuditLogWrittenEvent.
  • El mensaje data por ejemplo, LogEntryData o StorageObjectData.
Muchos tipos de CloudEvent pueden usar el mismo mensaje de datos. Por ejemplo, cada evento asociado con un objeto de Cloud Storage usa StorageObjectData como mensaje de datos. Cada mensaje de sobre especifica el tipo de CloudEvent al que se asocia a través de una anotación proto. Para obtener más información, consulta la Relación entre los mensajes protobuf y los tipos de CloudEvent.

En las siguientes tablas, se detallan los componentes de algunos eventos comunes:

Registros de auditoría de Cloud

Archivos protogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Mensaje del sobregoogle.events.cloud.audit.v1.AuditLogWrittenEvent
Mensaje de datosgoogle.events.cloud.audit.v1.LogEntryData
Tipo de evento
(cuando se escribe una entrada de registro de auditoría)		 google.cloud.audit.log.v1.written
Extensiones de eventos:
  • serviceName
  • methodName
  • resourceName
Consulta la lista de tipos de eventos con Registros de auditoría de Cloud.
Ejemplos Registro de auditoría de Pub/Sub
Registro de auditoría de BigQuery
Más información Crea un activador de Eventarc para un evento de Registros de auditoría de Cloud
Determina filtros de eventos para los Registros de auditoría de Cloud
Servicios de Google Cloud con Registros de auditoría

Cloud Storage

Archivos proto google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
Mensajes del sobregoogle.events.cloud.storage.v1.ObjectFinalizedEvent
google.events.cloud.storage.v1.ObjectArchivedEvent
google.events.cloud.storage.v1.ObjectDeletedEvent
google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
Mensaje de datosgoogle.events.cloud.storage.v1.StorageObjectData
Recurso Objects
Tipos de eventos
 Consulta la lista de tipos de eventos directos.
Ejemplos Simple
Complejo
Más información Crea un activador de Eventarc para un evento de Cloud Storage
Recibe eventos de Cloud Storage en un servicio de Cloud Run

Firestore

Archivos proto google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
Mensajes del sobregoogle.events.cloud.firestore.v1.DocumentCreatedEvent
google.events.cloud.firestore.v1.DocumentUpdatedEvent
google.events.cloud.firestore.v1.DocumentDeletedEvent
google.events.cloud.firestore.v1.DocumentWrittenEvent
Mensaje de datosgoogle.events.cloud.firestore.v1.DocumentEventData
Recurso Document
Tipos de eventos Consulta la lista de tipos de eventos directos.
Ejemplos Simple
Complejo
Más información Crea un activador de Eventarc para un evento de Firestore
Crea arquitecturas controladas por eventos con Eventarc y Firestore
Extender con Cloud Functions para controlar eventos activados por cambios en Firestore

Pub/Sub

Archivos proto google/events/cloud/pubsub/v1/events.proto
google/events/cloud/pubsub/v1/data.proto
Mensaje del sobregoogle.events.cloud.pubsub.v1.MessagePublishedEvent
Mensaje de datosgoogle.events.cloud.pubsub.v1.MessagePublishedData
Recurso PubsubMessage
Tipo de evento
(cuando se publica un mensaje de Pub/Sub)		 google.cloud.pubsub.topic.v1.messagePublished
Ejemplo Texto
Más información Recibe eventos en un servicio de Cloud Run mediante mensajes de Pub/Sub
Activa un flujo de trabajo con mensajes de Pub/Sub