Formato de CloudEvents

CloudEvents (cloudevents.io) es una especificación que describe los datos de eventos de manera común. La especificación está en Cloud Native Computing Foundation (CNCF) y la organiza el Serverless Working Group de la CNCF.

Eventarc entrega eventos a tu servicio de Cloud Run en el formato de CloudEvents a través de una solicitud HTTP.

Formato de solicitud HTTP

Los servicios de Cloud Run reciben eventos de enrutadores 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.events.cloud.audit.v1.LogEntryData
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. Este es un ejemplo de registro de auditoría de Cloud Storage:

{
  "protoPayload": {
    "status": {},
    "authenticationInfo": { ... },
    "requestMetadata": {
      "callerIp": "...",
      "callerSuppliedUserAgent": "...",
      "requestAttributes": {
        "time": "YYYY-MM-DDThh:mm:ss.sZ",
        "auth": {}
      },
      "destinationAttributes": {}
    },
    "serviceName": "storage.googleapis.com",
    "methodName": "storage.objects.create",
    "authorizationInfo": [
      {
        "resource": "projects/_/buckets/MY_BUCKET/objects/MY_FILE.txt",
        "permission": "storage.objects.create",
        "granted": true,
        "resourceAttributes": {}
      },
      {
        "resource": "projects/_/buckets/MY_BUCKET/objects/MY_FILE.txt",
        "permission": "storage.objects.delete",
        "granted": true,
        "resourceAttributes": {}
      }
    ],
    "resourceName": "projects/_/buckets/MY_PROJECT/objects/MY_FILE.txt",
    "serviceData": {
      "policyDelta": {
        "bindingDeltas": [ ... ]
      },
      "@type": "type.googleapis.com/google.iam.v1.logging.AuditData"
    },
    "resourceLocation": {
      "currentLocations": [
        "us-central1"
      ]
    }
  },
  "insertId": "-qklu1af11306y",
  "resource": {
    "type": "gcs_bucket",
    "labels": {
      "location": "us-central1",
      "bucket_name": "MY_BUCKET",
      "project_id": "MY_PROJECT"
    }
  },
  "timestamp": "2021-04-09T17:57:16.718915757Z",
  "severity": "INFO",
  "logName": "projects/MY_PROJECT/logs/cloudaudit.googleapis.com%2Fdata_access",
  "receiveTimestamp": "2021-04-09T17:57:17.748555474Z"
}

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: Es 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.

{
   "message": {
     "attributes": {
       "key": "value"
     },
     "data": "SGVsbG8gV29ybGQK",
     "messageId": "136969346945",
     "publishTime": "2021-10-02T15:01:23.045123456Z"
   },
   "subscription": "projects/MY_PROJECT/subscriptions/MY_SUBSCRIPTION"
}

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.