Formato CloudEvents: enlace de protocolo HTTP

CloudEvents (cloudevents.io) es una especificación para describir datos de eventos de forma común. La especificación está bajo la supervisión de la Cloud Native Computing Foundation (CNCF) y está organizada por el grupo de trabajo Serverless de la CNCF.

Eventarc envía eventos al receptor de eventos en formato CloudEvents a través de una solicitud HTTP.

Encabezados de solicitud HTTP

Los servicios de destino reciben eventos de los routers de eventos como solicitudes HTTP POST con el formato de la versión 1.0 de CloudEvents especificación de vinculación del protocolo HTTP. Cada solicitud HTTP contiene encabezados y un cuerpo específicos de eventos, 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 del evento. 1096434104173400
ce-source Identifica la fuente del evento. //pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion Versión de la especificación de CloudEvents usada en este evento. 1.0
ce-type El tipo de datos de 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 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: el URI de la API de Google del servicio que emite el evento. Por ejemplo, bigquery.googleapis.com para los eventos de BigQuery.
  • PROJECT_ID: tu ID de proyecto Google Cloud .
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: generado por el sistema.

Body

La carga útil es un objeto JSON que detalla el evento de registros de auditoría de Cloud. En protoPayload, puedes encontrar los valores de resourceName, serviceName y methodName. Para obtener más información, consulta Determinar filtros de eventos para 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 ha publicado el evento.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: generado por el sistema.

Body

La carga útil es un mensaje push de Pub/Sub. En el campo data, puedes encontrar el mensaje como una cadena codificada en Base64. Consulta el ejemplo de este documento.

Repositorio de código abierto

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

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

  • Protocol buffers de Google para cargas útiles de datos de CloudEvents
  • Esquemas JSON generados
  • Un catálogo público de esquemas JSON

También se incluyen enlaces a bibliotecas de cliente.

Eventos comunes

Los búferes de protocolo (o protobufs) representan los datos de los eventos que genera Eventarc. Los Protocol Buffers de CloudEvents se proporcionan como esquemas legibles por máquina, lo que permite crear bibliotecas de tipos de datos y facilita el consumo de eventos.

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

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

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

Registros de auditoría de Cloud

Archivos Protogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Mensaje de 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 evento
  • serviceName
  • methodName
  • resourceName
Consulta la lista de tipos de eventos que usan registros de auditoría de Cloud.
Ejemplos Registro de auditoría de Pub/Sub
Registro de auditoría de BigQuery
Más información Crear un activador de Eventarc para un evento de Registros de auditoría de Cloud
Determinar filtros de eventos para Registros de auditoría de Cloud
Google Cloud servicios con registros de auditoría

Cloud Storage

Archivos Proto google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
Mensajes de 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 de 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 Crear un activador de Eventarc para un evento de Firestore
Crear arquitecturas basadas en eventos con Eventarc y Firestore
Extender con funciones de Cloud Run para gestionar 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 de 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 Recibir eventos en un servicio de Cloud Run mediante mensajes de Pub/Sub
Activar un flujo de trabajo mediante mensajes de Pub/Sub

Siguientes pasos

Más información sobre las rutas de eventos