Iscriviti agli eventi utilizzando l'API Google Workspace Events

Questa pagina fornisce una panoramica dell'API Google Workspace Events e spiega come puoi usare l'API per abbonarti agli eventi su Google Workspace.

Gli eventi di Google Workspace rappresentano modifiche alle risorse di Google Workspace, ad esempio quando le risorse vengono create, aggiornate o eliminate. L'app può abbonarsi a una risorsa di Google Workspace per ricevere gli eventi pertinenti che che ti interessa.

Modalità di ricezione degli eventi da parte dell'app

Per consentire alla tua app di ricevere gli eventi di Google Workspace, utilizza la API Google Workspace Events per creare abbonamenti a Google Workspace Google Cloud.

Illustrazione di come l'API Google Workspace Events genera gli eventi.
Figura 1. Esempio di come L'API Google Workspace Events consegna gli eventi app Chat.
.

Nell'esempio seguente, ecco come funziona l'API Google Workspace Events eventi a un'app Google Chat tramite un abbonamento:

  1. Un'app di Chat si iscrive a uno spazio di Chat.
  2. Lo spazio di Chat cambia. Ad esempio, viene pubblicato un nuovo messaggio nello spazio.
  3. Chat consegna un evento per un argomento in Google Cloud Pub/Sub, che funge da endpoint di notifica per la sottoscrizione. L'evento contiene dati relativi a ciò che è cambiato. Ad esempio, nel caso di un evento relativo a un nuovo l'evento contiene i dettagli della risorsa Message che è stato creato.
  4. L'app Chat elabora i dati di Google Cloud Messaggio Pub/Sub che contiene l'evento e, se necessario, esegue un'azione.

Terminologia importante

Di seguito è riportato un elenco dei termini comuni utilizzati nelle API Google Workspace Events:

Evento Google Workspace

Una modifica a una risorsa di Google Workspace. Gli eventi vengono formattati utilizzando CloudEvents e può essere un evento di iscrizione un evento del ciclo di vita:

Evento abbonamento
Una modifica alla risorsa Google Workspace che stai monitorando, ad esempio un nuovo messaggio in uno spazio di Google Chat. Puoi specificare che vuoi ricevere sulla risorsa modificata. Per maggiori dettagli, vedi Struttura degli eventi di Google Workspace.
Evento di ciclo di vita
Un evento relativo al tuo abbonamento a Google Workspace. Eventi del ciclo di vita informarti sui problemi e sullo stato dell'abbonamento in modo che tu possa per non perdere gli eventi di abbonamento. Per impostazione predefinita, il tuo abbonamento riceve gli eventi del ciclo di vita. Per maggiori dettagli, consulta Eventi del ciclo di vita degli abbonamenti a Google Workspace.
Abbonamento a Google Workspace

Un'entità denominata che monitora una risorsa da un account Google Workspace un'applicazione. Una sottoscrizione è rappresentata da un Subscription risorsa. Un abbonamento viene definito dalle seguenti informazioni:

Risorsa di destinazione
La risorsa Google Workspace che vuoi monitorare. Questa risorsa è rappresentata nel campo targetResource della abbonamento a Google Workspace. Ogni abbonamento può eseguire e monitorare una risorsa. Per vedere quali risorse Google Workspace supporta l'API Google Workspace Events, vedi Eventi di Google Workspace supportati.
Tipi di evento
I tipi di modifiche per cui vuoi ricevere notifiche la risorsa di destinazione. Ad esempio, se hai sottoscritto un abbonamento a spazio di Google Chat, puoi scegliere se ricevere eventi su lo spazio e le relative risorse figlio, come le iscrizioni e i messaggi.
Endpoint di notifica
L'endpoint in cui L'abbonamento a Google Workspace riceve eventi. La L'API Google Workspace Events supporta gli argomenti Google Cloud Pub/Sub come un endpoint di notifica. Per saperne di più sull'uso di Google Cloud Pub/Sub, vedi il documentazione di Google Cloud Pub/Sub.
Opzioni di payload
I dati sugli eventi che vuoi ricevere sulle risorse modificate.

Eventi di Google Workspace supportati

Gli eventi a cui la tua app può ricevere eventi dipendono dalla risorsa di destinazione di l'abbonamento. La tabella seguente mostra gli eventi supportati per ogni una possibile risorsa target.

Risorsa di destinazione Eventi supportati
Spazi di Google Chat
  • Messaggi
  • Abbonamenti
  • Reazioni
  • Spazio
Utenti di Google Chat
  • Abbonamenti
Spazi per le riunioni di Google Meet
  • Conferenze
  • Sessioni dei partecipanti
  • Registrazioni
  • Trascrizioni
Utenti di Google Meet
  • Conferenze
  • Sessioni dei partecipanti
  • Registrazioni
  • Trascrizioni

Per saperne di più, consulta le seguenti guide:

Struttura degli eventi di Google Workspace

Gli eventi Google Workspace seguono CloudEvents specifiche, che è un metodo standard di settore per descrivere i dati sugli eventi. Google Workspace contengono quanto segue:

  • Attributi del CloudEvent.
  • Dati sulla risorsa Google Workspace che è cambiata per effetto di l'evento

La seguente sezione spiega la struttura degli attributi e dei dati per Eventi di Google Workspace.

Attributi CloudEvent

Gli eventi di Google Workspace contengono quanto segue: Attributi CloudEvents:

Attributo Descrizione Esempio

datacontenttype

Il tipo di dati trasmessi nell'evento.

application/json

id

Identificatore per l'evento CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

L'origine dell'evento. Per gli eventi di Google Workspace, si tratta del nome completo della risorsa della sottoscrizione. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

La versione della specifica CloudEvents utilizzata per questo evento.

1.0

subject

La risorsa Google Workspace in cui si è verificato l'evento.

//chat.googleapis.com/spaces/AAAABBBBBBB

time

Il timestamp in cui si è verificato l'evento, nel formato RFC 3339.

2023-09-07T21:37:36.260127Z

type

Il tipo di evento di Google Workspace.

google.workspace.chat.message.v1.created

Dati sugli eventi

I dati sugli eventi sono un payload che rappresenta una modifica al target del tuo abbonamento e quella secondaria, incluse le risorse figlio della risorsa di destinazione. Nel tuo abbonamento, puoi specificare se vuoi che il payload includa i dati su la risorsa modificata o solo il nome della risorsa modificata.

Ad esempio, se hai un'iscrizione a uno spazio di Chat, può ricevere eventi relativi a nuovi messaggi nello spazio. Per eventi su nuovi messaggi, i dati degli eventi contengono un payload spaces.message risorsa creata.

Quando crei una sottoscrizione, puoi specificare la quantità di dati delle risorse inclusi negli eventi ricevuti dall'app:

  • Includi dati risorsa: contiene alcuni o tutti i campi relativi alle modifiche apportate risorsa. Se scegli di includere i dati delle risorse, la sottoscrizione la durata è limitata a un massimo di 4 ore o 24 ore se utilizzi a livello di dominio delega.
  • Escludi dati risorsa: contiene solo il nome della risorsa modificata risorsa. La durata dell'abbonamento è fino a 7 giorni. Per avere informazioni dettagliate su all'evento, puoi eseguire una query sulla risorsa utilizzando il relativo nome.

Queste opzioni per i dati sugli eventi sono rappresentate nel payloadOptions campo della tua sottoscrizione.

Eventi come messaggi Google Cloud Pub/Sub

Gli abbonamenti all'API Google Workspace Events utilizzano Google Cloud Pub/Sub argomenti come endpoint di notifica che riceve Google Workspace eventi. Gli eventi sono codificati come messaggi Google Cloud Pub/Sub. La tua app possono elaborare il messaggio Google Cloud Pub/Sub per agire o rispondere l'evento.

L'esempio seguente mostra un messaggio Google Cloud Pub/Sub che contiene un evento relativo a un messaggio aggiornato in uno spazio di Chat:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

Tieni presente i seguenti campi:

  • attributes: attributi per CloudEvent, che includono il tipo di evento. In questo caso, l'evento riguarda un messaggio aggiornato nella spazio.
  • data: i dati sugli eventi con i dettagli sull'aggiornamento Risorsa spaces.message, formattata come stringa con codifica Base64.
  • messageId: l'identificatore del messaggio Google Cloud Pub/Sub.

Scopri di più su come gli eventi Cloud vengono specificati in Google Cloud Pub/Sub. vedi Associazione di protocolli Google Cloud Pub/Sub per CloudEvents.