Iscriviti agli eventi utilizzando l'API Google Workspace Events

Questa pagina fornisce una panoramica dell'API Google Workspace Events e spiega come utilizzarla per iscriversi 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. Utilizza l'API Google Workspace Events per iscriverti a una risorsa di Google Workspace e ricevere gli eventi pertinenti.

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 abbonamenti alle risorse di Google Workspace.

L'esempio seguente descrive come l'API Google Workspace Events invia gli eventi a un'app di chat tramite un abbonamento:

1. Un'app di Chat si abbona a uno spazio di Chat di Google.
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 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 di chat elabora il messaggio Google Cloud Pub/Sub che contiene l'evento e, se necessario, intraprende un'azione.

Terminologia importante

I termini comuni utilizzati nell'API Google Workspace Events includono:

Evento di Google Workspace

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

Evento di abbonamento

Una modifica alla risorsa di Google Workspace che stai monitorando, ad esempio un nuovo messaggio in uno spazio di chat. Puoi specificare la quantità di dettagli 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 del tuo abbonamento, in modo che tu possa evitare di perdere gli eventi di abbonamento. Per impostazione predefinita, l'abbonamento riceve sempre gli eventi del ciclo di vita. Per maggiori dettagli, vedi 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 Subscription risorsa. Un abbonamento è definito dalle seguenti informazioni:

Risorsa di destinazione

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

Tipi di eventi

I tipi di modifiche di cui vuoi ricevere una notifica per la risorsa di destinazione. Ad esempio, se ti sei abbonato a uno spazio di chat, puoi scegliere se ricevere eventi relativi allo spazio e alle relative risorse figlio, come abbonamenti 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 saperne di più sull'utilizzo di Google Cloud Pub/Sub, consulta la 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 che la tua app può ricevere dipendono dalla risorsa di destinazione dell'abbonamento. La tabella seguente mostra gli eventi supportati per ogni possibile risorsa di destinazione.

Per saperne di più, consulta le guide seguenti:

• Abbonarsi agli eventi di Chat
• Abbonarsi agli eventi di Drive
• Abbonarsi agli eventi di Meet

Struttura degli eventi di Google Workspace

Gli eventi di Google Workspace seguono la specifica CloudEvents, che è un modo standard di settore per descrivere i dati sugli eventi. Gli eventi di Google Workspace contengono:

• Attributi di CloudEvent.
• Dati sulla risorsa di Google Workspace modificata a seguito dell'evento

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

Attributi CloudEvent

Gli eventi di 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 figlio della risorsa di destinazione. Nell'abbonamento, 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 spaces.message di Chat creata.

Quando crei un abbonamento, puoi specificare la quantità di dati sulle risorse inclusi negli eventi ricevuti dalla tua app.

Queste opzioni per i dati sugli eventi sono rappresentate nel payloadOptions campo dell'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 di Google Workspace. Gli eventi sono codificati come messaggi Google Cloud Pub/Sub. La tua app può elaborare il messaggio Google Cloud Pub/Sub per intraprendere un'azione 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"
    }
}

Questo esempio contiene i seguenti campi:

• attributes: attributi di 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 risorsa aggiornata spaces.message, formattati come stringa codificata in Base64.
• messageId: l'identificatore del messaggio Google Cloud Pub/Sub.

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

Argomenti correlati

• Scegliere gli ambiti dell'API Google Workspace Events
• Creare un abbonamento a Google Workspace