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:

Header 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: El ID del proyecto de GCP
  • 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 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
Ejemplo Registro de auditoría de Pub/Sub
Registro de auditoría de BigQuery

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
(cuando un trabajo de Cloud Storage se finaliza, archiva, borra y actualiza)
google.cloud.storage.object.v1.finalized
google.cloud.storage.object.v1.archived
google.cloud.storage.object.v1.deleted
google.cloud.storage.object.v1.metadataUpdated
Examples Simple
Complejo

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
(cuando se crea, actualiza, borra y escribe un documento de Firestore)
google.cloud.firestore.document.v1.created
google.cloud.firestore.document.v1.updated
google.cloud.firestore.document.v1.deleted
google.cloud.firestore.document.v1.written
Examples Simple
Complejo

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
Examples Texto