1. Utilizzo delle API Google Workspace
Questo codelab ti introduce all'utilizzo delle API RESTful basate su HTTP di Google Workspace (precedentemente G Suite). L'esempio verrà eseguito in Python per brevità e disponibilità, ma puoi anche scegliere di utilizzare il tuo linguaggio di sviluppo preferito. Verranno trattati argomenti introduttivi come l'utilizzo della console per gli sviluppatori per creare/gestire progetti, l'ottenimento delle credenziali di autorizzazione e l'installazione delle librerie client API. Una volta sbrigate le formalità, scriverai un'app per visualizzare i primi 100 file e cartelle in Google Drive utilizzando la relativa API.
Obiettivi didattici
- Crea un progetto utilizzando Google/Cloud Developers Console
- Ottenere e utilizzare le credenziali dell'applicazione OAuth2 nella tua app
- Scopri di più sull'utilizzo delle librerie client delle API di Google
- Scrivere applicazioni utilizzando le API Google e Google Workspace
- Ottenere informazioni su file e cartelle con l'API Google Drive
Che cosa ti serve
- Accesso a internet e a un browser web
- Un Account Google (gli account Google Workspace potrebbero richiedere l'approvazione dell'amministratore)
- Familiarità con sistemi conformi a POSIX come Linux e Mac OS X
- Possibilità di creare file di origine con un editor di codice o comandi shell.
- Competenze di base in Python (2 o 3), ma puoi utilizzare qualsiasi linguaggio supportato
- Alcuni file e/o cartelle in Google Drive
2. Sondaggio
Come utilizzerai questo tutorial di codelab?
Come valuti la tua esperienza con le API e gli strumenti per sviluppatori di Google Workspace?
3. Panoramica
In questo codelab imparerai a:
- Scarica la libreria client delle API di Google per Python
- Crea un nuovo progetto in Google/Cloud Developers Console
- Ottieni le credenziali necessarie per la tua app
- Utilizza queste credenziali per accedere all'API Google Drive
Se preferisci non utilizzare Python, puoi implementare il codelab nel tuo strumento di sviluppo preferito (le librerie client dei linguaggi supportati sono disponibili qui) e fare riferimento agli esempi Python come pseudocodice (eseguibile).
4. Conferma l'ambiente Python
Questo codelab richiede l'utilizzo del linguaggio Python (anche se le librerie client delle API di Google supportano molti linguaggi, quindi sentiti libero di creare qualcosa di equivalente nel tuo strumento di sviluppo preferito e di utilizzare Python come pseudocodice). In particolare, questo codelab supporta Python 2 e 3, ma ti consigliamo di passare alla versione 3.x il prima possibile.
Cloud Shell è una comodità disponibile per gli utenti direttamente dalla console Cloud e non richiede un ambiente di sviluppo locale, quindi questo tutorial può essere completato interamente nel cloud con un browser web. Cloud Shell è particolarmente utile se stai sviluppando o prevedi di continuare a sviluppare con le API e i prodotti GCP. Più nello specifico per questo codelab, Cloud Shell ha già preinstallato entrambe le versioni di Python.
Cloud Shell ha anche IPython installato, un interprete Python interattivo di livello superiore che consigliamo, soprattutto se fai parte della community di data science o machine learning. In caso affermativo, IPython è l'interprete predefinito per i notebook Jupyter e per Colab, i notebook Jupyter ospitati da Google Research.
IPython preferisce prima un interprete Python 3, ma torna a Python 2 se la versione 3.x non è disponibile. È possibile accedere a IPython da Cloud Shell, ma può anche essere installato in un ambiente di sviluppo locale. Esci con ^D (Ctrl+D) e accetta l'offerta di uscire. L'output di esempio dell'avvio di ipython sarà simile al seguente:
$ ipython Python 3.7.3 (default, Mar 4 2020, 23:11:43) Type 'copyright', 'credits' or 'license' for more information IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help. In [1]:
Se IPython non è la tua preferenza, l'utilizzo di un interprete interattivo Python standard (Cloud Shell o il tuo ambiente di sviluppo locale) è perfettamente accettabile (esci anche con ^D):
$ python Python 2.7.13 (default, Sep 26 2018, 18:42:22) [GCC 6.3.0 20170516] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> $ python3 Python 3.7.3 (default, Mar 10 2020, 02:33:39) [GCC 6.3.0 20170516] on linux Type "help", "copyright", "credits" or "license" for more information. >>>
Il codelab presuppone inoltre che tu disponga dello strumento di installazione pip (gestore pacchetti e risolutore di dipendenze Python). È incluso nelle versioni 2.7.9+ o 3.4+. Se hai una versione precedente di Python, consulta questa guida per le istruzioni di installazione. A seconda delle autorizzazioni, potresti dover disporre dell'accesso sudo o di superutente, ma in genere non è così. Puoi anche utilizzare esplicitamente pip2 o pip3 per eseguire pip per versioni specifiche di Python.
Il resto del codelab presuppone che tu stia utilizzando Python 3. Se le istruzioni per Python 2 differiscono in modo significativo da quelle per la versione 3.x, verranno fornite istruzioni specifiche.
*Crea e utilizza ambienti virtuali
Questa sezione è facoltativa e necessaria solo per chi deve utilizzare un ambiente virtuale per questo codelab (come indicato nella barra laterale di avviso sopra). Se sul computer è installato solo Python 3, puoi semplicemente eseguire questo comando per creare un virtualenv chiamato my_env (puoi scegliere un altro nome, se vuoi):
virtualenv my_env
Tuttavia, se hai sia Python 2 che 3 sul computer, ti consigliamo di installare un virtualenv Python 3, che puoi fare con -p flag in questo modo:
virtualenv -p python3 my_env
Inserisci il virtualenv appena creato "attivandolo" in questo modo:
source my_env/bin/activate
Conferma di trovarti nell'ambiente osservando che il prompt della shell ora è preceduto dal nome dell'ambiente, ad esempio
(my_env) $
Ora dovresti essere in grado di pip install tutti i pacchetti richiesti, eseguire codice all'interno di questo ambiente e così via. Un altro vantaggio è che, se fai un pasticcio, ti trovi in una situazione in cui l'installazione di Python è danneggiata e così via, puoi eliminare l'intero ambiente senza influire sul resto del sistema.
5. Installa la libreria client delle API di Google per Python
Questo codelab richiede l'utilizzo della libreria client delle API di Google per Python, quindi si tratta di un semplice processo di installazione oppure potresti non dover fare nulla.
In precedenza ti abbiamo consigliato di utilizzare Cloud Shell per comodità. Puoi completare l'intero tutorial da un browser web nel cloud. Un altro motivo per utilizzare Cloud Shell è che molti strumenti di sviluppo e librerie necessari sono già preinstallati.
*Installa librerie client
(facoltativo) Questo passaggio può essere ignorato se utilizzi Cloud Shell o un ambiente locale in cui hai già installato le librerie client. Devi eseguire questa operazione solo se stai sviluppando localmente e non li hai installati (o non sei sicuro di averlo fatto). Il modo più semplice è utilizzare pip (o pip3) per eseguire l'installazione (incluso l'aggiornamento di pip stesso, se necessario):
pip install -U pip google-api-python-client oauth2client
Conferma l'installazione
Questo comando installa la libreria client e tutti i pacchetti da cui dipende. Indipendentemente dall'ambiente in uso, Cloud Shell o il tuo, verifica che la libreria client sia installata importando i pacchetti necessari e conferma che non siano presenti errori di importazione (né output):
python3 -c "import googleapiclient, httplib2, oauth2client"
Se utilizzi Python 2 (da Cloud Shell), riceverai un avviso che ti informa che il supporto è stato ritirato:
******************************************************************************* Python 2 is deprecated. Upgrade to Python 3 as soon as possible. See https://cloud.google.com/python/docs/python2-sunset To suppress this warning, create an empty ~/.cloudshell/no-python-warning file. The command will automatically proceed in seconds or on any key. *******************************************************************************
Una volta eseguito correttamente il comando "test" di importazione (senza errori/output), puoi iniziare a comunicare con le API di Google.
Riepilogo
Poiché si tratta di un codelab introduttivo, si presume che tu non abbia mai utilizzato le API Google e Google Workspace. Se hai già esperienza nella creazione di progetti e di ID client OAuth per l'autorizzazione degli utenti. In questo caso, crea o riutilizza un progetto esistente, crea o riutilizza un ID client OAuth esistente e salta i due moduli successivi per passare direttamente a "Visualizzazione dell'applicazione per file e cartelle di Drive" o vai direttamente a "Utilizzo avanzato di DevConsole" per esaminare questi passaggi con meno indicazioni.
6. Specifica il progetto in Cloud Console
Un'applicazione che utilizza le API di Google richiede un progetto. Questi vengono gestiti nella console Google Cloud Developers o semplicemente "devconsole". In questo codelab utilizzeremo solo l'API Google Drive, quindi abbiamo un link magico (di seguito nel passaggio 1) che:
- Ti porta alla console per gli sviluppatori
- Ti guida nella creazione di un nuovo progetto (o nella scelta di uno esistente) e
- Abilita automaticamente l'API Drive
Iniziamo!
- Vai alla pagina console.developers.google.com/start/api?id=drive e accedi al tuo Account Google.
- Se non hai ancora progetti, vedrai questa schermata per accettare i Termini di servizio delle API di Google:
Una volta accettati i termini, verrà creato un nuovo progetto denominato "Il mio progetto" e l'API Drive verrà attivata automaticamente. 3. Se invece hai già creato un progetto (magari il tuo codelab precedente), vedrai questa schermata: 
Quando fai clic sul menu a discesa Crea un progetto, scegli un progetto esistente o creane uno nuovo. 
Una volta effettuata la selezione (progetto nuovo o esistente), l'API Drive verrà attivata automaticamente. 4. Saprai che l'API Drive è stata abilitata con questa conferma: 
5. Fai clic su Vai alle credenziali per passare al passaggio successivo.
7. *Autorizza le richieste API (autorizzazione utente)
Questa sezione può essere ignorata se hai già creato le credenziali di autorizzazione dell'account utente e hai familiarità con la procedura. È diverso dall'autorizzazione del service account, la cui tecnica è diversa, quindi continua a leggere di seguito.
Introduzione all'autorizzazione (più qualche autenticazione)
Per effettuare richieste alle API, la tua applicazione deve disporre dell'autorizzazione appropriata. Autenticazione, un termine simile, descrive le credenziali di accesso. Ti autentichi quando accedi al tuo Account Google con un nome utente e una password. Una volta autenticato, il passaggio successivo consiste nel verificare se tu, o meglio, il tuo codice, sei autorizzato ad accedere ai dati, ad esempio ai file blob su Cloud Storage o ai file personali di un utente su Google Drive.
Le API di Google supportano diversi tipi di autorizzazione, ma quella più comune per gli utenti delle API Google Workspace è l'autorizzazione utente, poiché l'applicazione di esempio in questo codelab accede ai dati appartenenti agli utenti finali. Questi utenti finali devono concedere l'autorizzazione alla tua app per accedere ai loro dati. Ciò significa che il codice deve ottenere le credenziali OAuth2 dell'account utente.
Per ottenere le credenziali OAuth2 per l'autorizzazione utente, torna a Gestione API e seleziona la scheda "Credenziali" nel riquadro di navigazione a sinistra:
Una volta lì, vedrai tutte le tue credenziali in tre sezioni separate:
Il primo è per le chiavi API, il secondo per gli ID client OAuth 2.0 e l'ultimo per gli account di servizio OAuth2. Utilizziamo quello centrale.
Creazione delle credenziali
Nella pagina Credenziali, fai clic sul pulsante + Crea credenziali in alto, che apre una finestra di dialogo in cui scegliere "ID client OAuth":
Nella schermata successiva, hai due azioni: configurare la "schermata di consenso" dell'autorizzazione dell'app e scegliere il tipo di applicazione:
Se non hai impostato una schermata per il consenso, vedrai l'avviso nella console e dovrai farlo ora. Salta i passaggi successivi se la schermata per il consenso è già stata configurata.
Schermata consenso OAuth
Fai clic su "Configura schermata per il consenso", dove selezioni un'app"Esterna " (o"Interna" se sei un cliente Google Workspace [in precedenza "Google Workspace"]):
Tieni presente che ai fini di questo esercizio, non importa quale scegli perché non pubblicherai l'esempio di codelab. La maggior parte degli utenti selezionerà "Esterno" per accedere a una schermata più complessa, ma in realtà devi solo compilare il campo "Nome applicazione" in alto:
L'unica cosa che ti serve al momento è un nome dell'applicazione, quindi scegli un nome che rifletta il codelab che stai seguendo e fai clic su Salva.
Creazione dell'ID client OAuth (autenticazione dell'account utente)
Ora torna alla scheda Credenziali per creare un ID client OAuth2. Qui vedrai una serie di ID client OAuth che puoi creare:
Stiamo sviluppando uno strumento a riga di comando, ovvero Altro, quindi scegli questa opzione e fai clic sul pulsante Crea. Scegli un nome per l'ID client che rifletta l'app che stai creando o accetta il nome predefinito, che di solito è "Altro client N".
Salvataggio delle credenziali
- Viene visualizzata una finestra di dialogo con le nuove credenziali; fai clic su Ok per chiuderla.
- Torna alla pagina Credenziali, scorri verso il basso fino alla sezione "ID client OAuth2", individua e fai clic sull'icona di download
in basso a destra dell'ID client appena creato.
- Si apre una finestra di dialogo per salvare un file denominato
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, probabilmente nella cartella Download. Ti consigliamo di abbreviare il nome in uno più semplice, ad esempioclient_secret.json(che è quello utilizzato dall'app di esempio), quindi di salvarlo nella directory/cartella in cui creerai l'app di esempio in questo codelab.
Riepilogo
Con le credenziali a portata di mano, ora puoi accedere all'API Drive dalla tua app, tenendo presente che lo scopo dell'ID client OAuth è che i tuoi utenti devono concedere alla tua app l'autorizzazione ad accedere ai loro dati in Google Drive.
NOTE: ulteriori dettagli sulla creazione di progetti, sull'attivazione delle API e sull'ottenimento delle credenziali, manualmente, ovvero senza l'utilizzo della "procedura guidata" sopra descritta, sono disponibili al termine di questo codelab per ulteriori approfondimenti.
8. Visualizzazione dell'applicazione File e cartelle di Drive
Nell'ambiente di sviluppo locale o in Cloud Shell, nella stessa directory in cui si trova il file delle credenziali client_id.json, crea un nuovo file Python denominato drive_list.py e aggiungi le righe di codice riportate di seguito:
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
Struttura dell'applicazione
Questa applicazione è suddivisa in tre sezioni principali:
- Importazioni Python per includere la funzionalità della libreria
- Recupero delle credenziali dell'applicazione
- Recuperare e visualizzare i nomi di file e cartelle e i tipi MIME in Google Drive dell'utente
NOTE: dopo la conclusione di questo codelab, è disponibile un'analisi più approfondita del codice e una spiegazione riga per riga per ulteriori approfondimenti.
Esecuzione dell'applicazione
Assegna al file un nome come drive_list.py. La prima volta che esegui lo script, non avrà l'autorizzazione per accedere ai file dell'utente su Drive (i tuoi). L'output è simile al seguente con l'esecuzione in pausa:
$ python3 ./drive_list.py /usr/local/lib/python3.6/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Your browser has been opened to visit: https://accounts.google.com/o/oauth2/auth?client_id=LONG-STRING.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2F&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
Dall'ambiente di sviluppo locale
Lo script della riga di comando viene messo in pausa quando si apre una finestra del browser che mostra la finestra di dialogo delle autorizzazioni OAuth2:
È qui che l'applicazione chiede all'utente le autorizzazioni richieste dal codice (tramite la variabile SCOPES). In questo caso, si tratta della possibilità di visualizzare i metadati del file da Google Drive dell'utente. Sì, nel codice questi ambiti di autorizzazione vengono visualizzati come URI, ma vengono tradotti nella lingua specificata dalle impostazioni internazionali nella finestra di dialogo del flusso OAuth2. L'utente deve concedere l'autorizzazione esplicita per le autorizzazioni richieste, altrimenti la parte "run flow" del codice genererà un'eccezione e lo script non procederà oltre.
NOTE: alcuni utenti hanno più browser e la richiesta di autorizzazione potrebbe essere visualizzata in un browser non preferito. In questo caso, copia l'intero URL dalla finestra del browser che non vuoi utilizzare e incollalo nella barra degli indirizzi di un browser che vuoi utilizzare.
Da Cloud Shell
Se non hai prestato attenzione ed eseguito il programma in Cloud Shell, non si è aperta alcuna finestra del browser, lasciandoti bloccato. Ho capito che il messaggio diagnostico in basso era per te… questo:
If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
Se lo esegui in questo modo, otterrai il seguente output:
$ python3 drive_list.py --noauth_local_webserver /usr/local/lib/python3.7/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Go to the following link in your browser: https://accounts.google.com/o/oauth2/auth?client_id=xxx.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code Enter verification code:
Se segui le istruzioni e vai a un'altra scheda del browser con questo URL, otterrai un'esperienza quasi identica a quella descritta sopra per gli ambienti di sviluppo locali. La differenza principale si trova alla fine, dove viene visualizzata un'altra schermata con il codice di verifica da inserire in Cloud Shell:
Taglia e incolla questo codice nella finestra del terminale.
Riepilogo
Una volta che l'utente fa clic su Consenti e/o il codice di verifica viene incollato nel prompt, l'app continuerà a essere eseguita, quindi prevedi di visualizzare un output costituito da file/cartelle di Drive e dai relativi tipi MIME. Ecco un esempio di uno dei nostri account di test:
$ python3 ./drive_list.py Travel expenses application/vnd.google-apps.spreadsheet Gmail Add-ons codelab application/vnd.google-apps.script Google Workspace Developer Intro application/vnd.google-apps.presentation Baseball Sheets application/vnd.google-apps.folder My Resume application/vnd.google-apps.document . . .
Nota che nelle esecuzioni successive non ti viene più chiesto di autorizzare (perché è stato memorizzato nella cache dalle librerie di autenticazione) e vai direttamente all'output. Non è emozionante vedere i tuoi documenti in un terminale per la prima volta? Pensiamo di sì.
9. Conclusione
Ora puoi scoprire altre funzionalità dell'API Drive o esplorare altre API di Google Workspace (Gmail, Documenti, Fogli, Presentazioni, Calendar) e di Google (Maps, Analytics, YouTube e così via). Congratulazioni per aver completato il corso.
Il codice utilizzato in questo codelab è disponibile anche nel suo repository GitHub all'indirizzo github.com/googlecodelabs/gsuite-apis-intro. (Il nostro obiettivo è mantenere questo codelab sincronizzato con il repository.) Vuoi proseguire? Di seguito sono riportate varie risorse a cui puoi accedere per approfondire il materiale trattato in questo codelab o se vuoi mettere alla prova la tua mente ed esplorare altri modi di accedere alle tecnologie Google in modo programmatico.
Come accennato in precedenza, se non sei uno sviluppatore Python abituale, ti invitiamo a ripetere questo esempio di codelab nel tuo linguaggio di sviluppo preferito. Le librerie client per le lingue supportate sono disponibili qui.
Studio aggiuntivo
Ora che hai un po' di esperienza con l'API Drive, di seguito sono riportati alcuni esercizi consigliati per sviluppare ulteriormente le tue competenze:
- File ZIP: scrivi un'applicazione che esegue il backup di più archivi ZIP su Drive, decomprimendoli al volo in modo che ogni nome di file ZIP corrisponda al nome della cartella in cui vengono inseriti i file. EXTRA CREDIT: support recursive ZIP archives within other ZIP files with Drive folders embedded inside other folders. Se ti arrendi, consulta questa app Node.js di esempio.
- Album fotografici: scrivi l'inizio di uno strumento di generazione di album fotografici che carichi più immagini su Google Drive, organizzandole in cartelle separate in base al timestamp e alla geolocalizzazione. ATTIVITÀ EXTRA: trova una libreria di manipolazione delle immagini open source e unisci tutte le foto di ogni cartella per rappresentare gli eventi che potresti aver vissuto (un viaggio, una cena e così via).
- Esplora GCP: scrivi un'app che connette Google Workspace e Google Cloud Platform (GCP). Scrivi uno strumento che esegua il backup dei file immagine da Google Drive a Google Cloud Storage (GCS), un'altra soluzione di "archiviazione di file nel cloud". Che tu ci creda o no, l'utilizzo di GCS sarà più semplice di Drive grazie alle sue librerie client avanzate.
- Analizza e registra: estendi la tua soluzione al punto 3 analizzando ogni immagine di cui è stato eseguito il backup passandola all'API Google Cloud Vision e ottenendo le prime (3, 5, 10) "etichette" di ciò che l'API vede in queste immagini. Per ogni immagine, scrivi una riga in un foglio Google contenente l'analisi di Cloud Vision e la sua posizione di backup su GCS. Se ti arrendi, consulta questo codelab Python.
10. Risorse aggiuntive
Documentazione
- Documentazione dell'API Google Drive (API REST e SDK/API nativo per Android)
- Documentazione di altre API Google Workspace
- Documentazione di altre API di Google
- Librerie client delle API di Google
- Documentazione OAuth2
Video correlati e generali
- Creazione di nuovi progetti API Google ( post del blog e video)
- Revisione del codice boilerplate di autorizzazione Python ( video)
- Elenco dei file in Google Drive ( video, post del blog)
- Libreria di video dell'API Google Drive
- Launchpad Online serie di video (predecessore di...)
- Google Workspace Dev Show serie di video
Novità e aggiornamenti
- Blog per sviluppatori di Google Workspace
- Sviluppatori Google Workspace Twitter (@GSuiteDevs)
- Newsletter mensile per gli sviluppatori di Google Workspace
Altri codelab
Introduttivo
- [Apps Script] Introduzione a Google Apps Script
Intermedio
- [Apps Script] Strumento da riga di comando CLASP Apps Script
- [Apps Script] Componenti aggiuntivi di Gmail
- [Apps Script] Componente aggiuntivo per Documenti e API Natural Language di GCP
- [Apps Script] Framework per bot di Hangouts Chat
- [API REST] Strumento di generazione di report personalizzati (API Sheets)
- [API REST] Generatore di slide personalizzate per l'analizzatore BigQuery delle licenze GitHub (API Slides + BigQuery)
Avanzate
- [API REST] Flusso di lavoro di elaborazione delle immagini nel cloud (API Drive, Cloud Storage, Cloud Vision e Sheets)
App per la consultazione
- Convertitore da Markdown a Presentazioni Google (API REST di Presentazioni)
11. *Spiegazione dettagliata dell'applicazione
Questa sezione facoltativa deve essere utilizzata per lo studio autonomo al termine della sessione per colmare eventuali lacune o per ulteriori ricerche.
Importazioni Python per includere la funzionalità della libreria
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
- La prima istruzione
importconsente l'esecuzione di questo codice su Python 2. Può essere eliminata completamente se utilizzi solo Python 3. - Una delle linee guida di stile di Python prevede di separare le importazioni di librerie standard e moduli di terze parti. A questo scopo serve la riga vuota.
- I tre import successivi importano le classi e le funzioni necessarie dalla libreria client delle API di Google. Sono tutte necessarie per scrivere questa app. In breve, ecco cosa fanno:
googleapiclientsi concentra sulla connessione alle API di Googlehttplib2fornisce un client HTTP da utilizzare per l'appoauth2clientci aiuta a gestire le credenziali OAuth2
Autorizzazione e ottenimento delle credenziali dell'applicazione
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
- Le
SCOPESdell'applicazione sono le autorizzazioni che un'app chiederà all'utente che la esegue. Per proteggere i dati utente, le app non possono essere eseguite senza l'autorizzazione - Una best practice consiste nell'utilizzare le autorizzazioni più restrittive necessarie per il funzionamento dell'app. Perché?
- Non è fastidioso quando un'app chiede un ampio insieme di autorizzazioni quando la installi o la esegui? Indovina? Ora ti trovi dall'altra parte della medaglia e devi chiedere agli utenti tutte queste autorizzazioni. L'utilizzo di ambiti più restrittivi fa sentire gli utenti più a loro agio nell'installare la tua app perché chiedi un accesso inferiore.
- La maggior parte degli ambiti ha l'aspetto di URL lunghi e l'ambito dei metadati di Drive non fa eccezione.
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
- Per comunicare con i server di Google, le app richiedono un token. I token validi restituiti da Google verranno salvati nel file di archiviazione dei token,
storage.json. Se non salvi questi token, dovrai autorizzare nuovamente l'app ogni volta che la esegui.
store = file.Storage('storage.json')
- Questa app controlla innanzitutto se sono già presenti credenziali valide nell'archivio (vedi l'istruzione condizionale
if).
creds = store.get()
if not creds or creds.invalid:
- Se non hai credenziali o sono scadute, devi creare un nuovo flusso di autorizzazione [tramite
oauth2client.client.flow_from_clientsecrets()] dall'ID client e dal secret OAuth nel fileclient_id.jsonche hai scaricato.
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
- Una volta che l'app ha un flusso, deve essere eseguito per presentare all'utente la schermata delle autorizzazioni OAuth2 [tramite
oauth2client.tools.run_flow()] descritta e illustrata sopra.
creds = tools.run_flow(flow, store)
- Se fai clic su Consenti, gli utenti acconsentono all'accesso della tua app ai metadati dei file di Google Drive e i server di Google restituiscono token per accedere all'API. Vengono restituiti come
credse memorizzati nella cache del filestorage.json. - A questo punto, la tua app dispone di credenziali valide per effettuare chiamate API. La chiamata
googleapiclient.discovery.build()crea un endpoint di servizio per l'API che stai utilizzando. - Per utilizzare
build(), trasmetti il nome dell'API ('drive') e la versione desiderata (al momento'v3'). - L'ultimo parametro è un client HTTP da utilizzare per le chiamate API criptate.
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
Recupera e visualizza i primi 100 file/cartelle di Drive e i tipi MIME
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
- La riga di codice successiva chiama il metodo
list()nella raccoltafiles()per l'API Drive per creare la richiesta, che viene chiamata immediatamente conexecute(). Viene restituito undictPython da cui chiediamo la chiave'files'per ottenere i nomi di 100 file e cartelle da Google Drive dell'utente (o meno se hai meno file). - Perché 100? Questo è il valore predefinito di
DRIVE.files().list(). Se vuoi modificare questo numero, ad esempio per visualizzare solo 10 file o 1000, aggiungi il parametropageSizealla richiesta:DRIVE.files().list(pageSize=10). Per altre opzioni, consulta la documentazione. - L'ultima parte dello script scorre ogni file e mostra i relativi nomi e tipi MIME.
Ora hai scritto la tua prima applicazione che utilizza un'API REST di Google. Congratulazioni. A parte le importazioni e il codice di autorizzazione, questo script è costituito da un paio di righe di codice (quelle che vedi sopra). La maggior parte delle API di Google funziona in modo simile e devi creare endpoint di servizio solo per quelle che vuoi utilizzare.
Utilizzo di più di un'API Google in un'app
Sì, puoi utilizzare più di un'API nella stessa app. Ecco uno snippet di codice Python per un'app che riutilizza lo stesso client HTTP e crea endpoint di servizio per tre API di Google (sì, anche con tre SCOPES diverse):
SCOPES = (
'https://www.googleapis.com/auth/drive',
'https://www.googleapis.com/auth/spreadsheets.readonly',
'https://www.googleapis.com/auth/presentations',
)
. . .
HTTP = creds.authorize(Http())
DRIVE = discovery.build('drive', 'v3', http=HTTP)
SHEETS = discovery.build('sheets', 'v4', http=HTTP)
SLIDES = discovery.build('slides', 'v1', http=HTTP)
Immaginiamo che questo codice possa far parte di un'app che genera più presentazioni (API Slides) in base ai dati del foglio di lavoro (API Sheets) e utilizza un modello di slide che viene copiato (API Drive) per ogni presentazione generata. Anche se non esiste un'app di questo tipo, dovresti essere in grado di creare qualcosa di simile utilizzando due esempi esistenti che il team di Google Workspace ha creato come elementi costitutivi:
- Sostituzione di testo e immagini nelle slide ( post del blog e video): utilizza l'API Drive per copiare un file modello di slide, quindi impiega l'API Slides per modificare i segnaposto di testo e immagini
- Generazione di slide dai dati del foglio di lavoro ( post del blog e video): legge i dati da un foglio di lavoro (API Sheets) e crea slide (API Slides) in base a questi dati
La tua sfida: creare l'app.
12. *Utilizzo avanzato di DevConsole
In questa sezione facoltativa, descriviamo come creare progetti in devconsole, attivare le API e ottenere le credenziali, il tutto senza utilizzare la procedura guidata come descritto in precedenza nel codelab. Questa opzione è pensata per gli utenti intermedi che si sentono a loro agio a farlo manualmente o che vogliono imparare a farlo.
Specifica il progetto nella console Cloud
Ogni volta che scrivi un'applicazione utilizzando le API di Google, devi avere un progetto. Puoi riutilizzare un progetto esistente o crearne uno nuovo. Questa operazione viene eseguita nella console Cloud. Alcuni codelab forniscono un link magico (ad es. come una procedura guidata di configurazione) che ti consente di iniziare rapidamente, saltando molti dei passaggi richiesti. Tuttavia, non tutti lo fanno, quindi queste sono istruzioni generali su come creare progetti.
Puoi creare progetti dalla maggior parte delle schermate della console Cloud, a condizione che tu abbia eseguito l'accesso con le tue credenziali Google e che tu veda un menu a discesa del progetto nella parte superiore della console. Tieni presente che la maggior parte degli screenshot qui riportati sono stati acquisiti da API Manager, ovvero la Developers Console (facilmente raggiungibile facendo clic su "API Manager" nel menu di navigazione a sinistra o indirizzando direttamente il browser a console.developers.google.com.
- Se non hai ancora progetti, potresti essere indirizzato a...
- la pagina Dashboard:
- la pagina Raccolta:
- o una pagina completamente vuota:
Se si verifica questo terzo caso, aggiorna il browser per accedere alla pagina Raccolta.
- Che tu ti trovi nelle pagine Dashboard o Raccolta, fai clic sul selettore di progetti nella parte superiore della pagina:
- Successivamente, verrà visualizzata la finestra di dialogo del selettore. Fai clic sul segno "+" a destra per creare un nuovo progetto:
- Dopo aver fatto clic su "+", viene visualizzata una pagina Nuovo progetto. Per impostazione predefinita, tutti gli account consumer ricevono 12 progetti. Prima di creare il tuo primo progetto, devi accettare i Termini di servizio delle API di Google:
Una volta fatto, le domande relative alla sollecitazione via email e ai Termini di servizio non vengono più visualizzate quando crei progetti futuri:
Ora hai creato correttamente un progetto e puoi andare avanti scegliendo le API che vuoi utilizzare per il tuo progetto.
Abilita le API di Google
Prima di poter iniziare a utilizzare le API di Google, devi abilitarle. L'esempio seguente mostra cosa devi fare per abilitare l'API Cloud Vision. In questo codelab potresti utilizzare una o più API e dovresti seguire passaggi simili per abilitarle prima dell'utilizzo.
Da Cloud Shell
Utilizzando Cloud Shell, puoi abilitare l'API utilizzando il seguente comando:
gcloud services enable vision.googleapis.com
Dalla console Cloud
Puoi anche abilitare l'API Vision in API Manager. Nella console Cloud, vai a API Manager e seleziona "Libreria".
Nella barra di ricerca, inizia a digitare "vision", quindi seleziona Vision API quando viene visualizzata. Mentre digiti, potrebbe avere un aspetto simile al seguente:
Seleziona l'API Cloud Vision per visualizzare la finestra di dialogo mostrata di seguito, quindi fai clic sul pulsante "Attiva":
Costo
Sebbene molte API di Google possano essere utilizzate senza costi, l'utilizzo di GCP (prodotti e API) non è senza costi. Quando abiliti l'API Vision (come descritto sopra), potrebbe esserti chiesto un account di fatturazione attivo. L'utente deve fare riferimento alle informazioni sui prezzi dell'API Vision prima di abilitarla. Tieni presente che alcuni prodotti Google Cloud Platform (GCP) includono un livello"Always Free" che devi superare per incorrere nella fatturazione. Ai fini del codelab, ogni chiamata all'API Vision viene conteggiata in base a questo livello senza costi e, finché rimani entro i limiti complessivi (entro ogni mese), non dovresti sostenere alcun costo.
Alcune API di Google, ad esempio Google Workspace, il cui utilizzo è coperto da un abbonamento mensile, quindi non è prevista una fatturazione diretta per l'utilizzo delle API Gmail, Google Drive, Calendar, Documenti, Fogli e Presentazioni, ad esempio. I diversi prodotti Google vengono fatturati in modo diverso, quindi assicurati di consultare la documentazione dell'API per queste informazioni.
Riepilogo
In questo codelab, devi solo attivare l'API Google Drive, quindi segui le istruzioni riportate sopra e cerca "Drive". Procedi una volta attivato.
Autorizzazione delle richieste API (autorizzazione utente)
Introduzione all'autorizzazione (più qualche autenticazione)
Per effettuare richieste alle API, la tua applicazione deve disporre dell'autorizzazione appropriata. Autenticazione, un termine simile, descrive le credenziali di accesso. Ti autentichi quando accedi al tuo Account Google con un nome utente e una password. Una volta autenticato, il passaggio successivo consiste nel verificare se tu, o meglio, il tuo codice, sei autorizzato ad accedere ai dati, ad esempio ai file blob su Cloud Storage o ai file personali di un utente su Google Drive.
Le API di Google supportano diversi tipi di autorizzazione, ma quella più comune per gli utenti delle API Google Workspace è l'autorizzazione utente, poiché l'applicazione di esempio in questo codelab accede ai dati appartenenti agli utenti finali. Questi utenti finali devono concedere l'autorizzazione alla tua app per accedere ai loro dati. Ciò significa che il codice deve ottenere le credenziali OAuth2 dell'account utente.
Per ottenere le credenziali OAuth2 per l'autorizzazione utente, torna a Gestione API e seleziona la scheda "Credenziali" nel riquadro di navigazione a sinistra:
Una volta lì, vedrai tutte le tue credenziali in tre sezioni separate:
Il primo è per le chiavi API, il secondo per gli ID client OAuth 2.0 e l'ultimo per gli account di servizio OAuth2. Utilizziamo quello centrale.
Creazione delle credenziali
Nella pagina Credenziali, fai clic sul pulsante + Crea credenziali in alto, che apre una finestra di dialogo in cui scegliere "ID client OAuth":
Nella schermata successiva, hai due azioni: configurare la "schermata di consenso" dell'autorizzazione dell'app e scegliere il tipo di applicazione:
Se non hai impostato una schermata per il consenso, vedrai l'avviso nella console e dovrai farlo ora. Salta i passaggi successivi se la schermata per il consenso è già stata configurata.
Schermata consenso OAuth
Fai clic su "Configura schermata per il consenso", dove selezioni un'app"Esterna " (o"Interna" se sei un cliente Google Workspace):
Tieni presente che ai fini di questo esercizio, non importa quale scegli perché non pubblicherai l'esempio di codelab. La maggior parte degli utenti selezionerà "Esterno" per accedere a una schermata più complessa, ma in realtà devi solo compilare il campo "Nome applicazione" in alto:
L'unica cosa che ti serve al momento è un nome dell'applicazione, quindi scegli un nome che rifletta il codelab che stai seguendo e fai clic su Salva.
Creazione dell'ID client OAuth (autenticazione dell'account utente)
Ora torna alla scheda Credenziali per creare un ID client OAuth2. Qui vedrai una serie di ID client OAuth che puoi creare:
Stiamo sviluppando uno strumento a riga di comando, ovvero Altro, quindi scegli questa opzione e fai clic sul pulsante Crea. Scegli un nome per l'ID client che rifletta l'app che stai creando o accetta il nome predefinito, che di solito è "Altro client N".
Salvataggio delle credenziali
- Viene visualizzata una finestra di dialogo con le nuove credenziali; fai clic su Ok per chiuderla.
- Torna alla pagina Credenziali, scorri verso il basso fino alla sezione "ID client OAuth2", individua e fai clic sull'icona di download
- Si apre una finestra di dialogo per salvare un file denominato
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, probabilmente nella cartella Download. Ti consigliamo di abbreviare il nome in uno più semplice, ad esempioclient_secret.json(che è quello utilizzato dall'app di esempio), quindi di salvarlo nella directory/cartella in cui creerai l'app di esempio in questo codelab.