Panoramica delle app web

L'API Google Picker è un'API JavaScript che puoi utilizzare nelle tue app web per consentire agli utenti di selezionare o caricare file di Google Drive. 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 propri file.

Il selettore Google funge da finestra di dialogo "Apri file" per le informazioni archiviate su Drive e offre diverse funzionalità:

• Un aspetto simile all'interfaccia utente di Google Drive.
• Diverse visualizzazioni che mostrano anteprime e miniature dei file di Drive.
• Una finestra modale in linea, in modo che gli utenti non escano mai dall'app principale.

Tieni presente che Google Picker non consente agli utenti di organizzare, spostare o copiare i file da una cartella all'altra. Per gestire i file, devi utilizzare l' API Google Drive o la UI di Drive.

Prerequisiti

Le app che utilizzano il selettore Google 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 il tuo ambiente.

Abilita l'API

• 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 a dati disponibili pubblicamente, come 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:

1. Nella console Google Cloud, vai a Menu 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 content_copy 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.
   • 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.

Autorizzare le credenziali per un'app web

Importante:la tua app deve inviare un token di accesso OAuth 2.0 con visualizzazioni che accedono ai dati privati dell'utente durante la creazione di un oggetto Picker. Per richiedere un token di accesso, consulta l'articolo Utilizzare OAuth 2.0 per accedere alle API di Google.

Gestire il selettore Google

La parte restante di questa guida spiega come caricare e visualizzare il selettore Google da un'app web, nonché come implementare il callback. Per visualizzare l'esempio completo, consulta la pagina Esempio di codice per le 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 il 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 della tua 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 necessario. Per maggiori informazioni, consulta 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 della tua app web. Per maggiori informazioni, consulta la sezione Utilizzare il modello di token.

La funzione onApiLoad carica le librerie di Google Picker. La funzione di callback onPickerApiLoad viene chiamata dopo il caricamento 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 un ticket di assistenza.

Visualizzare il selettore Google

La funzione createPicker garantisce che il caricamento dell'API Google Picker sia completato e che venga creato un token OAuth 2.0. Utilizza il metodo PickerBuilder.setAppId per impostare l'ID 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 oggetto Picker utilizzando PickerBuilder. 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 un View alla volta. Specifica almeno una visualizzazione, ViewId (google.picker.ViewId.*) o creando un'istanza di un DocsView per un maggiore controllo sul rendering della visualizzazione.

Se vengono aggiunte più viste al selettore Google, gli utenti possono passare da una vista 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, consulta ViewId nella documentazione di riferimento di Google Picker. Per ottenere il token per una di queste visualizzazioni, utilizza l'ambito https://www.googleapis.com/auth/drive.file.

Implementare il callback del selettore Google

Un callback di Google Picker può essere utilizzato per reagire alle interazioni dell'utente in Google Picker, ad esempio la selezione di un file o la pressione di Annulla. L'interfaccia ResponseObject 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 formato JSON. Questo oggetto contiene un Action che l'utente esegue con il selettore Google (google.picker.Response.ACTION). Se l'utente seleziona un elemento, viene compilato anche l'array google.picker.Response.DOCUMENTS. In questo esempio, il google.picker.Document.URL viene mostrato nella pagina principale. Per informazioni dettagliate sui campi dei dati, consulta l'interfaccia ResponseObject.

Filtrare tipi di file specifici

Utilizza un ViewGroup come modo per filtrare elementi specifici. Il seguente esempio di codice mostra come la visualizzazione secondaria "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.

Modificare l'aspetto del selettore Google

Puoi utilizzare l'oggetto Feature per attivare o disattivare le funzionalità per varie visualizzazioni. Per perfezionare l'aspetto della finestra del selettore Google, utilizza il metodo PickerBuilder.enableFeature o PickerBuilder.disableFeature. Ad esempio, se hai una sola vista, 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 del 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();