Questa guida spiega come utilizzare OAuth 2.0 con le credenziali Google degli utenti per accedere all'API Chat. Innanzitutto, illustra come creare le credenziali Client-ID OAuth 2.0. Quindi, dimostra come scrivere uno script che utilizza le credenziali per autenticarsi con l'API Chat e aggiungere l'app Chat a uno spazio di Chat.
L'autenticazione e l'autorizzazione con credenziali utente consentono alle app di Chat di accedere ai dati degli utenti ed eseguire operazioni per conto dell'utente autenticato. Ad esempio, dopo l'autenticazione e l'autorizzazione delle credenziali utente, le app di chat possono:
- Creare spazi di Chat.
- Aggiungere utenti agli spazi di Chat e alle conversazioni di gruppo.
- Utilizza i dati utente in altre API Workspace:
- Creare eventi in Google Calendar.
- Voci di log in un foglio Google.
- Inviare un'email con Gmail.
Quando un'app esegue un'azione con autenticazione degli utenti (ad esempio, la creazione di uno spazio), Google Chat potrebbe mostrare un messaggio di attribuzione che indica il nome dell'app che ha eseguito l'azione per conto dell'utente che l'ha autorizzata.
Se la tua app di chat non accede ai dati utente o non esegue azioni per conto di un utente, valuta la possibilità di autenticarti come app.
Per saperne di più su quando le app di chat richiedono l'autenticazione e sul tipo di autenticazione da utilizzare, vedi Tipi di autenticazione obbligatoria nella panoramica dell'autorizzazione e dell'autenticazione dell'API Chat.
Prerequisiti
Per eseguire l'esempio di questa guida, sono necessari i seguenti prerequisiti:
Python
- Python 3.6 o versioni successive
- Strumento di gestione dei pacchetti pip
- Un account Google Workspace con accesso a Google Chat.
- Un progetto Google Cloud con l'API Chat abilitata e configurata. Per creare un progetto e abilitare un'API, consulta Creare un progetto e abilitare l'API.
- Un'app di Chat configurata nella pagina di configurazione dell'API Chat nella console Google Cloud. Per creare e configurare un'app di chat, vedi Creare un'app di Google Chat con Cloud Functions.
Passaggio 1: installa la libreria client di Google
Se non hai ancora installato le librerie client di Google per la tua lingua, esegui questo comando nell'interfaccia a riga di comando:
Python
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
Puoi utilizzare qualsiasi linguaggio supportato dalle nostre librerie client.
Passaggio 2: configura la schermata per il consenso OAuth, specifica gli ambiti e registra l'app
Quando utilizzi OAuth 2.0 per l'autorizzazione, Google mostra all'utente una schermata per il consenso che include un riepilogo del progetto, i relativi criteri e gli ambiti di autorizzazione richiesti. La configurazione della schermata per il consenso OAuth dell'app definisce i contenuti che Google deve mostrare agli utenti e ai revisori di app. Inoltre, registra l'app in modo che tu possa pubblicarla in un secondo momento.
Tutte le app che utilizzano OAuth 2.0 richiedono una configurazione della schermata di consenso, ma devi elencare solo gli ambiti per le app utilizzate da persone esterne all'organizzazione Google Workspace.
Nella console Google Cloud, vai a Menu > API e servizi > Schermata consenso OAuth.
Seleziona il tipo di utente per la tua app, poi fai clic su Crea.
Compila il modulo di registrazione dell'app, quindi fai clic su Salva e continua.
Fai clic su Aggiungi o rimuovi ambiti. Aggiungi e verifica gli ambiti di autorizzazione richiesti dalla tua app, fai clic su Aggiorna e poi su Salva e continua.
Esamina il riepilogo della registrazione dell'app. Fai clic su Modifica per apportare modifiche o fai clic su Torna alla dashboard.
Passaggio 3: crea le credenziali ID client OAuth nella console Google Cloud
Per eseguire l'autenticazione come utente finale e accedere ai dati utente nella tua app, devi creare uno o più ID client OAuth 2.0. L'ID client viene utilizzato per identificare una singola app nei server OAuth di Google. Se la tua app viene eseguita su più piattaforme, come Android, iOS e Web, devi creare un ID client separato per ogni piattaforma.
Creare credenziali ID client OAuth
Scegli il tipo di applicazione di seguito per istruzioni specifiche su come creare un ID client OAuth:
Applicazione web
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > ID client OAuth.
- Fai clic su Tipo di applicazione > Applicazione web.
- Nel campo Nome, digita un nome per la credenziale. Questo nome viene visualizzato solo nella console Google Cloud.
- Aggiungi URI autorizzati relativi alla tua app:
- App lato client (JavaScript): in Origini JavaScript autorizzate, fai clic su Aggiungi URI. Quindi, inserisci un URI da utilizzare per le richieste del browser. Identifica i domini da cui la tua applicazione può inviare richieste API al server OAuth 2.0.
- App lato server (Java, Python e altri ancora): in URI di reindirizzamento autorizzati, fai clic su Aggiungi URI. Quindi, inserisci un URI endpoint a cui il server OAuth 2.0 può inviare le risposte.
- Fai clic su Crea. Viene visualizzata la schermata Crea client OAuth, che mostra il nuovo ID client e il client secret.
Prendi nota dell'ID client. I client secret non vengono utilizzati per le applicazioni web.
- Fai clic su OK. Le credenziali appena create vengono visualizzate in ID client OAuth 2.0.
- (Facoltativo) Se stai creando credenziali come prerequisito per una guida rapida di JavaScript, devi anche generare una chiave API.
Android
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > ID client OAuth.
- Fai clic su Tipo di applicazione > Android.
- Digita un nome per la credenziale nel campo "Name". Questo nome viene visualizzato solo nella console Google Cloud.
- Nel campo "Nome pacchetto", inserisci il nome del file
AndroidManifest.xml. - Nel campo "Impronta digitale certificato SHA-1", inserisci la tua impronta digitale del certificato SHA-1.
- Fai clic su Crea. Viene visualizzata la schermata Crea client OAuth, che mostra il nuovo ID client.
- Fai clic su OK. Le credenziali appena create vengono visualizzate nella sezione "ID client OAuth 2.0".
iOS
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > ID client OAuth.
- Fai clic su Tipo di applicazione > iOS.
- Digita un nome per la credenziale nel campo "Name". Questo nome viene visualizzato solo nella console Google Cloud.
- Nel campo "ID bundle", inserisci l'identificatore pacchetto elencato nel file
Info.plistdell'app. - (Facoltativo) Se l'app viene visualizzata nell'App Store di Apple, inserisci l'ID App Store.
- (Facoltativo) Nel campo "ID team", inserisci la stringa univoca di 10 caratteri generata da Apple e assegnata al tuo team.
- Fai clic su Crea. Viene visualizzata la schermata Crea client OAuth, che mostra il nuovo ID client e il client secret.
- Fai clic su OK. Le credenziali appena create vengono visualizzate nella sezione "ID client OAuth 2.0".
App Chrome
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > ID client OAuth.
- Fai clic su Tipo di applicazione > App di Chrome.
- Digita un nome per la credenziale nel campo "Name". Questo nome viene visualizzato solo nella console Google Cloud.
- Nel campo "ID applicazione", inserisci la stringa univoca di 32 caratteri della tua app. Puoi trovare questo valore dell'ID nell'URL del Chrome Web Store della tua app e nella Dashboard per sviluppatori del Chrome Web Store.
- Fai clic su Crea. Viene visualizzata la schermata Crea client OAuth, che mostra il nuovo ID client e il client secret.
- Fai clic su OK. Le credenziali appena create vengono visualizzate nella sezione "ID client OAuth 2.0".
Applicazione desktop
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > ID client OAuth.
- Fai clic su Tipo di applicazione > App desktop.
- Nel campo Nome, digita un nome per la credenziale. Questo nome viene visualizzato solo nella console Google Cloud.
- Fai clic su Crea. Viene visualizzata la schermata Crea client OAuth, che mostra il nuovo ID client e il client secret.
- Fai clic su OK. Le credenziali appena create vengono visualizzate in ID client OAuth 2.0.
TV e dispositivi di input limitati
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > ID client OAuth.
- Fai clic su Tipo di applicazione > TV e dispositivi di input limitati.
- Digita un nome per la credenziale nel campo "Name". Questo nome viene visualizzato solo nella console Google Cloud.
- Fai clic su Crea. Viene visualizzata la schermata Crea client OAuth, che mostra il nuovo ID client e il client secret.
- Fai clic su OK. Le credenziali appena create vengono visualizzate nella sezione "ID client OAuth 2.0".
Universal Windows Platform (UWP)
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > ID client OAuth.
- Fai clic su Tipo di applicazione > Universal Windows Platform (UWP).
- Digita un nome per la credenziale nel campo "Name". Questo nome viene visualizzato solo nella console Google Cloud.
- Nel campo "ID store", inserisci il valore univoco di 12 caratteri dell'ID Microsoft Store della tua app. Puoi trovare questo ID nell'URL del Microsoft Store della tua app e nel Centro partner.
- Fai clic su Crea. Viene visualizzata la schermata Crea client OAuth, che mostra il nuovo ID client e il client secret.
- Fai clic su OK. Le credenziali appena create vengono visualizzate nella sezione "ID client OAuth 2.0".
Scarica il file JSON del client secret
Il file client secret è una rappresentazione JSON delle credenziali dell'ID client OAuth a cui la tua app Chat può fare riferimento quando fornisce le credenziali.
Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
In ID client OAuth 2.0, fai clic sull'ID client che hai creato.
Fai clic su Scarica JSON.
Salva il file come
client_secrets.json.
Passaggio 4: crea una chiave API
Mentre l'autenticazione utente per l'API Chat è in anteprima per sviluppatori, il tuo codice deve indirizzare a una versione di anteprima per sviluppatori del documento di rilevamento dell'API Chat. Per autenticare l'accesso del progetto Google Cloud alla versione di anteprima dell'API dello sviluppatore, genera una chiave API nel progetto e passala come parte della chiamata API.
Per creare una chiave API:
- Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.
- Fai clic su Crea credenziali > Chiave API.
- Viene visualizzata la nuova chiave API.
- Fai clic su Copia per copiare la chiave API da utilizzare nel codice della tua app. La chiave API è disponibile anche nella sezione "Chiavi API" delle credenziali del progetto.
- Fai clic su Limita chiave per aggiornare le impostazioni avanzate e limitare l'utilizzo della chiave API. Per maggiori dettagli, consulta la sezione Applicazione delle restrizioni relative alle chiavi API.
Passaggio 5: scrivi uno script che chiami l'API Chat
Il codice seguente utilizza una libreria client per chiamare l'API Chat. L'API si autentica con l'API Chat utilizzando le credenziali dell'ID client OAuth, quindi aggiunge l'app Chat a uno spazio.
Salva il seguente codice in un file denominato chat_create_membership.py nella stessa directory contenente client_secrets.json:
Python
from __future__ import print_function
import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.memberships.app"]
def main():
'''
Authenticates with Chat API via user credentials,
then adds the Chat app to a Chat space.
'''
# Start with no credentials.
creds = None
# Check for the file token.json. If it exists, use it for authentication.
# The file token.json stores the user's access and refresh tokens, and is
# created automatically when the authorization flow completes for the first
# time.
if os.path.exists('token.json'):
creds = Credentials.from_authorized_user_file('token.json', SCOPES)
# If there are no valid credentials available, let the user log in.
if not creds or not creds.valid:
if creds and creds.expired and creds.refresh_token:
creds.refresh(Request())
else:
flow = InstalledAppFlow.from_client_secrets_file(
'client_secrets.json', SCOPES)
creds = flow.run_local_server(port=0)
# Save the credentials for the next run in a file
# named token.json.
with open('token.json', 'w') as token:
token.write(creds.to_json())
# Build a service endpoint for Chat API.
#
# While user authentication is in developer preview, append the
# following parameters that let the Python client see a
# developer preview version of the client library:
#
# discoveryServiceUrl—Points to a developer preview version of the Chat
# API discovery document.
#
# developerKey—An API key created inside the developer preview Google
# Cloud Project. This API key is used to authenticate the Cloud Project's
# access to a developer preview API.
key = 'API_KEY'
url = 'https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW'
service = build('chat', 'v1', discoveryServiceUrl=url, developerKey=key, credentials=creds)
# Set the Chat app as the entity that gets added to the space.
# 'app' is an alias for the Chat app running the script.
#
# To specify a user, set:
#
# member = {
# 'member': {
# 'name':'users/{user}',
# 'type':'HUMAN'
# }
# }
member = {
'member': {
'name':'users/app',
'type': 'BOT'
}
}
# Use the service endpoint to call Chat API.
result = service.spaces().members().create(
# Replace SPACE with a space name.
# Obtain the space name from the spaces resource of Chat API,
# or from a space's URL.
parent='spaces/SPACE',
body=member).execute()
# Prints details about the created membership.
print(result)
if __name__ == '__main__':
main()
Passaggio 5: esegui lo script di esempio
Per eseguire l'esempio, dalla riga di comando vai alla directory che contiene chat_create_membership.py e client_secrets.json, quindi esegui il comando seguente:
Python
python3 chat_create_membership.py
Viene visualizzato un browser web che ti chiede di accedere al tuo Account Google:
Dopo aver eseguito l'accesso, viene visualizzata la schermata per il consenso OAuth che ti chiede di concedere l'autorizzazione all'app:
Dopo aver concesso l'autorizzazione, lo script chiama l'API Chat, che risponde aggiungendo l'app Chat a uno spazio di Chat. La console stampa i dettagli della chiamata API.
Risolvere i problemi dell'esempio
È previsto un oggetto JSON con una singola proprietà per un'applicazione "web" o "installata"
Quando esegui chat_create_membership.py, potresti ricevere un errore che indica che:
Expected a JSON object with a single property for a "web" or "installed" application
Questo messaggio di errore indica che il file client_secrets.json che hai scaricato da Google Cloud Platform non inizia con la proprietà "web" o "installed". Dopo l'autenticazione con il file scaricato, se il codice non salva il token di accesso in un nuovo file come token.json, il token di accesso viene scritto in client_secrets.json, causando questo errore durante i successivi tentativi di autorizzazione.
Per risolvere il problema, scarica di nuovo il file secret del client dalla console Google Cloud e salva il nuovo file al posto del file attuale.
Passaggio successivo
Scopri cos'altro può fare l'API Chat consultando la documentazione di riferimento dell'API Chat.