CloudEvents (formato di eventi JSON)

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. La destinazione di destinazione, ad esempio il servizio Workflows, converte l'evento in un oggetto JSON (in base alla specifica CloudEvents) e lo passa all'esecuzione del flusso di lavoro come argomento di runtime del flusso di lavoro.

Formato payload JSON

Il servizio di destinazione riceve gli eventi dai router di eventi e li formatta nel JSON Event Format for CloudEvents versione 1.0.1 con i seguenti attributi CloudEvents:

Attributo Descrizione Esempio
dati Il payload dei dati sull'evento. 

{
  "subscription": "projects/my-project/subscriptions/my-sub",
  "message": {
    "attributes": {
      "attr1":"attr1-value"
    },
    "data": "aGVsbG8gd29ybGQ=",
    "messageId": "2070443601311540",
    "publishTime":"2021-02-26T19:13:55.749Z"
  }
}
tipodicontenutidati Il tipo di dati trasmessi application/json
id L'identificatore univoco dell'evento. 2070443601311540
origine L'origine dell'evento. //pubsub.googleapis.com/projects/my-project/topics/my-topic
versione specifica La versione della specifica CloudEvents utilizzata per questo evento 1,0
tipo Il tipo di dati sugli eventi google.cloud.pubsub.topic.v1.messagePublished
tempo Ora di generazione degli eventi, in formato RFC 3339 (facoltativo) 2020-12-20T13:37:33.647Z

A seconda del tipo di evento, il formato del payload è il seguente:

Cloud Audit Logs

L'argomento runtime è un oggetto JSON che descrive in dettaglio l'evento Cloud Audit Logs. In questo documento, vedi l'esempio di eventi comuni. Nell'oggetto JSON puoi trovare i valori resourceName, serviceName e methodName. Per ulteriori informazioni, consulta Determinare i filtri eventi per Cloud Audit Logs.

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

{
  "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: i contenuti decodificati dei messaggi in formato JSON. Per saperne di più, consulta Eventi comuni in questo documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: generato dal sistema.
  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • dataschema, methodName, resourceName, serviceName, subject: attributi specifici del tipo di evento.

Cloud Storage

Gli argomenti di runtime sono modifiche a Cloud Storage. Nel campo data puoi trovare la modifica nel bucket Cloud Storage. In questo documento, vedi l'esempio di eventi comuni.

Gli eventi di tipo google.cloud.storage.object.v1.finalized hanno il seguente formato:

{
  "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: i contenuti decodificati dei messaggi in formato JSON. Per saperne di più, consulta Eventi comuni in questo documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: generato dal sistema.
  • BUCKET_NAME: il nome del bucket Cloud Storage che viene aggiornato.
  • subject: attributo specifico per il tipo di evento.

Pub/Sub

L'argomento di runtime è un messaggio push di Pub/Sub. Nel campo data puoi trovare il messaggio come stringa con codifica Base64. In questo documento, vedi l'esempio di eventi comuni.

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

{
  "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: i contenuti decodificati dei messaggi in formato JSON. Per saperne di più, consulta Eventi comuni in questo documento.
  • MESSAGE_ID, EVENT_GENERATION_TIME: generato dal sistema.
  • TOPIC_NAME: il nome dell'argomento Pub/Sub in cui è stato pubblicato l'evento.

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 protocollogoogle/events/cloud/audit/v1/events.proto
google/events/cloud/audit/v1/data.proto
Messaggio sulla bustagoogle.events.cloud.audit.v1.AuditLogWrittenEvent
Messaggio di datigoogle.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 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
(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 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 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 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
Esempi Testo