CloudEvents – JSON-Ereignisformat

CloudEvents (cloudevents.io) ist eine Spezifikation zum allgemeinen Beschreiben von Ereignisdaten. Die Spezifikation fällt unter die Cloud Native Computing Foundation (CNCF) und wird von der serverlosen Arbeitsgruppe des CNCF organisiert.

Eventarc liefert Ereignisse über eine HTTP-Anfrage an den Ereignisempfänger im CloudEvents-Format. Das Ziel (z. B. der Workflow-Dienst) konvertiert das Ereignis gemäß der CloudEvents-Spezifikation in ein JSON-Objekt und übergibt das Ereignis als Workflow-Laufzeitargument an die Workflow-Ausführung.

JSON-Nutzlastformat

Der Zieldienst empfängt Ereignisse von Ereignis-Routern und formatiert die Ereignisse im JSON-Ereignisformat für CloudEvents Version 1.0.1 mit den folgenden CloudEvents-Attributen:

Attribut Beschreibung Beispiel
daten Die Nutzlast der Ereignisdaten. 

{
  "subscription": "projects/my-project/subscriptions/my-sub",
  "message": {
    "attributes": {
      "attr1":"attr1-value"
    },
    "data": "aGVsbG8gd29ybGQ=",
    "messageId": "2070443601311540",
    "publishTime":"2021-02-26T19:13:55.749Z"
  }
}
datacontenttype Der übergebene Datentyp application/json
id Die eindeutige Kennung für das Ereignis 2070443601311540
source Die Quelle des Ereignisses //pubsub.googleapis.com/projects/my-project/topics/my-topic
specversion Die CloudEvents-Spezifikationsversion, die für dieses Ereignis verwendet wird. 1
Typ Die Art der Ereignisdaten google.cloud.pubsub.topic.v1.messagePublished
Zeit Zeitpunkt der Ereigniserstellung im Format RFC 3339 (optional) 2020-12-20T13:37:33.647Z

Je nach Ereignistyp sieht das Nutzlastformat so aus:

Cloud-Audit-Logs

Das Laufzeitargument ist ein JSON-Objekt, in dem das Ereignis des Cloud-Audit-Logs detailliert beschrieben wird. In diesem Dokument finden Sie weitere Informationen unter Häufige Ereignisse. Im JSON-Objekt finden Sie die Werte resourceName, serviceName und methodName. Weitere Informationen finden Sie unter Ereignisfilter für Cloud-Audit-Logging ermitteln.

Ereignisse vom Typ google.cloud.audit.log.v1.written haben das folgende Format:

{
  "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: der decodierte Nachrichteninhalt im JSON-Format. Weitere Informationen in diesem Dokument finden Sie unter Häufige Ereignisse.
  • MESSAGE_ID, EVENT_GENERATION_TIME: vom System generiert.
  • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
  • dataschema, methodName, resourceName, serviceName, subject: Attribute, die für den Ereignistyp spezifisch sind.

Cloud Storage

Die Laufzeitargumente sind Änderungen an Cloud Storage. Im Feld data finden Sie die Änderung im Cloud Storage-Bucket. In diesem Dokument finden Sie weitere Informationen im Beispiel zu gängigen Ereignissen.

Ereignisse vom Typ google.cloud.storage.object.v1.finalized haben das folgende Format:

{
  "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: der decodierte Nachrichteninhalt im JSON-Format. Weitere Informationen in diesem Dokument finden Sie unter Häufige Ereignisse.
  • MESSAGE_ID, EVENT_GENERATION_TIME: vom System generiert.
  • BUCKET_NAME: der Name des Cloud Storage-Buckets, der aktualisiert wird.
  • subject: spezifisch für den Ereignistyp.

Pub/Sub

Das Laufzeitargument ist eine Pub/Sub-Push-Nachricht. Im Feld data finden Sie die Nachricht als Base64-codierten String. In diesem Dokument finden Sie weitere Informationen im Beispiel zu gängigen Ereignissen.

Ereignisse vom Typ google.cloud.pubsub.topic.v1.messagePublished haben das folgende Format:

{
  "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: der decodierte Nachrichteninhalt im JSON-Format. Weitere Informationen in diesem Dokument finden Sie unter Häufige Ereignisse.
  • MESSAGE_ID, EVENT_GENERATION_TIME: vom System generiert.
  • TOPIC_NAME: der Name des Pub/Sub-Themas, in dem das Ereignis veröffentlicht wurde.

Open-Source-Repository

Die Struktur des HTTP-Texts für alle Ereignisse ist im CloudEvents-GitHub-Repository verfügbar.

Das Repository enthält Folgendes, damit Sie CloudEvents-Daten in Ihrer Programmiersprache verstehen und verwenden können:

  • Google Protocol Buffers für CloudEvents-Datennutzlasten
  • Generierte JSON-Schemas
  • Einen öffentlichen JSON-Schemakatalog

Links zu Clientbibliotheken sind ebenfalls enthalten.

Häufige Ereignisse

Protokollzwischenspeicher (oder Protokollpuffer) stellen die Daten innerhalb von Ereignissen dar, die von Eventarc generiert werden. Protokollzwischenspeicher für CloudEvents werden als maschinenlesbare Schemas bereitgestellt, wodurch Bibliotheken von Datentypen erstellt werden können und die Nutzung von Ereignissen vereinfacht wird.

Es gibt zwei protobuf-Nachrichten, die für alle CloudEvent-Typ relevant sind:

  • Die Envelope-Nachricht, die das vollständige CloudEvent einschließlich Erweiterungsattribute darstellt. Beispiel: AuditLogWrittenEvent.
  • Die Datennachricht; Beispiel: LogEntryData oder StorageObjectData.
Viele CloudEvent-Typen können die gleiche Datennachricht verwenden. Beispielsweise verwendet jedes mit einem Cloud Storage-Objekt verknüpfte Ereignis StorageObjectData als Datennachricht. Jede Envelope-Nachricht gibt den CloudEvent-Typ an, dem sie über eine Proto-Annotation zugeordnet ist. Weitere Informationen finden Sie unter Beziehung zwischen protobuf-Nachrichten und CloudEvent-Typen.

In den folgenden Tabellen sind die Komponenten einiger häufiger Ereignisse aufgeführt:

Cloud-Audit-Logs

Proto-Dateiengoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Envelope-Nachrichtgoogle.events.cloud.audit.v1.AuditLogWrittenEvent
Datennachrichtgoogle.events.cloud.audit.v1.LogEntryData
Ereignistyp
(wenn ein Audit-Logeintrag geschrieben wird)		 google.cloud.audit.log.v1.written
Ereigniserweiterungen
  • serviceName
  • methodName
  • resourceName
Weitere Informationen finden Sie in der Liste der Ereignistypen mit Cloud-Audit-Logs.
Beispiele Pub/Sub Audit-Log
BigQuery Audit-Log
Weitere Informationen Eventarc-Trigger für ein Cloud-Audit-Log-Ereignis erstellen
Ereignisfilter für Cloud-Audit-Logs ermitteln
Google Cloud Dienste mit Audit-Logs

Cloud Storage

Proto-Dateien google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
Envelope-Nachrichtengoogle.events.cloud.storage.v1.ObjectFinalizedEvent
google.events.cloud.storage.v1.ObjectArchivedEvent
google.events.cloud.storage.v1.ObjectDeletedEvent
google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
Datennachrichtgoogle.events.cloud.storage.v1.StorageObjectData
Ressource Objects
Ereignistypen
 Liste direkter Ereignistypen
Beispiele Einfach
Komplex
Weitere Informationen Eventarc-Trigger für ein Cloud Storage-Ereignis erstellen
Ereignisse aus Cloud Storage in einem Cloud Run-Dienst empfangen

Firestore

Proto-Dateien google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
Envelope-Nachrichtengoogle.events.cloud.firestore.v1.DocumentCreatedEvent
google.events.cloud.firestore.v1.DocumentUpdatedEvent
google.events.cloud.firestore.v1.DocumentDeletedEvent
google.events.cloud.firestore.v1.DocumentWrittenEvent
Datennachrichtgoogle.events.cloud.firestore.v1.DocumentEventData
Ressource Document
Ereignistypen Liste direkter Ereignistypen
Beispiele Einfach
Komplex
Weitere Informationen Eventarc-Trigger für ein Firestore-Ereignis erstellen
Ereignisgesteuerte Architekturen mit Eventarc und Firestore erstellen
Erweiterung mit Cloud Functions zur Verarbeitung von Ereignissen, die durch Änderungen in Firestore ausgelöst werden

Pub/Sub

Proto-Dateien google/events/cloud/pubsub/v1/events.proto
google/events/cloud/pubsub/v1/data.proto
Envelope-Nachrichtgoogle.events.cloud.pubsub.v1.MessagePublishedEvent
Datennachrichtgoogle.events.cloud.pubsub.v1.MessagePublishedData
Ressource PubsubMessage
Ereignistyp
(wenn eine Pub/Sub-Nachricht veröffentlicht wird)		 google.cloud.pubsub.topic.v1.messagePublished
Beispiel Text
Weitere Informationen Ereignisse in einem Cloud Run-Dienst mit Pub/Sub-Nachrichten empfangen
Workflow mit Pub/Sub-Nachrichten auslösen