Questa pagina fornisce una panoramica dell'API Google Workspace Events e spiega come puoi usare l'API per abbonarti agli eventi su Google Workspace.
Gli eventi di Google Workspace rappresentano modifiche alle risorse di Google Workspace, ad esempio quando le risorse vengono create, aggiornate o eliminate. L'app può abbonarsi a una risorsa di Google Workspace per ricevere gli eventi pertinenti che che ti interessa.
Modalità di ricezione degli eventi da parte dell'app
Per consentire alla tua app di ricevere gli eventi di Google Workspace, utilizza la API Google Workspace Events per creare abbonamenti a Google Workspace Google Cloud.
Nell'esempio seguente, ecco come funziona l'API Google Workspace Events 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 per un argomento in
Google Cloud Pub/Sub,
che funge da endpoint di notifica per la sottoscrizione. L'evento
contiene dati relativi a ciò che è cambiato. Ad esempio, nel caso di un evento relativo a un nuovo
l'evento contiene i dettagli della risorsa
Message
che è stato creato. - L'app Chat elabora i dati di Google Cloud Messaggio Pub/Sub che contiene l'evento e, se necessario, esegue un'azione.
Terminologia importante
Di seguito è riportato un elenco dei termini comuni utilizzati nelle API Google Workspace Events:
- Evento Google Workspace
Una modifica a una risorsa di Google Workspace. Gli eventi vengono formattati utilizzando CloudEvents e può essere un evento di iscrizione 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 che vuoi ricevere sulla risorsa modificata. Per maggiori dettagli, vedi Struttura degli eventi di Google Workspace.
- Evento di ciclo di vita
- Un evento relativo al tuo abbonamento a Google Workspace. Eventi del ciclo di vita ricevere notifiche sui problemi e sullo stato dell'abbonamento in modo da per non perdere gli eventi di abbonamento. Per impostazione predefinita, il tuo abbonamento riceve gli eventi del ciclo di vita. Per maggiori dettagli, consulta Eventi del ciclo di vita degli abbonamenti a Google Workspace.
- Abbonamento a Google Workspace
Un'entità denominata che monitora una risorsa da un account Google Workspace un'applicazione. Una sottoscrizione è rappresentata da un
Subscription
risorsa. Un abbonamento viene definito dalle seguenti informazioni:- Risorsa di destinazione
- La risorsa Google Workspace che vuoi monitorare.
Questa risorsa è rappresentata nel campo
targetResource
della abbonamento a Google Workspace. Ogni abbonamento può eseguire e monitorare una risorsa. Per vedere quali risorse Google Workspace supporta l'API Google Workspace Events, vedi Eventi di Google Workspace supportati. - Tipi di evento
- I tipi di modifiche per cui vuoi ricevere notifiche la risorsa di destinazione. Ad esempio, se hai sottoscritto un abbonamento a spazio di Google Chat, puoi scegliere se ricevere eventi su lo spazio e le relative risorse figlio, come le iscrizioni e i messaggi.
- Endpoint di notifica
- L'endpoint in cui L'abbonamento a Google Workspace riceve eventi. La L'API Google Workspace Events supporta gli argomenti Google Cloud Pub/Sub come un endpoint di notifica. Per saperne di più sull'uso di Google Cloud Pub/Sub, vedi il 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 a cui la tua app può ricevere eventi dipendono dalla risorsa di destinazione di l'abbonamento. La tabella seguente mostra gli eventi supportati per ogni una possibile risorsa target.
Risorsa di destinazione | Eventi supportati |
---|---|
Spazi di Google Chat |
|
Utenti di Google Chat |
|
Spazi per le riunioni di Google Meet |
|
Utenti di Google Meet |
|
Per saperne di più, consulta le seguenti guide:
Struttura degli eventi di Google Workspace
Gli eventi Google Workspace seguono CloudEvents specifiche, che è un metodo standard di settore per descrivere i dati sugli eventi. Google Workspace contengono quanto segue:
- Attributi del CloudEvent.
- Dati sulla risorsa Google Workspace che è cambiata per effetto di l'evento
La seguente sezione spiega la struttura degli attributi e dei dati per Eventi di Google Workspace.
Attributi CloudEvent
Gli eventi di Google Workspace contengono quanto segue: Attributi CloudEvents:
Attributo | Descrizione | Esempio |
---|---|---|
|
Il tipo di dati trasmessi nell'evento. |
|
|
Identificatore per l'evento CloudEvent. |
|
|
L'origine dell'evento. Per gli eventi di Google Workspace, si tratta del nome completo della risorsa della sottoscrizione. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
La versione della specifica CloudEvents utilizzata per questo evento. |
|
|
La risorsa Google Workspace in cui si è verificato l'evento. |
|
|
Il timestamp in cui si è verificato l'evento, nel formato RFC 3339. |
|
|
Il tipo di evento di Google Workspace. |
|
Dati sugli eventi
I dati sugli eventi sono un payload che rappresenta una modifica al target del tuo abbonamento e quella secondaria, incluse le risorse figlio della risorsa di destinazione. Nel tuo abbonamento, puoi specificare se vuoi che il payload includa i dati su la risorsa modificata o solo il nome della risorsa modificata.
Ad esempio, se hai un'iscrizione a uno spazio di Chat,
può ricevere eventi relativi a nuovi messaggi nello spazio. Per eventi su
nuovi messaggi, i dati degli eventi contengono un payload
spaces.message
risorsa creata.
Quando crei una sottoscrizione, puoi specificare la quantità di dati delle risorse inclusi negli eventi ricevuti dall'app:
- Includi dati risorsa: contiene alcuni o tutti i campi relativi alle modifiche apportate risorsa. Se scegli di includere i dati delle risorse, la sottoscrizione la durata è limitata a un massimo di 4 ore o 24 ore se utilizzi a livello di dominio delega.
- Escludi dati risorsa: contiene solo il nome della risorsa modificata risorsa. La durata dell'abbonamento è fino a 7 giorni. Per avere informazioni dettagliate su all'evento, puoi eseguire una query sulla risorsa utilizzando il relativo nome.
Queste opzioni per i dati sugli eventi sono rappresentate nel payloadOptions
campo della tua sottoscrizione.
Eventi come messaggi Google Cloud Pub/Sub
Gli abbonamenti all'API Google Workspace Events utilizzano Google Cloud Pub/Sub argomenti come endpoint di notifica che riceve Google Workspace eventi. Gli eventi sono codificati come messaggi Google Cloud Pub/Sub. La tua app possono elaborare il messaggio Google Cloud Pub/Sub per agire o rispondere l'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 nella spazio.data
: i dati sugli eventi con i dettagli sull'aggiornamento Risorsaspaces.message
, formattata come stringa con codifica Base64.messageId
: l'identificatore del messaggio Google Cloud Pub/Sub.
Scopri di più su come gli eventi Cloud vengono specificati in Google Cloud Pub/Sub. vedi Associazione di protocolli Google Cloud Pub/Sub per CloudEvents.