Formato CloudEvents: associazione del protocollo HTTP

CloudEvents (cloudevents.io) è una specifica per descrivere i dati degli eventi in modo comune. La specifica è sotto la Cloud Native Computing Foundation (CNCF) ed è organizzata dal gruppo di lavoro serverless della CNCF.

Eventarc invia gli eventi al ricevitore di eventi nel formato CloudEvents tramite una richiesta HTTP.

Intestazioni delle richieste HTTP

I servizi di destinazione ricevono eventi dai router di eventi come richieste HTTP POST formattate in base alla specifica di binding del protocollo HTTP CloudEvents versione 1.0. Ogni richiesta HTTP contiene intestazioni e un corpo specifici per l'evento e viene inviata al percorso URL principale (/) del servizio.

Oltre ad altre intestazioni HTTP, tutti gli eventi hanno le seguenti intestazioni HTTP CloudEvents:

Intestazione Descrizione Esempio
ce-id Identificatore univoco dell'evento 1096434104173400
ce-source Identifica l'origine dell'evento. //pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion La versione della specifica CloudEvents utilizzata per questo evento 1.0
ce-type Il tipo di dati sugli eventi google.cloud.pubsub.topic.v1.messagePublished
ce-time Ora di generazione dell'evento, in formato RFC 3339 (facoltativo) 2020-12-20T13:37:33.647Z

Formato payload HTTP

Cloud Audit Logs

Gli eventi di tipo google.cloud.audit.log.v1.written hanno il seguente formato:

Intestazioni

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: l'URI dell'API Google per il servizio che genera l'evento; ad esempio, bigquery.googleapis.com per gli eventi di BigQuery.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: generato dal sistema.

Corpo

Il payload è un oggetto JSON che descrive in dettaglio l'evento Cloud Audit Logs. In protoPayload puoi trovare i valori resourceName, serviceName e methodName. Per saperne di più, vedi Determinare i filtri eventi per Cloud Audit Logs.

Pub/Sub

Gli eventi di tipo google.cloud.pubsub.topic.v1.messagePublished hanno il seguente formato:

Intestazioni

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: l'argomento Pub/Sub in cui è stato pubblicato l'evento.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: generato dal sistema.

Corpo

Il payload è un messaggio push Pub/Sub. Nel campo data puoi trovare il messaggio come stringa con codifica Base64. Consulta l'esempio in questo documento.

Repository open source

La struttura del corpo HTTP per tutti gli eventi è disponibile nel repository GitHub CloudEvents.

Il repository contiene quanto segue per aiutarti a comprendere e utilizzare i dati CloudEvents nel tuo linguaggio di programmazione:

  • Google Protocol Buffers per i payload di dati CloudEvents
  • Schemi JSON generati
  • Un catalogo pubblico di schemi JSON

Sono inclusi anche i link alle librerie client.

Eventi comuni

I protocol buffer (o protobuf) rappresentano i dati all'interno degli eventi generati da Eventarc. I buffer di protocollo per CloudEvents vengono forniti come schemi leggibili automaticamente, consentendo la creazione di librerie di tipi di dati e semplificando l'utilizzo degli eventi.

Esistono due messaggi protobuf pertinenti per un determinato tipo di CloudEvent:

  • Il messaggio envelope che rappresenta l'intero CloudEvent, inclusi eventuali attributi di estensione; ad esempio, AuditLogWrittenEvent.
  • Il messaggio data; ad esempio, LogEntryData o StorageObjectData.
Molti tipi di CloudEvent possono utilizzare lo stesso messaggio di dati. Ad esempio, ogni evento associato a un oggetto Cloud Storage utilizza StorageObjectData come messaggio di dati. Ogni messaggio envelope specifica il tipo di CloudEvent a cui è associato tramite un'annotazione proto. Per saperne di più, consulta Relazione tra messaggi protobuf e tipi CloudEvent.

Le tabelle seguenti descrivono in dettaglio i componenti di alcuni eventi comuni:

Cloud Audit Logs

File Protogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Messaggio nella bustagoogle.events.cloud.audit.v1.AuditLogWrittenEvent
Messaggio di datigoogle.events.cloud.audit.v1.LogEntryData
Tipo di evento
(quando viene scritta una voce di log di controllo)		 google.cloud.audit.log.v1.written
Estensioni evento
  • serviceName
  • methodName
  • resourceName
Consulta l'elenco dei tipi di eventi che utilizzano Cloud Audit Logs.
Esempi Log di controllo Pub/Sub
Log di controllo BigQuery
Ulteriori informazioni Crea un trigger Eventarc per un evento Cloud Audit Logs
Determina i filtri eventi per Cloud Audit Logs
Google Cloud servizi con audit log

Cloud Storage

File Proto google/events/cloud/storage/v1/events.proto
google/events/cloud/storage/v1/data.proto
Messaggi di bustagoogle.events.cloud.storage.v1.ObjectFinalizedEvent
google.events.cloud.storage.v1.ObjectArchivedEvent
google.events.cloud.storage.v1.ObjectDeletedEvent
google.events.cloud.storage.v1.ObjectMetadataUpdatedEvent
Messaggio di datigoogle.events.cloud.storage.v1.StorageObjectData
Risorsa Objects
Tipi di eventi
 Consulta l'elenco dei tipi di eventi diretti.
Esempi Semplice
Complesso
Ulteriori informazioni Crea un trigger Eventarc per un evento Cloud Storage
Ricevi eventi da Cloud Storage in un servizio Cloud Run

Firestore

File Proto google/events/cloud/firestore/v1/events.proto
google/events/cloud/firestore/v1/data.proto
Messaggi di bustagoogle.events.cloud.firestore.v1.DocumentCreatedEvent
google.events.cloud.firestore.v1.DocumentUpdatedEvent
google.events.cloud.firestore.v1.DocumentDeletedEvent
google.events.cloud.firestore.v1.DocumentWrittenEvent
Messaggio di datigoogle.events.cloud.firestore.v1.DocumentEventData
Risorsa Document
Tipi di evento Consulta l'elenco dei tipi di eventi diretti.
Esempi Semplice
Complesso
Ulteriori informazioni Crea un trigger Eventarc per un evento Firestore
Crea architetture basate su eventi con Eventarc e Firestore
Estendi con le funzioni Cloud Run per gestire gli eventi attivati dalle modifiche in Firestore

Pub/Sub

File Proto google/events/cloud/pubsub/v1/events.proto
google/events/cloud/pubsub/v1/data.proto
Messaggio nella bustagoogle.events.cloud.pubsub.v1.MessagePublishedEvent
Messaggio di datigoogle.events.cloud.pubsub.v1.MessagePublishedData
Risorsa PubsubMessage
Tipo di evento
(quando viene pubblicato un messaggio Pub/Sub)		 google.cloud.pubsub.topic.v1.messagePublished
Esempio Testo
Ulteriori informazioni Ricevi eventi in un servizio Cloud Run utilizzando messaggi Pub/Sub
Attiva un flusso di lavoro utilizzando messaggi Pub/Sub

Passaggi successivi

Scopri di più sulle route degli eventi.