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. La tua app può abbonarsi a una risorsa Google Workspace in modo da ricevere gli eventi pertinenti che ti interessano.

Come la tua app riceve gli eventi

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

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

1. Un'app Chat si iscrive a uno spazio di Chat.
2. Modifiche allo spazio Chat. 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 dettagli sulla risorsa Message creata.
4. L'app di Chat elabora il messaggio Google Cloud Pub/Sub che contiene l'evento e, se necessario, interviene.

Terminologia importante

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

Evento Google Workspace

Modifica di una risorsa 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 Google Workspace che stai monitorando, ad esempio un nuovo messaggio in uno spazio 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 di problemi e dello stato del tuo abbonamento in modo che tu possa evitare di perdere eventi dell'abbonamento. Per impostazione predefinita, il tuo 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 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 una sola risorsa. Per vedere quali risorse di Google Workspace sono supportate dall'API Google Workspace Events, consulta Eventi Google Workspace supportati.

Tipi di evento

I tipi di modifiche per cui vuoi ricevere una notifica per la risorsa di destinazione. Ad esempio, se hai eseguito l'iscrizione a uno spazio Google Chat, puoi scegliere se ricevere eventi relativi allo spazio e alle relative risorse secondarie, come iscrizioni 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 payload

I dati sugli eventi che vuoi ricevere sulle risorse modificate.

Eventi 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 risorsa di destinazione possibile.

Per saperne di più, consulta le seguenti guide:

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

Struttura degli eventi di Google Workspace

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

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

La seguente sezione 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 degli eventi sono un payload che rappresenta una modifica alla risorsa di destinazione dell'abbonamento, incluse le risorse secondarie della risorsa di destinazione. Nell'abbonamento, puoi specificare se vuoi che il payload includa 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 sui nuovi messaggi nello spazio. Per gli eventi relativi ai nuovi messaggi, i dati dell'evento contengono un payload con la risorsa spaces.message di Chat creata.

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

• Includi dati 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 dati risorsa: contiene solo il nome della risorsa modificata. La durata dell'abbonamento è di massimo 7 giorni. Per ottenere dettagli sull'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 argomenti Google Cloud Pub/Sub come endpoint di notifica che riceve gli eventi di Google Workspace. Gli eventi vengono 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"
    }
}

Tieni presente i seguenti campi:

• attributes: Attributi per CloudEvent, incluso il tipo di evento. In questo caso, l'evento riguarda un messaggio aggiornato nello spazio.
• data: i dati evento con i dettagli della risorsa spaces.message aggiornata, formattati come stringa con codifica Base64.
• messageId: l'identificatore del messaggio Google Cloud Pub/Sub.

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

Argomenti correlati

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