Questo documento spiega come integrare Google Picker nelle app web
utilizzando l'API Google Picker.
L'API Google Picker è un'API JavaScript che puoi implementare per consentire agli utenti di selezionare o caricare file di Google Drive utilizzando Google Picker. Gli utenti possono concedere alle tue app l'autorizzazione ad accedere ai propri dati di Drive, fornendo un modo sicuro e autorizzato per interagire con i loro file.
Funzionalità
Google Picker ha diverse funzionalità:
- Un aspetto simile all'interfaccia utente di Google Drive.
- Diverse visualizzazioni che mostrano anteprime e immagini in miniatura dei file di Drive.
- Visualizzazioni pre-filtrate che mostrano solo tipi di file specifici (come PDF o immagini) o determinate cartelle.
- Una finestra modale in linea, in modo che gli utenti non abbandonino mai l'app principale.
Tieni presente che, sebbene tu possa selezionare e caricare file con Google Picker, non consente agli utenti di organizzare, spostare o copiare file da una cartella all'altra. Per gestire i file, devi utilizzare l'API Google Drive o l'interfaccia utente di Drive.
Prerequisiti
Le app che utilizzano Google Picker devono rispettare tutti i Termini di servizio esistenti. Ancora più importante, devi identificarti correttamente nelle tue richieste.
Devi anche disporre di un progetto Google Cloud.
Configura l'ambiente
Per iniziare a utilizzare l'API Google Picker, devi configurare l'ambiente.
Abilita l'API
Prima di utilizzare le API di Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.Nella console Google Cloud, abilita l'API Google Picker.
Crea una chiave API
Una chiave API è una stringa lunga contenente lettere maiuscole e minuscole, numeri, trattini bassi e
trattini, ad esempio AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Questo metodo di autenticazione
viene utilizzato per accedere in modo anonimo ai dati disponibili pubblicamente, ad esempio i file di Google Workspace condivisi utilizzando
l'impostazione di condivisione "Chiunque su internet con questo link". Per maggiori dettagli, vedi
Gestire le chiavi 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 in your app's code. La chiave API è disponibile anche nella sezione "Chiavi API" delle credenziali del progetto.
- Per impedire l'uso non autorizzato, ti consigliamo di limitare dove e per quali API può essere utilizzata la chiave API. Per maggiori dettagli, vedi Aggiungere limitazioni API.
Autorizza le credenziali per un'app web
Per autenticare gli utenti finali 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 l'app viene eseguita su più piattaforme, devi creare un ID client separato per ogni piattaforma.- Nella console API di Google, vai a Menu > Piattaforma di autenticazione Google > Client.
- Fai clic su Crea client.
- Fai clic su Tipo di applicazione > Applicazione web.
- Nel campo Nome, digita un nome per la credenziale. Questo nome viene visualizzato solo nella console API di Google.
- Aggiungi gli URI autorizzati relativi alla tua app:
- App lato client (JavaScript): in Origini JavaScript autorizzate, fai clic su Aggiungi URI. Poi, inserisci un URI da utilizzare per le richieste del browser. In questo modo vengono identificati i domini da cui l'applicazione può inviare richieste API al server OAuth 2.0.
- App lato server (Java, Python e altro): in URI di reindirizzamento autorizzati, fai clic su Aggiungi URI. Poi, inserisci un URI dell'endpoint a cui il server OAuth 2.0 può inviare le risposte.
- Fai clic su Crea.
La credenziale appena creata viene visualizzata in ID client OAuth 2.0.
Prendi nota dell'ID client. I secret client non vengono utilizzati per le applicazioni web.
Importante: quando crei un oggetto Picker, la tua app deve inviare un token di accesso OAuth 2.0 con le visualizzazioni che
accedono ai dati utente privati. Per richiedere un token di accesso,
vedi Utilizzare OAuth 2.0 per accedere alle API di Google.
Gestisci Google Picker
La parte restante di questo documento spiega come caricare e visualizzare Google Picker da un'app web, nonché come implementare il callback. Per visualizzare l'esempio di codice completo, vedi Utilizzare le funzionalità dell'API Google Picker nelle app web.
Carica la libreria Google Picker
Per caricare la libreria Google Picker, chiama
gapi.load
con il nome della libreria e una funzione di callback da richiamare dopo un caricamento riuscito:
<script>
let tokenClient;
let accessToken = null;
let pickerInited = false;
let gisInited = false;
// Use the API Loader script to load google.picker.
function onApiLoad() {
gapi.load('picker', onPickerApiLoad);
}
function onPickerApiLoad() {
pickerInited = true;
}
function gisLoaded() {
// Replace with your client ID and required scopes.
tokenClient = google.accounts.oauth2.initTokenClient({
client_id: 'CLIENT_ID',
scope: 'SCOPES',
callback: '', // defined later
});
gisInited = true;
}
</script>
<!-- Load the Google API Loader script. -->
<script async defer src="https://apis.google.com/js/api.js" onload="onApiLoad()"></script>
<script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
Sostituisci quanto segue:
CLIENT_ID: l'ID client dell'app web.SCOPES: uno o più ambiti OAuth 2.0 che devi richiedere per accedere alle API di Google, a seconda del livello di accesso di cui hai bisogno. Per ulteriori informazioni, vedi Ambiti OAuth 2.0 per le API di Google.
La libreria JavaScript google.accounts.oauth2 ti aiuta a richiedere il consenso dell'utente e a ottenere un token di accesso per lavorare con i dati utente. Il metodo initTokenClient inizializza un nuovo client token con l'ID client dell'app web. Per ulteriori
informazioni, vedi Utilizzare il modello di token.
La funzione onApiLoad carica le librerie Google Picker. La funzione di callback onPickerApiLoad viene chiamata dopo il caricamento corretto della libreria Google Picker.
Nota:se utilizzi TypeScript, puoi installare
@types/google.picker per
utilizzare window.google.picker. Per segnalare un problema con questi tipi, apri una richiesta di assistenza.
Visualizza Google Picker
La funzione createPicker garantisce che l'API Google Picker abbia terminato il caricamento e che sia stato creato un token OAuth 2.0. Utilizza il metodo PickerBuilder.setAppId per impostare l'ID dell'app Drive
utilizzando il numero di progetto Cloud per consentire all'app
di accedere ai file dell'utente. Questa funzione crea quindi un'istanza di Google Picker e la visualizza:
// Create and render a Google Picker object for selecting from Drive.
function createPicker() {
const showPicker = () => {
// Replace with your API key and App ID.
const picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.DOCS)
.setOAuthToken(accessToken)
.setDeveloperKey('API_KEY')
.setCallback(pickerCallback)
.setAppId('APP_ID')
.build();
picker.setVisible(true);
}
// Request an access token.
tokenClient.callback = async (response) => {
if (response.error !== undefined) {
throw (response);
}
accessToken = response.access_token;
showPicker();
};
if (accessToken === null) {
// Prompt the user to select a Google Account and ask for consent to share their data
// when establishing a new session.
tokenClient.requestAccessToken({prompt: 'consent'});
} else {
// Skip display of account chooser and consent dialog for an existing session.
tokenClient.requestAccessToken({prompt: ''});
}
}
Sostituisci quanto segue:
API_KEY: la tua chiave API.APP_ID: il numero del tuo progetto Cloud.
Per creare un'istanza di Google Picker, devi creare un Picker oggetto utilizzando il PickerBuilder. Il PickerBuilder accetta un View, un token OAuth 2.0, una chiave sviluppatore e una
funzione di callback da chiamare in caso di esito positivo (pickerCallback).
L'oggetto Picker esegue il rendering di una View alla volta. Specifica almeno una visualizzazione,
tramite ViewId
(google.picker.ViewId.*) o creando un'istanza di DocsView per un maggiore controllo sul rendering della visualizzazione.
Se a Google Picker vengono aggiunte più visualizzazioni, gli utenti possono passare da una visualizzazione all'altra facendo clic su una scheda a sinistra. Le schede possono essere raggruppate logicamente
con gli oggetti ViewGroup.
Per un elenco delle visualizzazioni valide, vedi ViewId in
il riferimento di Google Picker. Per ottenere il token per una di queste visualizzazioni, utilizza l'ambito https://www.googleapis.com/auth/drive.file.
Implementa il callback di Google Picker
È possibile utilizzare un callback di Google Picker per reagire alle interazioni dell'utente in Google Picker, ad esempio la selezione di un file o la pressione di Annulla. L'
ResponseObjectinterfaccia trasmette
informazioni sulle selezioni dell'utente.
// A callback implementation.
function pickerCallback(data) {
let url = 'nothing';
if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
const doc = data[google.picker.Response.DOCUMENTS][0];
url = doc[google.picker.Document.URL];
}
const message = `You picked: ${url}`;
document.getElementById('result').textContent = message;
}
Il callback riceve un oggetto dati codificato in JSON. Questo oggetto contiene un
Action eseguita dall'utente con il
Google Picker (google.picker.Response.ACTION). Se l'utente seleziona un
elemento, viene compilato anche l'array google.picker.Response.DOCUMENTS. In questo esempio, google.picker.Document.URL viene visualizzato nella pagina principale. Per informazioni dettagliate sui campi dati, vedi l'interfaccia ResponseObject.
Filtra tipi di file specifici
Utilizza un ViewGroup per filtrare
elementi specifici. Il seguente esempio di codice mostra come la sottovista "Drive" mostra solo documenti e presentazioni.
const picker = new google.picker.PickerBuilder()
.addViewGroup(
new google.picker.ViewGroup(google.picker.ViewId.DOCS)
.addView(google.picker.ViewId.DOCUMENTS)
.addView(google.picker.ViewId.PRESENTATIONS))
.setOAuthToken(oauthToken)
.setDeveloperKey(developerKey)
.setAppId(cloudProjectNumber)
.setCallback(pickerCallback)
.build();
Per un elenco dei tipi di visualizzazione validi, vedi
ViewId.
Ottimizza l'aspetto di Google Picker
Puoi utilizzare l'oggetto Feature per attivare
o disattivare le funzionalità per varie visualizzazioni. Per ottimizzare l'aspetto della finestra di Google Picker, utilizza il PickerBuilder.enableFeature o
PickerBuilder.disableFeature
metodo. Ad esempio, se hai una sola visualizzazione, potresti voler nascondere il
riquadro di navigazione (Feature.NAV_HIDDEN) per
dare agli utenti più spazio per visualizzare gli elementi.
Il seguente esempio di codice mostra un esempio di selettore di ricerca di un foglio di lavoro che utilizza questa funzionalità:
const picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.SPREADSHEETS)
.enableFeature(google.picker.Feature.NAV_HIDDEN)
.setDeveloperKey(developerKey)
.setCallback(pickerCallback)
.build();
Argomenti correlati
- Esempio di codice: utilizzare le funzionalità dell'API Google Picker nelle app web
- Scegliere gli ambiti dell'API Google Drive