Formato CloudEvents - Associazione di protocollo HTTP

CloudEvents (cloudevents.io) è una specifica per descrivere i dati degli eventi in un modo comune. La specifica fa parte della Cloud Native Computing Foundation (CNCF) ed è organizzata dal Serverless Working Group del CNCF.

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

Nota: man mano che il prodotto Eventarc si evolve, potremmo applicare modifiche compatibili con le versioni precedenti, come l'aggiunta di attributi di filtro facoltativi, attributi solo di output o campi facoltativi al payload dell'evento.

Intestazioni delle richieste HTTP

I servizi di destinazione ricevono eventi dai router di eventi come richieste POST HTTP formattate secondo la specifica di associazione del protocollo HTTP di CloudEvents 1.0. Ogni richiesta HTTP contiene un corpo e intestazioni specifiche per gli eventi e viene inviata al percorso dell'URL principale (/) del servizio.

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

Titolo	Descrizione	Esempio
ce-id	Identificatore univoco per l'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
ora ce	Data/ora di generazione degli eventi, 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 di Google per il servizio che ha emesso l'evento; ad esempio, bigquery.googleapis.com per gli eventi da BigQuery.
• PROJECT_ID: il tuo ID progetto Google Cloud.
• MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: generato dal sistema.

Body

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 ulteriori informazioni, consulta 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.

Body

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

Repository open source

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

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

• buffer di protocollo Google per payload di dati CloudEvents
• Schemi JSON generati
• Un catalogo di schemi JSON pubblico

Sono inclusi anche i link alle librerie client.

Eventi comuni

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

Esistono due messaggi protobuf pertinenti per ogni tipo CloudEvent specifico:

• Il messaggio envelope che rappresenta l'evento CloudEvent completo, inclusi eventuali attributi dell'estensione, ad esempio AuditLogWrittenEvent.
• Il messaggio dati; ad esempio, LogEntryData o StorageObjectData.

Molti tipi di CloudEvent possono utilizzare lo stesso messaggio relativo ai dati. Ad esempio, ogni evento associato a un oggetto Cloud Storage utilizza StorageObjectData come messaggio di dati. Ogni messaggio envelope specifica il tipo CloudEvent a cui è associato tramite un'annotazione proto. Per ulteriori informazioni, consulta la sezione Relazione tra messaggi protobuf e tipi di CloudEvent.

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

Cloud Audit Logs

File di protocollo	google/events/cloud/audit/v1/events.proto google/events/cloud/audit/v1/data.proto
Messaggio sulla busta	google.events.cloud.audit.v1.AuditLogWrittenEvent
Messaggio di dati	google.events.cloud.audit.v1.LogEntryData
Tipo di evento (quando viene scritta una voce dell'audit log)	google.cloud.audit.log.v1.written
Estensioni evento	serviceName methodName resourceName
Esempio	Log di controllo di Pub/Sub Log di controllo di BigQuery

Cloud Storage

File di protocollo	google/events/cloud/storage/v1/events.proto google/events/cloud/storage/v1/data.proto
Messaggi sulla busta	google.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 dati	google.events.cloud.storage.v1.StorageObjectData
Risorsa	Objects
Tipi di eventi (quando un job Cloud Storage viene finalizzato, archiviato, eliminato, aggiornato)	google.cloud.storage.object.v1.finalized google.cloud.storage.object.v1.archived google.cloud.storage.object.v1.deleted google.cloud.storage.object.v1.metadataUpdated
Esempi	Semplice Complesso

Firestore

File di protocollo	google/events/cloud/firestore/v1/events.proto google/events/cloud/firestore/v1/data.proto
Messaggi sulla busta	google.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 dati	google.events.cloud.firestore.v1.DocumentEventData
Risorsa	Document
Tipi di eventi (quando un documento Firestore viene creato, aggiornato, eliminato, scritto)	google.cloud.firestore.document.v1.created google.cloud.firestore.document.v1.updated google.cloud.firestore.document.v1.deleted google.cloud.firestore.document.v1.written
Esempi	Semplice Complesso

Pub/Sub

File di protocollo	google/events/cloud/pubsub/v1/events.proto google/events/cloud/pubsub/v1/data.proto
Messaggio sulla busta	google.events.cloud.pubsub.v1.MessagePublishedEvent
Messaggio di dati	google.events.cloud.pubsub.v1.MessagePublishedData
Risorsa	PubsubMessage
Tipo di evento (quando viene pubblicato un messaggio Pub/Sub)	google.cloud.pubsub.topic.v1.messagePublished
Esempi	Testo