CloudEvents – Format d'événement JSON

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. La cible de destination (par exemple, le service Workflows) convertit l'événement en objet JSON (conformément à la spécification CloudEvents) et transmet l'événement à l'exécution du workflow comme argument d'environnement d'exécution du workflow.

Format de charge utile JSON

Le service de destination reçoit les événements des routeurs d'événements et les met en forme au format d'événement JSON pour CloudEvents version 1.0.1 avec les attributs CloudEvents suivants :

Attribut Description Exemple
data Charge utile des données d'événement 

{
  "subscription": "projects/my-project/subscriptions/my-sub",
  "message": {
    "attributes": {
      "attr1":"attr1-value"
    },
    "data": "aGVsbG8gd29ybGQ=",
    "messageId": "2070443601311540",
    "publishTime":"2021-02-26T19:13:55.749Z"
  }
}
datacontenttype Le type de données transmis application/json
id Identifiant unique de l'événement 2070443601311540
source Source de l'événement //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion Version de la spécification CloudEvents utilisée pour cet événement 1
type Type des données d'événement google.cloud.pubsub.topic.v1.messagePublished
time Heure de génération de l'événement, au format RFC 3339 (facultatif) 2020-12-20T13:37:33.647Z

Selon le type d'événement, le format de la charge utile est le suivant :

Cloud Audit Logs

L'argument d'exécution est un objet JSON qui détaille l'événement Cloud Audit Logging. Dans ce document, consultez l'exemple d'événement courant. Dans l'objet JSON, 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.

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

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//cloudaudit.googleapis.com/projects/PROJECT_ID/logs/data_access",
  "specversion": "1.0",
  "type": "google.cloud.audit.log.v1.written",
  "time": "EVENT_GENERATION_TIME",
  "dataschema": "https://googleapis.github.io/google-cloudevents/jsonschema/google/events/cloud/audit/v1/LogEntryData.json",
  "methodName": "jobservice.jobcompleted",
  "resourceName": "projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1",
  "serviceName": "bigquery.googleapis.com",
  "subject": "bigquery.googleapis.com/projects/my-project/jobs/bqjob_r3ac45813612fa2d6_0000017d591922c9_1"
}
  • EVENT_DATA : contenu de message décodé au format JSON. Pour plus d'informations, consultez la section Événements courants.
  • MESSAGE_ID, EVENT_GENERATION_TIME : générés par le système.
  • PROJECT_ID : ID de votre projet Google Cloud.
  • dataschema, methodName, resourceName, serviceName, subject : attributs spécifiques au type d'événement.

Cloud Storage

Les arguments d'exécution sont modifiés dans Cloud Storage. Dans le champ data, vous trouverez la modification dans le bucket Cloud Storage. Dans ce document, consultez l'exemple d'événement courant.

Les événements de type google.cloud.storage.object.v1.finalized sont au format suivant :

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json",
  "id": "MESSAGE_ID",
  "source": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME",
  "specversion": "1.0",
  "type": "google.cloud.storage.object.v1.finalized",
  "time": "EVENT_GENERATION_TIME",
  "subject": "objects/my-file.txt"
}
  • EVENT_DATA : contenu de message décodé au format JSON. Pour plus d'informations, consultez la section Événements courants.
  • MESSAGE_ID, EVENT_GENERATION_TIME : générés par le système.
  • BUCKET_NAME : nom du bucket Cloud Storage mis à jour.
  • subject : attribut spécifique au type d'événement.

Pub/Sub

L'argument d'exécution est un message push Pub/Sub. Le champ data contient le message sous forme de chaîne encodée en base64. Dans ce document, consultez l'exemple d'événement courant.

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

{
  "data":{ EVENT_DATA },
  "datacontenttype": "application/json; charset=utf-8",
  "id": "MESSAGE_ID",
  "source": "//pubsub.googleapis.com/TOPIC_NAME",
  "specversion": "1.0",
  "type": "google.cloud.pubsub.topic.v1.messagePublished",
  "time": "EVENT_GENERATION_TIME"
}
  • EVENT_DATA : contenu de message décodé au format JSON. Pour plus d'informations, consultez la section Événements courants.
  • MESSAGE_ID, EVENT_GENERATION_TIME : générés par le système.
  • TOPIC_NAME : nom du sujet Pub/Sub dans lequel l'événement a été publié.

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.
Examples Journal d'audit Pub/Sub
Journal d'audit BigQuery
Informations complémentaires 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.
Examples Simple
Complexe
Informations complémentaires 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.
Examples Simple
Complexe
Informations complémentaires 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 avec Cloud Functions pour la gestion des événements déclenchés par des modifications dans 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
Informations complémentaires 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