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 Eventi e spiega come utilizzare l'API per abbonarti agli eventi su Google Workspace.

Gli eventi 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 di Google Workspace in modo da ricevere eventi pertinenti che ti interessano.

In che modo la tua app riceve eventi

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

Illustrazione di come l'API Google Workspace Event fornisce eventi.

Ecco come l'API Google Workspace Event fornisce eventi nella tua app tramite un abbonamento:

L'app si abbona a una risorsa in un'applicazione Google Workspace, ad esempio uno spazio di Google Chat.
La risorsa a cui hai effettuato l'iscrizione cambia.
L'applicazione Google Workspace fornisce un evento in un argomento in Google Cloud Pub/Sub, che funge da endpoint di notifica per l'abbonamento a Google Workspace. L'evento contiene dati su cosa è cambiato nella risorsa.
La tua app 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 Eventi:

Evento Google Workspace

Una modifica a una risorsa Google Workspace. Gli eventi vengono formattati utilizzando la specifica CloudEvents e possono essere un evento di abbonamento o 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 quanti dettagli vuoi ricevere sulla risorsa modificata. Per maggiori dettagli, consulta Struttura degli eventi di Google Workspace.
Evento ciclo di vita: Un evento relativo al tuo abbonamento a Google Workspace. Gli eventi del ciclo di vita ti informano dei problemi e dello stato dell'abbonamento, in modo che tu possa evitare la perdita di eventi di abbonamento. Per impostazione predefinita, la sottoscrizione 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 viene 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 sapere quali risorse Google Workspace sono supportate dall'API Google Workspace Eventi, consulta Eventi Google Workspace supportati.
Tipi di eventi: I tipi di modifiche per 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 figlio, come le iscrizioni e i messaggi.
Endpoint di notifica: L'endpoint in cui l'abbonamento a Google Workspace riceve eventi. L'API Google Workspace Eventi 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 per le risorse modificate.

Eventi di Google Workspace supportati

Gli eventi che l'app può ricevere dipendono dalla risorsa di destinazione dell'abbonamento. La tabella seguente 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	`//chat.googleapis.com/spaces/SPACE_ID`	Messaggi Abbonamenti Reazioni Spazio Per maggiori dettagli, consulta Iscriviti 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, consulta Iscriviti agli eventi di Google Chat.	L'abbonamento riceve soltanto gli eventi relativi all'utente che l'ha autorizzato. 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 Iscriviti 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 Iscriviti agli eventi di Google Meet.	L'abbonamento riceve eventi relativi agli spazi per le 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 per le riunioni.

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 Google Workspace contengono quanto segue:

Attributi del CloudEvent.
Dati relativi alla risorsa Google Workspace che è stata modificata a seguito dell'evento

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

Attributo	Descrizione	Esempio
`datacontenttype`	Il tipo di dati trasmessi nell'evento.	`application/json`
`id`	Un identificatore per il 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 del momento in cui si è verificato l'evento, nel formato RFC 3339.	`2023-09-07T21:37:36.260127Z`
`type`	Il tipo di evento 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 dell'abbonamento, incluse le risorse figlio della risorsa di destinazione. Nell'abbonamento puoi specificare se il payload deve includere i dati relativi alla risorsa modificata o solo il nome della risorsa modificata.

Ad esempio, se hai un abbonamento a uno spazio di Chat, puoi ricevere eventi per i 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 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 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 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 Eventi 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 contenente 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 degli eventi 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 gli eventi CloudEvents nei messaggi di Google Cloud Pub/Sub, consulta Associazione del protocollo di Google Cloud Pub/Sub per CloudEvents.

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