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 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.

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

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 informarti sui problemi e sullo stato dell'abbonamento in modo che tu possa 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	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 un membro dello spazio tramite Google Workspace o Google Account.
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 può essere 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 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
`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 di Google Workspace, si tratta del nome completo della risorsa della sottoscrizione.	`//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 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 Risorsa spaces.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.

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