Autenticare e autorizzare le app di Chat e le richieste dell'API Google Chat

Autenticazione e autorizzazione sono meccanismi utilizzati per verificare l'identità e l'accesso alle risorse. Questo documento illustra come l'autenticazione per le app Chat e le richieste dell'API Chat.

Panoramica della procedura

Il seguente diagramma mostra i passaggi generali di autenticazione e autorizzazione per Google Chat:

Passaggi generali per l'autenticazione e l'autorizzazione di Google Chat
Figura 1. Passaggi generali per l'autenticazione e l'autorizzazione di Google Chat.

  1. Configura un progetto Google Cloud, abilita l'API Chat e configura App di chat: durante lo sviluppo, crei un'app progetto Google Cloud. Nel progetto Google Cloud, abiliti l'API Chat, configurare l'app Chat e impostare l'autenticazione. Per ulteriori informazioni, vedi Sviluppa su Google Workspace e Creare un'app di chat.

  2. API Call Chat: quando l'app chiama l'API API Chat, invia le credenziali di autenticazione ai API Chat. Se l'app esegue l'autenticazione con un account di servizio, le credenziali vengono inviate parte del codice della tua app. Se la tua app richiede la chiamata all'API Chat utilizzando un'autenticazione utente che non è stata ancora concessa, richiede di eseguire l'accesso all'utente.

  3. Richiedi risorse. La tua app richiede l'accesso con ambiti specificato durante la configurazione dell'autenticazione.

  4. Chiedi il consenso:se la tua app viene autenticata come utente, Google mostra Una schermata per il consenso OAuth, in modo che l'utente possa decidere se concedere alla tua app l'accesso ai dati richiesti. L'autenticazione con un account di servizio richiede il consenso degli utenti.

  5. Invia una richiesta approvata per le risorse:se l'utente acconsente al ambiti di autorizzazione, l'app raggruppa le credenziali e i dati in una richiesta. La richiesta viene inviata al server di autorizzazione di Google per ottenere un token di accesso.

  6. Google restituisce un token di accesso. Il token di accesso contiene un elenco di gli ambiti concessi. Se l'elenco degli ambiti restituito è più restrittivo rispetto richiesti, l'app disattiva tutte le funzionalità limitate dal token.

  7. Accesso alle risorse richieste:la tua app utilizza il token di accesso di Google per richiamare l'API Chat e accedere alle risorse dell'API Chat.

  8. (Facoltativo) Richiedi un token di aggiornamento: se la tua app deve accedere allo API Google Chat oltre la durata di un singolo token di accesso, può ricevere token di aggiornamento. Per ulteriori informazioni, vedi Utilizzare OAuth 2.0 per accedere alle API di Google.

  9. Richiedere altre risorse: se l'app richiede un accesso maggiore, chiede all'utente di accedere. per concedere nuovi ambiti, generando una nuova richiesta per ottenere un token di accesso (passaggi 3-6).

Quando le app di chat richiedono l'autenticazione

Le app di chat possono inviare messaggi in risposta a un'interazione dell'utente oppure in modo asincrono. Possono anche completare attività per conto di un utente, ad esempio: creare uno spazio di Chat o recuperare un elenco di persone in Spazio di Chat.

Le app di chat non richiedono l'autenticazione per rispondere a un interazione dell'utente, a meno che l'app Chat non chiami L'API Chat o un'altra API di Google durante la configurazione durante l'elaborazione di una risposta.

Per inviare messaggi asincroni o eseguire attività per conto di un utente, Le app di chat effettuano richieste RESTful API Chat, che richiedono autenticazione e autorizzazione.

Le risposte alle interazioni degli utenti non richiedono l'autenticazione

Non è necessario eseguire l'autenticazione per le app di Google Chat come utente o App Chat per ricevere e rispondere in modo sincrono eventi di interazione.

Le app Google Chat ricevono eventi di interazione ogni volta che un utente interagisce o richiama un'app di Chat, include quanto segue:

  • Un utente invia un messaggio a un'app di Chat.
  • Un utente @menziona un'app di Chat.
  • Un utente richiama una delle comandi slash.

Il seguente diagramma mostra una sequenza di richiesta-risposta tra un Utente Chat e app Chat:

Non è richiesta alcuna autorizzazione per gli eventi di interazione con l'app di Chat
Figura 2. Gli eventi di interazione con l'app di chat non richiedono l'autenticazione.

  1. L'utente invia un messaggio all'app Chat in Google Chat.
  2. Google Chat inoltra il messaggio all'app.
  3. L'app riceve il messaggio, lo elabora e restituisce una risposta a Google Chat.
  4. Google Chat mostra la risposta per l'utente o in uno spazio.

Questa sequenza si ripete per ogni interazione con l'app di chat .

I messaggi asincroni richiedono l'autenticazione

I messaggi asincroni si verificano quando un'app di Chat invia una richiesta alla API Chat, che richiede autenticazione e autorizzazione.

Chiamando l'API Chat, le app di Chat possono pubblicare messaggi a Google Chat o completare attività e accedere ai dati per conto di un utente. Per Ad esempio, dopo aver rilevato un'interruzione del server, un'app di Chat può chiamare il API Chat per:

  • Crea uno spazio di Chat dedicato all'analisi e alla risoluzione dei problemi o un'interruzione del servizio.
  • Aggiungi persone allo spazio di Chat.
  • Pubblica un messaggio nello spazio di Chat per fornire dettagli su o un'interruzione del servizio.

Il seguente diagramma mostra una sequenza di messaggi asincrona tra un App di Chat e uno spazio di Chat:

Autenticazione richiesta per i messaggi asincroni
Figura 3. I messaggi asincroni richiedono l'autenticazione.

  1. Un'app di Chat crea un messaggio chiamando il l'API Chat con spaces.messages.create metodo predefinito, e include le credenziali utente nella richiesta HTTP.
  2. Google Chat autentica l'app Chat con l'account di servizio o le credenziali utente.
  3. Google Chat esegue il rendering del messaggio dell'app in un messaggio di Chat specificato spazio.

Ambiti API Chat

Configura la schermata per il consenso OAuth e scegli gli ambiti per definire quali informazioni mostrare a utenti e revisori di app e registrare la tua app per poterla pubblicare in un secondo momento.

Per definire il livello di accesso concesso alla tua app, devi identificare e dichiarare gli ambiti di autorizzazione. Un ambito di autorizzazione è un URI OAuth 2.0 stringa che contiene il nome dell'app Google Workspace, il tipo di dati accessi e il livello di accesso.

Ambiti non sensibili

Codice ambito Descrizione
https://www.googleapis.com/auth/chat.bot

L'ambito chat.bot supporta solo gli account di servizio. Tu che non possono eseguire l'autenticazione con le credenziali utente o con delega a livello di dominio utilizzando questo ambito.

Consente alle app di Chat di visualizzare le chat e inviare messaggi. Dà accesso a tutte le funzionalità disponibili per le app di chat.

Ambiti sensibili

Codice ambito Descrizione
https://www.googleapis.com/auth/chat.spaces Creare conversazioni e spazi e visualizzare o modificare metadati (tra cui impostazioni della cronologia e di accesso) in Chat.
https://www.googleapis.com/auth/chat.spaces.create Creare nuove conversazioni in Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Visualizzare la chat e gli spazi in Chat.
https://www.googleapis.com/auth/chat.memberships Visualizzare, aggiungere, aggiornare e rimuovere membri dalle conversazioni in Chat.
https://www.googleapis.com/auth/chat.memberships.app Aggiungersi e rimuoversi dalle conversazioni in Google Chat.
https://www.googleapis.com/auth/chat.memberships.readonly Visualizzare i membri nelle conversazioni di Chat.
https://www.googleapis.com/auth/chat.messages.create Scrivi e invia messaggi in Chat.
https://www.googleapis.com/auth/chat.messages.reactions Visualizza, aggiungi ed elimina le reazioni ai messaggi in Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create Aggiungere reazioni a un messaggio in Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Visualizzare le reazioni a un messaggio in Chat.
https://www.googleapis.com/auth/chat.users.readstate Visualizzare e modificare data e ora dell'ultima lettura delle conversazioni di Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Visualizzare l'ora dell'ultima lettura delle conversazioni di Chat.
https://www.googleapis.com/auth/chat.admin.spaces.readonly Visualizzare la chat e gli spazi di proprietà del dominio dell'amministratore in Chat.
https://www.googleapis.com/auth/chat.admin.spaces Visualizzare o modificare la chat e gli spazi di proprietà del dominio dell'amministratore in Chat.
https://www.googleapis.com/auth/chat.admin.memberships.readonly Visualizzare i membri e i gestori nelle conversazioni di proprietà del dominio dell'amministratore in Chat.
https://www.googleapis.com/auth/chat.admin.memberships Visualizzare, aggiungere, aggiornare e rimuovere membri e gestori nelle conversazioni di proprietà del dominio dell'amministratore in Chat.

Ambiti con restrizioni

Codice ambito Descrizione
https://www.googleapis.com/auth/chat.delete Eliminare conversazioni e spazi e rimuovere l'accesso ai file associati in Chat.
https://www.googleapis.com/auth/chat.import Importare spazi, messaggi e iscrizioni in Chat. Per ulteriori informazioni, vedi Autorizzare le app di Chat a importare dati
https://www.googleapis.com/auth/chat.messages Visualizzare, scrivere, inviare, aggiornare ed eliminare messaggi, nonché aggiungere, visualizzare e Eliminare le reazioni ai messaggi.
https://www.googleapis.com/auth/chat.messages.readonly Visualizza messaggi e reazioni in Chat.
https://www.googleapis.com/auth/chat.admin.delete Eliminare le conversazioni e gli spazi di proprietà del dominio dell'amministratore e rimuovere l'accesso ai file associati in Chat.

Gli ambiti nelle tabelle precedenti indicano la loro sensibilità, in base alla seguenti definizioni:

Se la tua app richiede l'accesso a qualsiasi altra API di Google, puoi aggiungere questi ambiti . Per ulteriori informazioni sugli ambiti delle API di Google, consulta Utilizzo di OAuth 2.0 per Accedi alle API di Google.

Per saperne di più sugli ambiti per le API Google Workspace, consulta Configura la schermata per il consenso OAuth e scegli gli ambiti.

Tipi di autenticazione richiesta

Esistono due modi in cui le app di chat possono autenticarsi e autorizzare con l'API Chat: credenziali utente o account di servizio.

Con l'autorizzazione delle credenziali utente, un'app di Chat può accedere ai dati degli utenti e completare azioni per conto di un utente. Gli ambiti OAuth specificano i dati e le azioni autorizzati.

Con l'autorizzazione app, un'app di Chat accede l'API come app utilizzando le credenziali dell'account di servizio. Autorizzazione app sempre utilizza l'ambito di autorizzazione chat.bot.

Quando decidi quale tipo di credenziale usare per una particolare richiesta API, ricorda che alcuni metodi dell'API supportano solo un particolare tipo la credenziale. Se un metodo API supporta entrambe le credenziali, il tipo di credenziale usato nella chiamata influisce sul risultato che viene restituito:

  • Con l'autorizzazione dell'app, i metodi restituiscono solo le risorse che l'app può l'accesso.
  • Con l'autorizzazione dell'utente, i metodi restituiscono solo le risorse che l'utente a cui possono accedere nell'interfaccia utente di Chat.

Ad esempio, una chiamata al metodo ListSpaces con l'autorizzazione app restituisce il token degli spazi di cui l'app è membro. Chiamata al ListSpaces con l'utente autorizzazione restituisce l'elenco degli spazi di cui l'utente è membro. Nella pratica, la tua app potrebbe utilizzare entrambi i tipi di autorizzazione quando chiami l'API Chat, a seconda della funzionalità che vuoi usare.

Per le chiamate API di Chat asincrone

La tabella seguente elenca i metodi dell'API Chat e i relativi metodi supportati ambiti di autorizzazione:

Metodo Autenticazione utente supportata Autenticazione delle app supportata Ambiti di autorizzazione supportati
Spazi  
Creare uno spazio Con l'autenticazione utente:
    .
  • chat.spaces.create
  • chat.spaces
  • chat.import
Configurare uno spazio Con l'autenticazione utente:
    .
  • chat.spaces.create
  • chat.spaces
Ottieni uno spazio Con l'autenticazione utente:
    .
  • chat.spaces.readonly
  • chat.spaces
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.spaces.readonly
Elenco spazi Con l'autenticazione utente:
    .
  • chat.spaces.readonly
  • chat.spaces
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
Cerca spazi Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.spaces.readonly
Aggiornare uno spazio Con l'autenticazione utente:
    .
  • chat.spaces
  • chat.import
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.spaces
Eliminare uno spazio Con l'autenticazione utente:
    .
  • chat.delete
  • chat.import
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.delete
Completare il processo di importazione di uno spazio Con l'autenticazione utente:
    .
  • chat.import
Trovare un messaggio diretto Con l'autenticazione utente:
    .
  • chat.spaces.readonly
  • chat.spaces
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
Membri  
Creare un membro Con l'autenticazione utente:
    .
  • chat.memberships
  • chat.memberships.app
  • chat.import
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.memberships
Abbonarsi Con l'autenticazione utente:
    .
  • chat.memberships.readonly
  • chat.memberships
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.memberships.readonly
Membri dell'elenco Con l'autenticazione utente:
    .
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.memberships.readonly
Eliminare un membro Con l'autenticazione utente:
    .
  • chat.memberships
  • chat.memberships.app
  • chat.import
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.memberships
Aggiornare un membro Con l'autenticazione utente:
    .
  • chat.memberships
  • chat.import
di Gemini Advanced. Con l'autenticazione utente mediante privilegi amministrativi:
    .
  • chat.admin.memberships
Messaggi  
Crea un messaggio Con l'autenticazione utente:
    .
  • chat.messages.create
  • chat.messages
  • chat.import
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
Ricevi un messaggio Con l'autenticazione utente:
    .
  • chat.messages.readonly
  • chat.messages
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
Elenca messaggi Con l'autenticazione utente:
    .
  • chat.messages.readonly
  • chat.messages
  • chat.import
Aggiornare un messaggio Con l'autenticazione utente:
    .
  • chat.messages
  • chat.import
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
Eliminare un messaggio Con l'autenticazione utente:
    .
  • chat.messages
  • chat.import
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
Reazioni  
Creare una reazione Con l'autenticazione utente:
    .
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Elencare le reazioni Con l'autenticazione utente:
    .
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Eliminare una reazione Con l'autenticazione utente:
    .
  • chat.messages.reactions
  • chat.messages
  • chat.import
Contenuti multimediali e allegati  
Caricare contenuti multimediali come file allegati Con l'autenticazione utente:
    .
  • chat.messages.create
  • chat.messages
  • chat.import
Scaricare contenuti multimediali Con l'autenticazione utente:
    .
  • chat.messages.readonly
  • chat.messages
di Gemini Advanced. Con l'autenticazione app:
  • chat.bot
Ricevere un allegato del messaggio Con l'autenticazione delle app:
    .
  • chat.bot
Stati di lettura dell'utente
Ottenere lo stato di lettura dello spazio di un utente Con l'autenticazione utente:
    .
  • chat.users.readstate
  • chat.users.readstate.readonly
Aggiornare lo stato di lettura dello spazio di un utente Con l'autenticazione utente:
    .
  • chat.users.readstate
Ottenere lo stato di lettura dei thread di un utente Con l'autenticazione utente:
    .
  • chat.users.readstate
  • chat.users.readstate.readonly
Eventi dello spazio
Ricevere eventi nello spazio . Con l'autenticazione utente, devi utilizzare un ambito basato . tipo di evento:
  • Per gli eventi relativi ai messaggi:
    • chat.messages
    • chat.messages.readonly
  • Per gli eventi relativi alle reazioni:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Per gli eventi relativi agli abbonamenti:
    • chat.memberships
    • chat.memberships.readonly
  • Per gli eventi relativi allo spazio:
    • chat.spaces
    • chat.spaces.readonly
Elenca eventi dello spazio . Con l'autenticazione utente, devi utilizzare un ambito per ogni . incluso nella richiesta:
  • Per gli eventi relativi ai messaggi:
    • chat.messages
    • chat.messages.readonly
  • Per gli eventi relativi alle reazioni:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Per gli eventi relativi agli abbonamenti:
    • chat.memberships
    • chat.memberships.readonly
  • Per gli eventi relativi allo spazio:
    • chat.spaces
    • chat.spaces.readonly

Per gli eventi di interazione con l'app di Chat

La tabella seguente elenca i modi più comuni con cui gli utenti interagiscono con le app di chat e indica se l'autenticazione è richiesta o supportata:

Scenario Nessuna autenticazione richiesta Autenticazione utente supportata Autenticazione delle app supportata
Ricevi messaggi da:
Eventi di interazione con l'app di Chat
Callback di Apps Script
Google Cloud Pub/Sub
Rispondi ai messaggi:
In modo sincrono, utilizzando un evento di interazione con l'app Chat.
In modo sincrono, utilizzando un valore restituito di callback di Apps Script
Inviare nuovi messaggi:
Con webhook in arrivo