API Google Picker

Finestra di dialogo del selettore Google.

Il selettore Google è una finestra di dialogo "Apri file" per le informazioni archiviate su Google Drive. Il selettore di Google ha le seguenti funzioni:

  • Ha un aspetto simile all'interfaccia utente di Google Drive.
  • Diverse visualizzazioni che mostrano anteprime e miniature dei file di Drive.
  • Una finestra modale incorporata, in modo che gli utenti non abbandonino mai l'applicazione principale.

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

Requisiti dell'applicazione

Le applicazioni che utilizzano il selettore di Google devono rispettare tutti i Termini di servizio esistenti. Ma soprattutto, devi identificarti correttamente nelle 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.

  • Nella console Google Cloud, abilita l'API Google Picker.

    Abilita l'API

crea una chiave API

Una chiave API è una lunga stringa 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 navighi su 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 dell'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 tua chiave API. Per maggiori dettagli, vedi Applicare le limitazioni relative alle chiavi API.

Autorizzare le credenziali per un'applicazione web

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 consente di 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.

  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 gli 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. Questo identifica i domini da cui l'applicazione può inviare richieste API al server OAuth 2.0.
    • App lato server (Java, Python e altri): in URI di reindirizzamento autorizzati, fai clic su Aggiungi URI. Quindi, inserisci l'URI dell'endpoint a cui il server OAuth 2.0 può inviare le risposte.
  6. Fai clic su Crea. Viene visualizzata la schermata relativa al client OAuth creato, 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. La credenziale appena creata viene visualizzata in ID client OAuth 2.0.
Importante: l'applicazione deve inviare un token di accesso OAuth 2.0 con viste che accedono ai dati privati dell'utente quando viene creato un oggetto Picker. Per richiedere un token di accesso, consulta l'articolo su come utilizzare OAuth 2.0 per accedere alle API di Google.

Visualizza il selettore di Google

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

Carica la libreria di selettore di Google

Per caricare la libreria di selettore di Google, 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: '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 della tua app web.
  • SCOPES: uno o più ambiti OAuth 2.0 che è necessario richiedere per accedere alle API di Google, a seconda del livello di accesso necessario. Per ulteriori informazioni, consulta l'articolo Ambiti OAuth 2.0 per API di Google.

La libreria JavaScript google.accounts.oauth2 consente di richiedere il consenso dell'utente e ottenere un token di accesso per utilizzare i dati utente. Il metodo initTokenClient() inizializza un nuovo client token con l'ID client della tua app web. Per saperne di più, consulta la sezione Utilizzo del modello di token.

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

Visualizza il selettore di Google

La funzione createPicker() riportata di seguito verifica che l'API Google Picker termini il caricamento e che venga creato un token OAuth. Questa funzione crea quindi un'istanza del selettore di 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('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 del selettore Google, devi creare un oggetto Picker utilizzando PickerBuilder. L'PickerBuilder richiede un View, un token OAuth, una chiave sviluppatore e una funzione di callback da chiamare in caso di esito positivo (pickerCallback).

L'oggetto Picker esegue il rendering di un elemento View alla volta. Specifica almeno una vista, per ViewId (google.​picker.​ViewId.*) o creando un'istanza di un tipo (google.​picker.​*View). Specifica la vista per tipo per avere un ulteriore controllo su come viene visualizzata la vista.

Se vengono aggiunte più visualizzazioni al selettore di Google, 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.

Implementare il callback del selettore di Google

È possibile utilizzare un callback di Google Picker per reagire alle interazioni degli utenti nel selettore Google, ad esempio per selezionare un file o premere Annulla. L'oggetto Response fornisce informazioni sulle selezioni dell'utente.

    // 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 un elemento Action eseguito dall'utente con il selettore di Google (google.picker.Response.ACTION). Se l'utente seleziona un elemento Document, viene completato anche l'array google.picker.Response.DOCUMENTS. In questo esempio, google.picker.Document.URL viene mostrato nella pagina principale. Per maggiori dettagli sui campi di dati, consulta la pagina di riferimento JSON.

Filtrare tipi di file specifici

Utilizza una ViewGroup per filtrare elementi specifici. Il seguente esempio di codice mostra come 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();
    
Per un elenco dei tipi di visualizzazioni validi, consulta ViewId.

Ottimizzare l'aspetto del selettore di Google

Puoi utilizzare l'oggetto Feature per attivare o disattivare le funzionalità per varie visualizzazioni. Per perfezionare l'aspetto della finestra di selettore di Google, utilizza la funzione PickerBuilder.enableFeature() o PickerBuilder.disableFeature(). Ad esempio, se hai una sola vista, potresti voler nascondere il riquadro di navigazione (Feature.NAV_HIDDEN) per offrire agli utenti più spazio per visualizzare gli elementi.

Il seguente esempio di codice mostra un esempio del selettore di ricerca di un foglio di lavoro che utilizza questa funzionalità:

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

Visualizza il selettore di Google in altre lingue

Specifica la lingua dell'interfaccia utente fornendo le impostazioni internazionali all'istanza PickerBuilder utilizzando il metodo setLocale(locale).

Il seguente esempio di codice mostra come impostare le impostazioni internazionali sul 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 lingue 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