Collegare un'app di chat ad altri servizi e strumenti

Questa pagina descrive come connettere un'app Google Chat a un servizio o a uno strumento al di fuori di Google Chat. Sebbene le app di chat siano potenti di per sé, spesso funzionano in combinazione con altri sistemi e richiedono applicazioni complementari per collegare account, autorizzare l'accesso ai dati, visualizzare dati aggiuntivi o configurare le preferenze utente.

Per autenticare gli utenti con un servizio di terze parti o un flusso OAuth, la tua app di chat esegue i seguenti passaggi:

  1. Rilevare quando è richiesta l'autorizzazione o la configurazione.
  2. Restituisci una scheda di autorizzazione di base che chiede all'utente di accedere o configurare il servizio.
  3. Reindirizza all'URI di completamento in modo che Google Chat riprovi automaticamente l'interazione originale dopo che l'utente ha completato l'autorizzazione.

Architettura di autenticazione delle app Google Chat con un servizio di terze parti.

Prerequisiti

HTTP

Un'app Google Chat che riceve e risponde alle interazioni degli utenti. Per crearne uno, completa la guida rapida HTTP.

Apps Script

Un'app Google Chat che riceve e risponde alle interazioni degli utenti. Per crearne uno, completa la guida rapida di Apps Script.

Rilevare che è necessaria l'autorizzazione

Quando interagiscono con l'app Chat, gli utenti potrebbero non essere autorizzati ad accedere a una risorsa protetta per vari motivi, ad esempio:

  • Non è ancora stato generato un token di accesso per connettersi al servizio di terze parti o è scaduto.
  • Il token di accesso non copre la risorsa richiesta.
  • Il token di accesso non copre gli ambiti richiesti della richiesta.

La tua app di chat deve rilevare questi casi in modo che gli utenti possano accedere e autorizzare l'accesso al tuo servizio.

Se stai sviluppando in Apps Script, puoi utilizzare la libreria OAuth2 per Google Apps Script (o la versione OAuth1), in cui la funzione hasAccess verifica se l'utente ha autorizzato l'accesso a un servizio. In alternativa, quando utilizzi le richieste UrlFetchApp.fetch, puoi impostare il parametro muteHttpExceptions su true per esaminare il codice di risposta e i contenuti nell'oggetto HttpResponse restituito.

Richiedere agli utenti una scheda di autorizzazione di base

Quando l'app di chat rileva che è necessaria l'autorizzazione o la configurazione, restituisci una risposta AuthorizationError per mostrare all'utente una scheda di autorizzazione di base privata.

La seguente immagine mostra un esempio della scheda di autorizzazione di base di Google:

Prompt di autorizzazione di base per l'account di esempio.
Figura 1: richiesta di autorizzazione di base per l'account di esempio. Il prompt indica che l'app Chat vorrebbe mostrare ulteriori informazioni, ma necessita dell'approvazione dell'utente per accedere all'account.

Per richiedere agli utenti una scheda di autorizzazione di base, restituisci un oggetto AuthorizationError:

HTTP

Restituisci la seguente risposta JSON:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Sostituisci quanto segue:

  • AUTHORIZATION_URL: l'URL HTTPS dell'app web che gestisce l'autenticazione, l'autorizzazione o la configurazione.
  • RESOURCE_DISPLAY_NAME: il nome visualizzato per la risorsa o il servizio protetto. Questo nome viene visualizzato all'utente nel prompt di autorizzazione. Ad esempio, se il tuo RESOURCE_DISPLAY_NAME è Example Account, il prompt indica che l'app ha bisogno dell'approvazione per accedere al tuo Example Account.

Completa la richiesta di configurazione

In Chat, l'utente può completare la procedura di autorizzazione e Chat ritenta automaticamente l'interazione originale senza un aggiornamento manuale. Chat supporta il nuovo tentativo automatico se il trigger è Messaggio, Aggiunta allo spazio o Comando app.

Per questi trigger, la tua app Chat riceve un URI di reindirizzamento di completamento (configCompleteRedirectUri / completeRedirectUri) nel payload dell'evento:

  • Messaggio: chat.messagePayload.configCompleteRedirectUri
  • Aggiunto allo spazio: chat.addedToSpacePayload.configCompleteRedirectUri
  • Comando app: chat.appCommandPayload.configCompleteRedirectUri

Devi codificare questo URI di reindirizzamento nel tuo <var>AUTHORIZATION_URL</var> e reindirizzare il browser dell'utente dopo il completamento del flusso di autorizzazione. Il reindirizzamento a questo URL indica a Google Chat che la richiesta di autorizzazione o configurazione è stata soddisfatta.

Quando un utente viene reindirizzato correttamente all'URI di reindirizzamento al completamento fornito nel payload dell'evento originale, Google Chat esegue i seguenti passaggi:

  1. Cancella la richiesta di autorizzazione privata visualizzata dall'utente che ha avviato l'operazione.
  2. Converte il messaggio originale in pubblico, rendendolo visibile agli altri membri dello spazio.
  3. Invia di nuovo l'oggetto evento originale alla tua app di chat.

Se non reindirizzi all'URI di reindirizzamento del completamento, l'utente può comunque completare il flusso di autorizzazione, ma Google Chat non ritenta automaticamente l'esecuzione precedente e l'utente deve richiamare manualmente la tua app Chat.

La visita di un URI di reindirizzamento al completamento influisce solo su una singola interazione utente. Se un utente ha inviato più messaggi all'app di chat e ha ricevuto più richieste, il completamento della procedura di autenticazione e configurazione per una sola richiesta riprova solo l'interazione specifica.

Autenticare l'utente di Chat al di fuori di Chat

Quando colleghi un URL esterno a Chat (ad esempio un callback web OAuth), spesso devi correlare la sessione web esterna all'identità dell'utente in Chat. Ti consigliamo di proteggere l'app web di destinazione con Google Sign-In.

Utilizza il token ID emesso durante l'accesso per ottenere l'ID utente. L'attestazione sub contiene l'ID Google univoco dell'utente e può essere correlata al nome della risorsa utente (chat.user.name) di Google Chat.

Per correlare l'attestazione sub con un nome risorsa users/{user} di Google Chat, anteponi il valore dell'attestazione sub con users/. Ad esempio, un valore della rivendicazione sub pari a 123 corrisponde a users/123 negli oggetti evento inviati alla tua app Chat.

Esempi di codice

I seguenti esempi di codice mostrano come un'app Chat può richiedere credenziali OAuth2 offline utilizzando una scheda di autorizzazione di base, memorizzarle in un database, reindirizzare all'URI di completamento ed effettuare chiamate API con autenticazione utente:

App di chat che non sono componenti aggiuntivi: connetti un'app di chat ad altri servizi e strumenti

Se gestisci un'app di Chat che non è un componente aggiuntivo di Google Workspace, la tua app di Chat richiede la configurazione utilizzando un actionResponse di tipo REQUEST_CONFIG e legge configCompleteRedirectUrl dall'oggetto Event di primo livello.

Per eseguire l'upgrade di un'app di Chat che non è un componente aggiuntivo al framework dei componenti aggiuntivi di Google Workspace, consulta Convertire un'app di Google Chat in un componente aggiuntivo di Google Workspace.

Richiedere la configurazione a un utente in un'app di chat che non è un componente aggiuntivo

In un'app di chat che non è un componente aggiuntivo, restituisci un URL di configurazione all'utente nel seguente formato:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

In questo modo, Google Chat presenta all'utente un prompt privato, in cui CONFIGURATION_URL è un link che l'utente può visitare per ulteriori autenticazioni, autorizzazioni o configurazioni. Una risposta REQUEST_CONFIG è mutualmente esclusiva con un normale messaggio di risposta; qualsiasi testo, scheda o altro attributo viene ignorato.

Completa la richiesta di configurazione in un'app di chat che non è un componente aggiuntivo

Ogni interazione MESSAGE, ADDED_TO_SPACE e APP_COMMAND Event che riceve un'app di chat che non è un componente aggiuntivo include il campo di primo livello configCompleteRedirectUrl. Codifica questo URL nell'URL di configurazione e reindirizza l'utente al termine dell'operazione in modo che Google Chat cancelli il prompt, converta il messaggio originale in pubblico e invii nuovamente l'evento di interazione originale alla tua app Chat.

Per esempi di implementazione, consulta l'esempio di app di connettività Node.js e l'esempio di app di autenticazione Python MyProfile su GitHub.