API Google Picker

Finestra di dialogo Selettore di Google.

Selettore Google è una finestra di dialogo "Apertura file" per le informazioni memorizzate su Google Drive. Il selettore Google dispone di queste funzionalità:

  • Aspetto e design simili a quelli dell'interfaccia utente di Google Drive.
  • Diverse visualizzazioni che mostrano anteprime e miniature di file di Drive.
  • Una finestra modale incorporata che impedisce agli utenti di uscire dall'applicazione principale.

L'API Google Picker è un'API JavaScript che puoi utilizzare nelle app web per consentire agli utenti di aprire o caricare file di Drive.

Requisiti dell'applicazione

Le applicazioni che utilizzano il selettore Google devono rispettare tutti i Termini di servizio esistenti. Cosa più importante, devi identificarti correttamente nelle tue richieste.

Devi anche avere un progetto Google Cloud.

Configura l'ambiente

Per iniziare a utilizzare l'API Google Picker, devi configurare il tuo 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.

Crea una chiave API

Una chiave API è una lunga stringa contenente lettere maiuscole e minuscole, numeri, trattini bassi e trattini, come 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 in Internet con questo link". Per maggiori dettagli, consulta Autenticarsi utilizzando le chiavi API.

Per creare una chiave API:

  1. Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.

    Vai a Credenziali

  2. Fai clic su Crea credenziali > Chiave API.
  3. 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.

Autorizzare le credenziali per un'applicazione web

Per autenticarti come utente finale e accedere ai dati utente nella tua app, devi creare uno o più ID client OAuth 2.0. Un ID client viene utilizzato per identificare una singola app ai server OAuth di Google. Se la tua app viene eseguita su più piattaforme, devi creare un ID client separato per ogni piattaforma.

  1. Nella console Google Cloud, vai a Menu > API e servizi > Credenziali.

    Vai a Credenziali

  2. Fai clic su Crea credenziali > ID client OAuth.
  3. Fai clic su Tipo di applicazione > Applicazione web.
  4. Nel campo Nome, digita un nome per la credenziale. Questo nome viene visualizzato solo nella console Google Cloud.
  5. 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.
  6. 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.

  7. Fai clic su OK. Le credenziali appena create vengono visualizzate in ID client OAuth 2.0.
  8. (Facoltativo) Se stai creando credenziali come prerequisito per una guida rapida di JavaScript, devi anche generare una chiave API.
Importante: l'applicazione deve inviare un token di accesso OAuth 2.0 con viste che accedono ai dati utente privati durante la creazione di un oggetto Picker. Per richiedere un token di accesso, vedi Utilizzare OAuth 2.0 per accedere alle API di Google.

Mostra il selettore Google

La parte restante di questa guida illustra come caricare e visualizzare il selettore Google da un'app web. Per visualizzare l'esempio completo, vai all'esempio di codice del selettore Google.

Carica la raccolta del selettore Google

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() {
        // TODO(developer): Replace with your client ID and required scopes
        tokenClient = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_CLIENT_ID',
          scope: 'YOUR_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>
    

La funzione onApiLoad() carica le librerie del selettore Google. La funzione di callback onPickerApiLoad() viene chiamata dopo il caricamento corretto della libreria di Google Picker.

Mostra il selettore Google

La funzione createPicker() verifica che l'API Google Picker termini il caricamento e che venga creato un token OAuth. Quindi, questa funzione crea un'istanza del selettore Google e la visualizza:

    // Create and render a Google Picker object for selecting from Drive
    function createPicker() {
      const showPicker = () => {
        // TODO(developer): Replace with your API key
        const picker = new google.picker.PickerBuilder()
            .addView(google.picker.ViewId.DOCS)
            .setOAuthToken(accessToken)
            .setDeveloperKey('YOUR_API_KEY')
            .setCallback(pickerCallback)
            .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: ''});
      }
    }
    

Per creare un'istanza di Google Picker, devi fornire un elemento View, un oauthToken, un developerKey e una funzione di callback per chiamare al successo (pickerCallback).

Un oggetto Picker esegue il rendering di un View alla volta. Specifica almeno una vista, ViewId (google.​picker.​ViewId.*) o creando un'istanza di tipo (google.​picker.​*View). Specifica la visualizzazione per tipo per un ulteriore controllo sul modo in cui viene visualizzata la visualizzazione.

Se vengono aggiunte più viste al selettore Google, gli utenti possono passare da una visualizzazione all'altra facendo clic su una scheda a sinistra. Le schede possono essere raggruppate logicamente con oggetti ViewGroup.

Implementare il callback Picker

Il callback Picker può essere utilizzato per reagire alle interazioni degli utenti nel selettore Google, ad esempio la selezione di un file o la pressione di Annulla.

    // A simple callback implementation.
    function pickerCallback(data) {
      let url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        let doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      let message = `You picked: ${url}`;
      document.getElementById('result').innerText = message;
    }
    

Il callback riceve un oggetto data con codifica JSON. Questo oggetto contiene tutte le azioni che l'utente esegue con il selettore Google (google.picker.Response.ACTION). Se l'utente seleziona un elemento, viene completato anche l'array google.picker.Response.DOCUMENTS. In questo esempio, google.picker.Document.URL viene visualizzato nella pagina principale. Per informazioni dettagliate sui campi dei dati, consulta la documentazione di riferimento JSON.

Filtrare tipi di file specifici

Utilizza ViewGroup per filtrare elementi specifici. Nell'esempio seguente, la visualizzazione secondaria "Google Drive" mostra solo documenti e presentazioni.

    let 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)
        .setCallback(pickerCallback)
        .build();
    

Regola l'aspetto del selettore Google

Utilizza la funzione PickerBuilder.enableFeature() per perfezionare l'aspetto della finestra del selettore Google. Ad esempio, se hai una sola vista, puoi nascondere il riquadro di navigazione per concedere agli utenti più spazio per visualizzare gli elementi. Ecco un esempio di selettore di ricerca dei fogli di lavoro che mostra questa funzionalità:

     let picker = new google.picker.PickerBuilder()
         .addView(google.picker.ViewId.SPREADSHEETS)
         .enableFeature(google.picker.Feature.NAV_HIDDEN)
         .setDeveloperKey(developerKey)
         .setCallback(pickerCallback)
         .build();
     

Visualizzare il selettore Google in altre lingue

Specifica la lingua dell'interfaccia utente fornendo le impostazioni internazionali all'istanza PickerBuilder utilizzando il metodo setLocale(locale). Di seguito è riportato un esempio in lingua francese:

    let picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.IMAGE_SEARCH)
        .setLocale('fr')
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

Di seguito è riportato l'elenco delle impostazioni internazionali attualmente supportate:

af
am
ar
bg
bn
ca
cs
da
de
el
en
en-GB
es
es-419
et
eu
fa
fi
fil
fr
fr-CA
gl
gu
hi
hr
hu
id
is
it
iw
ja
kn
ko
lt
lv
ml
mr
ms
nl
no
pl
pt-BR
pt-PT
ro
ru
sk
sl
sr
sv
sw
ta
te
th
tr
uk
ur
vi
zh-CN
zh-HK
zh-TW
zu