Iscriviti agli eventi utilizzando l'API Google Workspace Events

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

Gli eventi di Google Workspace rappresentano le modifiche alle risorse di Google Workspace, ad esempio quando le risorse vengono create, aggiornate o eliminate. La tua app può iscriversi a una risorsa Google Workspace in modo da ricevere eventi pertinenti che ti interessano.

Come la tua app riceve gli eventi

Per consentire alla tua app di ricevere gli eventi di Google Workspace, utilizza l'API Google Workspace Events per creare iscrizioni alle risorse di Google Workspace.

Nell'esempio seguente viene mostrato come l'API Google Workspace Events invia gli 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 invia un evento a un argomento in Google Cloud Pub/Sub, che funge da endpoint di notifica per l'abbonamento. L'evento contiene i dati sulle modifiche. Ad esempio, per un evento relativo a un nuovo messaggio, l'evento contiene i dettagli della risorsa Message creata.
4. L'app Chat elabora il messaggio Pub/Sub di Google Cloud contenente l'evento e, se necessario, interviene.

Terminologia importante

Di seguito è riportato un elenco di termini comuni utilizzati nell'API Google Workspace Events:

Evento Google Workspace

Una modifica a una risorsa Google Workspace. Gli eventi sono formattati utilizzando la specifica CloudEvents e possono essere un evento di sottoscrizione o un evento di ciclo di vita:

Evento di sottoscrizione

Una modifica alla risorsa Google Workspace che stai monitorando, come un nuovo messaggio in uno spazio di Google Chat. Puoi specificare il livello di dettaglio che vuoi ricevere sulla risorsa modificata. Per maggiori dettagli, vedi Struttura degli eventi di Google Workspace.

Evento del ciclo di vita

Un evento relativo al tuo abbonamento a Google Workspace. Gli eventi del ciclo di vita ti informano sui problemi e sullo stato dell'abbonamento in modo da evitare di perderti eventi di abbonamento. Per impostazione predefinita, il tuo abbonamento riceve sempre gli eventi del ciclo di vita. Per maggiori dettagli, consulta Eventi del ciclo di vita per gli abbonamenti a Google Workspace.

Abbonamento a Google Workspace

Un'entità denominata che monitora una risorsa da un'applicazione Google Workspace. Un abbonamento è rappresentato da una risorsa Subscription. Un abbonamento è definito dalle seguenti informazioni:

Risorsa di destinazione

La risorsa Google Workspace che vuoi monitorare. Questa risorsa è rappresentata nel campo targetResource dell'abbonamento a Google Workspace. Ogni abbonamento può monitorare solo una risorsa. Per sapere quali risorse di Google Workspace sono supportate dall'API Google Workspace Events, consulta Eventi di Google Workspace supportati.

Tipi di evento

I tipi di modifiche di cui vuoi ricevere una notifica per la risorsa di destinazione. Ad esempio, se hai effettuato l'iscrizione a uno spazio di Google Chat, puoi scegliere se ricevere eventi relativi allo spazio e alle relative risorse secondarie, come adesioni e messaggi.

Endpoint di notifica

L'endpoint in cui l'abbonamento a Google Workspace riceve gli eventi. L'API Google Workspace Events supporta gli argomenti Google Cloud Pub/Sub come endpoint di notifica. Per scoprire di più sull'utilizzo di Google Cloud Pub/Sub, consulta la documentazione di Google Cloud Pub/Sub.

Opzioni del payload

I dati sugli eventi che vuoi ricevere relativi alle risorse modificate.

Eventi di Google Workspace supportati

Gli eventi che la tua app può ricevere dipendono dalla risorsa di destinazione del tuo abbonamento. La tabella seguente mostra gli eventi supportati per ogni possibile risorsa di destinazione.

Per saperne di più, consulta le seguenti guide:

• Iscriverti agli eventi di Google Chat
• Iscriverti agli eventi di Google Meet

Struttura degli eventi di Google Workspace

Gli eventi di Google Workspace rispettano la specifica CloudEvents, che è uno standard di settore per la descrizione dei dati sugli eventi. Gli eventi Google Workspace contengono quanto segue:

• Attributi di CloudEvent.
• Dati sulla risorsa Google Workspace modificata in seguito all'evento

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

Attributi CloudEvent

Gli eventi Google Workspace contengono i seguenti attributi CloudEvents obbligatori:

Dati sugli eventi

I dati sugli eventi sono un payload che rappresenta una modifica alla risorsa di destinazione dell'abbonamento, incluse le risorse secondarie della risorsa di destinazione. Nell'subscription, puoi specificare se vuoi che il payload includa i dati sulla risorsa modificata o solo il nome della risorsa modificata.

Ad esempio, se hai un abbonamento a uno spazio di Chat, puoi ricevere eventi relativi ai nuovi messaggi nello spazio. Per gli eventi relativi ai nuovi messaggi, i dati sugli eventi contengono un payload con la risorsa Chatspaces.message creata.

Quando crei un abbonamento, puoi specificare la quantità di dati delle risorse da includere negli eventi ricevuti dalla tua app:

• Includi i dati della risorsa:contiene alcuni o tutti i campi della risorsa modificata. Se scegli di includere i dati delle risorse, la durata dell'abbonamento è limitata a un massimo di 4 ore o 24 ore se utilizzi la delega a livello di dominio.
• Escludi i dati della risorsa: contiene solo il nome della risorsa modificata. La durata dell'abbonamento può essere fino a 7 giorni. Per ottenere i dettagli dell'evento, puoi eseguire una query sulla risorsa utilizzando il nome della risorsa.

Queste opzioni per i dati sugli eventi sono rappresentate nel campo payloadOptions del tuo abbonamento.

Eventi come messaggi Google Cloud Pub/Sub

Gli abbonamenti all'API Google Workspace Events utilizzano gli argomenti Google Cloud Pub/Sub come endpoint di notifica che riceve gli eventi Google Workspace. Gli eventi vengono codificati come messaggi Google Cloud Pub/Sub. La tua app può elaborare il messaggio Google Cloud Pub/Sub per intervenire o rispondere all'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 nello spazio.
• data: i dati sugli eventi con i dettagli della risorsaspaces.message aggiornata, formattata come stringa con codifica Base64.
• messageId: l'identificatore del messaggio Google Cloud Pub/Sub.

Per scoprire di più su come vengono specificati i CloudEvents nei messaggi Google Cloud Pub/Sub, consulta Binding del protocollo Google Cloud Pub/Sub per CloudEvents.

Argomenti correlati

• Iscriverti agli eventi di Google Chat
• Iscriverti agli eventi di Google Meet
• Eventi del ciclo di vita per gli abbonamenti a Google Workspace
• Scegliere gli ambiti dell'API Google Workspace Events
• Creare un abbonamento a Google Workspace