In questa pagina vengono descritti gli eventi di Google Chat a cui un'app Google Chat può abbonarsi utilizzando l'API Google Workspace Events. Dopo aver deciso i tipi di eventi di cui hai bisogno, crea un abbonamento per iniziare a ricevere gli eventi da Google Chat.
Oltre a iscriverti agli eventi, puoi anche eseguire query sugli eventi chiamando l'API Chat. Le chiamate all'API Chat consentono di recuperare gli eventi su base periodica o di recuperare gli eventi che potrebbero non essere stati inclusi nell'abbonamento a causa di un'interruzione del servizio. Per scoprire di più su come ricevere e rispondere agli eventi di Chat, vedi Utilizzare gli eventi di Google Chat nella documentazione di Chat.
Risorse di destinazione di Chat supportate
L'API Google Workspace Events supporta abbonamenti per:
- Spazi, rappresentati come risorse
space - Utenti, rappresentati come risorse
userdell'API Cloud Identity
Eventi di Chat supportati
Gli abbonamenti a Google Workspace ti consentono di ricevere in Chat eventi relativi ai seguenti tipi di modifiche:
- Messaggi nuovi, aggiornati o eliminati nello spazio.
- reazioni nuove o rimosse a un messaggio.
- Membri nuovi, aggiornati o rimossi dello spazio.
- Modifiche allo spazio per cui hai effettuato l'iscrizione, ad esempio il nome o la descrizione aggiornati dello spazio.
Tipi di eventi per la creazione di sottoscrizioni
Quando crei una sottoscrizione, utilizzi il campo eventTypes[] per specificare i tipi di eventi che vuoi ricevere. I tipi di eventi vengono
formattati in base alla specifica CloudEvents, ad esempio
google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.
Ad esempio, per ricevere eventi relativi agli utenti che entrano in uno spazio di Chat, puoi specificare lo spazio come risorsa di destinazione e il tipo di evento google.workspace.chat.membership.v1.created. Per ricevere eventi relativi a un determinato utente che entra in uno spazio, devi specificare l'utente come risorsa di destinazione e il tipo di evento google.workspace.chat.membership.v1.created. Per scoprire di più su
come funzionano gli eventi, consulta Struttura degli eventi
di Google Workspace.
La tabella seguente mostra i tipi di eventi supportati per le iscrizioni agli spazi e le sottoscrizioni agli utenti. Per scoprire di più sulle eccezioni relative agli elementi che attivano un evento, consulta Limitazioni.
| Tipo di evento | Formato | Dati delle risorse | ||
|---|---|---|---|---|
| Abbonamenti a spazi | ||||
| È stato pubblicato un messaggio. |
|
|
||
| Viene aggiornato un messaggio. |
|
|
||
| È stato eliminato un messaggio. |
|
|
||
| Viene creata una reazione. |
|
|
||
| Viene eliminata una reazione. |
|
|
||
| Un membro è stato aggiunto allo spazio. |
|
|
||
| Un membro è stato aggiornato nello spazio. |
|
|
||
| Un membro è stato rimosso dallo spazio. |
|
|
||
| Lo spazio è aggiornato. |
|
|
||
| Lo spazio è stato eliminato. |
|
|
||
| Abbonamenti per gli utenti | ||||
| L'utente diventa membro di uno spazio.
Non tutti i nuovi membri attivano eventi. Per maggiori dettagli, vedi Limitazioni |
|
|
||
| L'appartenenza dell'utente a uno spazio viene aggiornata. |
|
|
||
| L'utente viene rimosso come membro diretto di uno spazio. |
|
|
||
Tipi di eventi batch (solo output)
Oltre a ricevere i tipi di eventi a cui hai effettuato l'iscrizione, l'app Chat potrebbe anche ricevere eventi batch. Un evento batch è un evento che rappresenta molti eventi dello stesso tipo che si verificano in un breve periodo di tempo. Il payload di un evento batch contiene un elenco di tutte le risorse modificate.
Ad esempio, se un utente aggiunge contemporaneamente 20 utenti a uno spazio, l'app Chat potrebbe ricevere un evento batch
(google.workspace.chat.membership.v1.batchCreated). Il payload dell'evento contiene
un elenco di tutte le nuove risorse Membership create quando l'utente
ha aggiunto i membri allo spazio.
Ricevi un evento batch per qualsiasi tipo di evento a cui hai sottoscritto l'abbonamento, quindi non è necessario specificare eventi batch quando crei una sottoscrizione. Ad
esempio, se ti abboni a nuove reazioni
(google.workspace.chat.reaction.v1.created), la tua
app Chat viene configurata automaticamente per ricevere eventi di reazione
in batch (google.workspace.chat.reaction.v1.batchCreated).
La tabella seguente mostra i possibili eventi batch per una sottoscrizione:
| Tipo di evento batch | Formato |
|---|---|
| Vengono pubblicati più messaggi. |
|
| Vengono aggiornati più messaggi. |
|
| Vengono eliminati più messaggi. |
|
| Vengono create più reazioni. |
|
| Vengono eliminate più reazioni. |
|
| Più membri vengono aggiunti allo spazio a cui hai effettuato l'iscrizione oppure l'utente che ha effettuato l'iscrizione è stato aggiunto a più spazi. |
|
| Gli abbonamenti multipli vengono aggiornati nello spazio a cui hai effettuato l'iscrizione o per l'utente che ha effettuato l'iscrizione. |
|
| Più membri vengono rimossi dallo spazio a cui hai effettuato l'iscrizione oppure l'utente che ha effettuato l'iscrizione è stato rimosso da più spazi. |
|
| Lo spazio ha diversi aggiornamenti. |
|
Dati sugli eventi
Questa sezione descrive i dati sugli eventi e i payload di esempio per gli eventi in Chat.
Quando il tuo abbonamento a Google Workspace riceve un evento da Chat, il campo data contiene il payload per l'evento. Questo payload contiene informazioni sulla risorsa Google Workspace che è stata modificata. Ad esempio, se hai effettuato l'iscrizione a eventi di appartenenza in uno spazio, il payload per questi eventi contiene informazioni sulla risorsa spaces.membership che è stata modificata.
Dati delle risorse nel payload dell'evento
Quando crei una sottoscrizione, puoi specificare se vuoi che il payload includa i dettagli della risorsa o solo il nome della risorsa. Ad esempio, se vuoi ricevere eventi relativi ai membri in uno spazio di Chat, puoi specificare quali campi di una risorsa di appartenenza vuoi ricevere nel payload dell'evento.
La tabella seguente fornisce esempi di payload JSON per una sottoscrizione allo spazio di Chat spaces/AAAABBBBBB. Per ogni evento ricevuto dalla sottoscrizione, il payload viene visualizzato nel campo data dell'evento:
| Esempio | Tipo di evento | Payload JSON |
|---|---|---|
Un utente pubblica nello spazio un messaggio con scritto "Hello world". |
|
Include i dati delle risorse
{
"message":
{
"name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD",
"sender":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "2023-09-07T21:37:36.260127Z",
"text": "Hello world",
"thread":
{
"name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE"
},
"space":
{
"name": "spaces/AAAABBBBBB"
},
"argumentText": "Hello world"
}
}
Esclude i dati delle risorse
{
"message":
{
"name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
}
}
|
| Un utente diventa un gestore dello spazio. |
|
Include i dati delle risorse
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321",
"state": "JOINED",
"member":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MANAGER"
}
}
Esclude i dati delle risorse
{
"membership":
{
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
}
|
| Un utente aggiorna la descrizione dello spazio in "Team di vendita di Cymbal Labs". | google.workspace.chat.space.v1.updated |
Include i dati delle risorse
{
"space":
{
"name": "spaces/AAAABBBBBB",
"displayName": "Cymbal Sales",
"spaceThreadingState": "THREADED_MESSAGES",
"spaceType": "SPACE",
"spaceDetails":
{
"description": "Sales team for Cymbal Labs."
},
"spaceHistoryState": "HISTORY_ON"
}
}
Esclude i dati delle risorse
{
"space":
{
"name": "spaces/AAAABBBBBB"
}
}
|
| Due utenti di Chat sono stati aggiunti allo spazio contemporaneamente. | google.workspace.chat.membership.v1.batchCreated |
Include i dati delle risorse
{
"memberships": [
{
"membership": {
"name": "spaces/AAAABBBBBB/members/1234567890987654321",
"state": "JOINED",
"member":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MEMBER"
}
},
{
"membership": {
"name": "spaces/AAAABBBBBB/members/987654321234567890",
"state": "JOINED",
"member":
{
"name": "users/987654321234567890",
"type": "HUMAN"
},
"createTime": "1970-01-01T00:00:00Z",
"role": "ROLE_MEMBER"
}
}
]
}
Esclude i dati delle risorse
{
"memberships": [
{
"membership": {
"name": "spaces/AAAABBBBBB/members/1234567890987654321"
}
},
{
"membership": {
"name": "spaces/AAAABBBBBB/members/98765432123456789019"
}
}
]
}
|
| Un utente reagisce a un messaggio con l'emoji 😊. | google.workspace.chat.reaction.v1.created |
Include i dati delle risorse
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
"user":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😊"
}
}
}
I dati delle risorse vengono omessi
{
"reaction":
{
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
}
}
|
| Gli utenti reagiscono a un messaggio con le emoji 😊 e ⧖. | google.workspace.chat.reaction.v1.batchCreated |
Include i dati delle risorse
{
"reactions": [
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
"user":
{
"name": "users/1234567890987654321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😊"
}
}
},
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
"user":
{
"name": "users/98765431234564321",
"type": "HUMAN"
},
"emoji":
{
"unicode": "😸"
}
}
}
]
}
I dati delle risorse vengono omessi
{
"reactions": [
{
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
},
"reaction": {
"name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
}
}
]
}
|
Limitazioni
-
Per le iscrizioni agli utenti, gli eventi relativi ai nuovi membri in messaggi diretti o chat di gruppo senza nome (
google.workspace.chat.membership.v1.created) vengono attivati solo dopo la pubblicazione del primo messaggio. - Le modifiche alla cronologia degli spazi non attivano gli eventi aggiornati dello spazio (tipo di evento:
google.workspace.chat.spaces.v1.updated). - Per ricevere eventi di iscrizione, l'utente deve essere un membro diretto dello spazio. Se un utente è stato aggiunto, aggiornato o rimosso indirettamente a uno spazio tramite un gruppo Google, l'abbonamento non riceve questi eventi di appartenenza. Per capire come funzionano le iscrizioni a gruppi Google, vedi Aggiungere un gruppo Google a uno spazio.
Argomenti correlati
- Struttura degli eventi di Google Workspace
- Scegli gli ambiti OAuth
- Creare un abbonamento per ricevere eventi di Chat