Questa pagina è stata tradotta dall'API Cloud Translation.

Iscriviti agli eventi utilizzando l'API Google Workspace Events

Questa pagina fornisce una panoramica dell'API Google Workspace Events e spiega come utilizzarla per abbonarsi agli eventi di Google Workspace.

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

Modalità di ricezione degli eventi da parte dell'app

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

Illustrazione di come l'API Google Workspace Events genera gli eventi. — **Figura 1.** Esempio di come l'API Google Workspace Events consegna gli eventi in un'app di Chat.

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

Un'app di Chat si iscrive a uno spazio di Chat.
Lo spazio di Chat cambia. Ad esempio, viene pubblicato un nuovo messaggio nello spazio.
Chat consegna un evento a un argomento in Google Cloud Pub/Sub, che funge da endpoint di notifica per la sottoscrizione. L'evento contiene dati su cosa è cambiato. Ad esempio, un evento relativo a un nuovo messaggio contiene dettagli sulla risorsa Message creata.
L'app Chat elabora il messaggio Pub/Sub di Google Cloud che contiene l'evento e, se necessario, agisce.

Terminologia importante

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

Evento Google Workspace

Una modifica a una risorsa di Google Workspace. Gli eventi vengono formattati utilizzando la specifica CloudEvents e possono essere un evento di abbonamento o un evento di 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 quanti dettagli vuoi ricevere sulla risorsa che è stata modificata. Per maggiori dettagli, consulta Struttura degli eventi di Google Workspace.
Evento di ciclo di vita: Un evento relativo al tuo abbonamento a Google Workspace. Gli eventi del ciclo di vita ti avvisano dei problemi e dello stato dell'abbonamento, in modo da evitare di perdere 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 degli abbonamenti a Google Workspace.

Abbonamento a Google Workspace

Un'entità denominata che monitora una risorsa da un'applicazione Google Workspace. Una sottoscrizione è rappresentata da una risorsa Subscription. Un abbonamento viene 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 Google Workspace sono supportate dall'API Google Workspace Events, vedi Eventi Google Workspace supportati.
Tipi di evento: I tipi di modifiche per cui vuoi ricevere notifiche relative alla 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 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 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 eventi dipendono dalla risorsa di destinazione dell'abbonamento. La seguente tabella mostra gli eventi supportati per ogni possibile risorsa di destinazione.

Risorsa di destinazione	Formato	Eventi supportati	Limitazioni (se applicabili)
Google Chat
Spazi di Google Chat	Per abbonarti a uno spazio specifico: `//chat.googleapis.com/spaces/SPACE_ID` Per abbonarti a tutti gli spazi di cui l'utente è membro: `//chat.googleapis.com/spaces/-`	Messaggi Abbonamenti Reazioni Spazio Per maggiori dettagli, vedi Iscriversi agli eventi di Google Chat.	L'utente di Google Chat che autorizza l'abbonamento deve essere membro dello spazio tramite il proprio Account Google Workspace o Google.
Utenti di Google Chat	`//cloudidentity.googleapis.com/users/USER_ID`	Abbonamenti Per maggiori dettagli, vedi Iscriversi agli eventi di Google Chat.	L'abbonamento riceve soltanto gli eventi relativi all'utente che li ha autorizzati. Un utente non può autorizzare un abbonamento per conto di altri utenti.
Google Meet
Spazi per le riunioni di Google Meet	`//meet.googleapis.com/spaces/SPACE_ID`	Conferenze Sessioni dei partecipanti Registrazioni Trascrizioni Per maggiori dettagli, vedi Abbonarsi agli eventi di Google Meet.
Utenti di Google Meet	`//cloudidentity.googleapis.com/users/USER_ID`	Conferenze Sessioni dei partecipanti Registrazioni Trascrizioni Per maggiori dettagli, vedi Abbonarsi agli eventi di Google Meet.	L'abbonamento riceve eventi relativi agli spazi per riunioni in cui l'utente è uno dei seguenti: Il proprietario dello spazio per le riunioni. L'organizzatore dell'evento di Google Calendar associato allo spazio delle riunioni.

Struttura degli eventi di Google Workspace

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

Attributi del CloudEvent.
Dati relativi alla risorsa Google Workspace che sono stati modificati in seguito all'evento

La sezione seguente illustra 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:

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 Google Workspace, si tratta del nome completo della risorsa dell'abbonamento.	`//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 alla risorsa di destinazione della sottoscrizione, incluse le risorse figlio della risorsa di destinazione. Nel tuo abbonamento puoi specificare se desideri che il payload includa i dati sulla risorsa modificata o solo il nome della risorsa modificata.

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

Quando crei un abbonamento, puoi specificare la quantità di dati delle risorse inclusi negli eventi ricevuti dall'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 di 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 è fino a 7 giorni. Per ottenere i dettagli sull'evento, puoi eseguire una query sulla risorsa utilizzando il relativo nome.

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 ricevono gli eventi Google Workspace. Gli eventi sono codificati come messaggi Google Cloud Pub/Sub. La tua app può elaborare il messaggio Google Cloud Pub/Sub per agire 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 dell'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 gli eventi Cloud vengono specificati nei messaggi Google Cloud Pub/Sub, consulta Associazione di protocolli Google Cloud Pub/Sub per CloudEvents.

Iscriversi agli eventi di Google Chat
Eventi del ciclo di vita degli abbonamenti a Google Workspace
Scegliere gli ambiti dell'API Google Workspace Events
Creare un abbonamento a Google Workspace