Format CloudEvents : liaison de protocole HTTP

CloudEvents (cloudevents.io) est une spécification permettant d'uniformiser la description des données d'événement. La spécification est rattachée à la Cloud Native Computing Foundation (CNCF) et est organisée au sein du CNCF par le groupe de travail Serverless.

Eventarc fournit des événements au destinataire d'événements au format CloudEvents via une requête HTTP.

En-têtes de requête HTTP

Les services cibles les événements des routeurs d'événements sous forme de requêtes HTTP POST formatées selon la spécification de liaison du protocole HTTP CloudEvents version 1.0. Chaque requête HTTP contient des en-têtes spécifiques à un événement, ainsi qu'un corps. Elle est envoyée au chemin d'URL racine (/) du service.

Outre les autres en-têtes HTTP, tous les événements comportent les en-têtes HTTP CloudEvents suivants :

En-tête Description Exemple
ce-id Identifiant unique de l'événement 1096434104173400
ce-source Identifie la source de l'événement //pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion Version de la spécification CloudEvents utilisée pour cet événement 1.0
ce-type Type des données d'événement google.cloud.pubsub.topic.v1.messagePublished
ce-time Heure de génération de l'événement, au format RFC 3339 (facultatif). 2020-12-20T13:37:33.647Z

Format de charge utile HTTP

Cloud Audit Logging

Les événements de type google.cloud.audit.log.v1.written sont au format suivant :

En-têtes

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 : URI de l'API Google pour le service qui émet l'événement, par exemple bigquery.googleapis.com pour les événements BigQuery.
  • PROJECT_ID : ID de votre projet Google Cloud.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH : générés par le système.

Corps

La charge utile est un objet JSON qui détaille l'événement Cloud Audit Logging. Dans protoPayload, vous pouvez trouver les valeurs resourceName, serviceName et methodName. Pour plus d'informations, consultez la section Déterminer des filtres d'événements pour Cloud Audit Logs.

Pub/Sub

Les événements de type google.cloud.pubsub.topic.v1.messagePublished sont au format suivant :

En-têtes

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 : sujet Pub/Sub dans lequel l'événement a été publié.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH : générés par le système.

Corps

La charge utile est un message push Pub/Sub. Le champ data contient le message sous forme de chaîne encodée en base64. Consultez l'exemple dans ce document.

Dépôt Open Source

La structure du corps HTTP de tous les événements est disponible dans le dépôt GitHub de CloudEvents.

Le dépôt contient les éléments suivants pour vous aider à comprendre et utiliser les données CloudEvents dans votre langage de programmation :

  • Les tampons de protocole Google pour les charges utiles de données CloudEvents
  • Les schémas JSON générés
  • Un catalogue de schémas JSON public

Des liens vers des bibliothèques clientes sont également inclus.

Événements courants

Les tampons de protocole (ou protobufs) représentent les données dans les événements générés par Eventarc. Les tampons de protocole de CloudEvents sont fournis sous forme de schémas lisibles par un ordinateur, ce qui permet de créer des bibliothèques de types de données et de faciliter l'utilisation d'événements.

Deux messages protobuf sont pertinents pour tout type d'événement CloudEvent donné :

  • Le message envelope qui représente l'événement CloudEvent complet, y compris les attributs d'extension, par exemple AuditLogWrittenEvent.
  • Le message data : Par exemple, LogEntryData ou StorageObjectData.
De nombreux types CloudEvent peuvent utiliser le même message de données. Par exemple, chaque événement associé à un objet Cloud Storage utilise StorageObjectData comme message de données. Chaque message encapsulé spécifie le type CloudEvent auquel il est associé via une annotation proto. Pour plus d'informations, consultez la section Relation entre les messages protobuf et les types CloudEvent.

Les tableaux suivants détaillent les composants de certains événements courants :

Cloud Audit Logs

Fichiers protogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Message envelopegoogle.events.cloud.audit.v1.AuditLogWrittenEvent
Message datagoogle.events.cloud.audit.v1.LogEntryData
Type d'événement
(lorsqu'une entrée de journal d'audit est écrite)
google.cloud.audit.log.v1.written
Extensions d'événement
  • serviceName
  • methodName
  • resourceName
Consultez la liste des types d'événements utilisant Cloud Audit Logs.
Exemples Journal d'audit Pub/Sub
Journal d'audit BigQuery
En savoir plus Créer un déclencheur Eventarc pour un événement Cloud Audit Logs
Déterminer les filtres d'événements pour Cloud Audit Logs
Google Cloud services avec journaux d'audit

Cloud Storage

Fichiers proto google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
Messages envelopegoogle.events.cloud.storage.v1.ObjectFinalizedEvent
google.events.cloud.storage.v1.ObjectArchivedEvent
google.events.cloud.storage.v1.ObjectDeletedEvent
google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
Message datagoogle.events.cloud.storage.v1.StorageObjectData
Ressource Objects
Types d'événement
Consultez la liste des types d'événements directs.
Exemples Simple
Complexe
En savoir plus Créer un déclencheur Eventarc pour un événement Cloud Storage
Recevoir des événements depuis Cloud Storage dans un service Cloud Run

Firestore

Fichiers proto google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
Messages envelopegoogle.events.cloud.firestore.v1.DocumentCreatedEvent
google.events.cloud.firestore.v1.DocumentUpdatedEvent
google.events.cloud.firestore.v1.DocumentDeletedEvent
google.events.cloud.firestore.v1.DocumentWrittenEvent
Message datagoogle.events.cloud.firestore.v1.DocumentEventData
Ressource Document
Types d'événement Consultez la liste des types d'événements directs.
Exemples Simple
Complexe
En savoir plus Créer un déclencheur Eventarc pour un événement Firestore
Créer des architectures basées sur des événements avec Eventarc et Firestore
Étendre à l'aide des fonctions Cloud Run pour gérer les événements déclenchés par les modifications apportées à Firestore

Pub/Sub

Fichiers proto google/events/cloud/pubsub/v1/events.proto
google/events/cloud/pubsub/v1/data.proto
Message envelopegoogle.events.cloud.pubsub.v1.MessagePublishedEvent
Message datagoogle.events.cloud.pubsub.v1.MessagePublishedData
Ressource PubsubMessage
Type d'événement
(lorsqu'un message Pub/Sub est publié)
google.cloud.pubsub.topic.v1.messagePublished
Exemple Texte
En savoir plus Recevoir des événements dans un service Cloud Run à l'aide de messages Pub/Sub
Déclencher un workflow à l'aide de messages Pub/Sub

Étapes suivantes

En savoir plus sur les routes d'événements