Formato de CloudEvents: vinculación de protocolo HTTP

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.

Encabezados de la solicitud HTTP

Los servicios objetivos reciben eventos de routers de eventos como solicitudes POST HTTP con formato de la especificación de vinculación del protocolo HTTP versión 1.0 de CloudEvents. Cada solicitud HTTP contiene encabezados y un cuerpo de evento específico, y se envía a la ruta de URL raíz (/) del servicio.

Además de otros encabezados HTTP, todos los eventos tienen los siguientes encabezados HTTP de CloudEvents:

Encabezado	Descripción	Ejemplo
ce-id	Identificador único para el evento	`1096434104173400`
ce-source	Identifica la fuente del evento	`//pubsub.googleapis.com/projects/my-project/topics/my-topic`
ce-specversion	La versión de la especificación de CloudEvent que se usa para este evento.	`1.0`
ce-type	El tipo de datos del evento	`google.cloud.pubsub.topic.v1.messagePublished`
ce-time	Hora de generación del evento, en formato RFC 3339 (opcional)	`2020-12-20T13:37:33.647Z`

Formato de carga útil de HTTP

Registros de auditoría de Cloud

Los eventos de tipo google.cloud.audit.log.v1.written tienen el siguiente formato:

Encabezados

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: Es el URI de la API de Google para el servicio que emite el evento. Por ejemplo, bigquery.googleapis.com es el de los eventos de BigQuery.
PROJECT_ID: tu ID del proyecto de Google Cloud.
MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: generado por el sistema.

Cuerpo

La carga útil es un objeto JSON que detalla el evento de los registros de auditoría de Cloud. En protoPayload, 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.

Pub/Sub

Los eventos de tipo google.cloud.pubsub.topic.v1.messagePublished tienen el siguiente formato:

Encabezados

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: el tema de Pub/Sub en el que se publicó el evento.
MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: generado por el sistema.

Cuerpo

La carga útil es un mensaje de envío de Pub/Sub. En el campo data, puedes encontrar el mensaje como una string codificada en base64. Consulta el ejemplo en este documento.

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 proto	google/events/cloud/audit/v1/events.proto google/events/cloud/audit/v1/data.proto
Mensaje del sobre	`google.events.cloud.audit.v1.AuditLogWrittenEvent`
Mensaje de datos	`google.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 sobre	`google.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 datos	`google.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 sobre	`google.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 datos	`google.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 funciones de Cloud Run 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 sobre	`google.events.cloud.pubsub.v1.MessagePublishedEvent`
Mensaje de datos	`google.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

¿Qué sigue?

Obtén más información sobre las rutas de eventos.