Scegli gli ambiti API di Google Drive

Questo documento contiene informazioni su autorizzazione e autenticazione specifiche dell'API Google Drive. Prima di leggere questo documento, assicurati di leggere le informazioni generali su autenticazione e autorizzazione di Google Workspace all'indirizzo Informazioni su autenticazione e autorizzazione.

Configurare OAuth 2.0 per l'autorizzazione

Per autorizzare la tua app, l'API Google Drive richiede di definire gli ambiti OAuth in due posizioni: la console Google Cloud e la tua app.

Nella console Google Cloud, devi dichiarare gli ambiti di cui la tua app ha bisogno nella configurazione della schermata per il consenso OAuth. Questi sono i livelli di autorizzazione più elevati che la tua app può richiedere. Questa richiesta formale viene inviata a Google e gli ambiti dichiarati sono quelli che Google mostra agli utenti nella schermata per il consenso. Consente all'utente di capire esattamente a quali dati e azioni la tua app richiede l'accesso.

Configura la schermata per il consenso OAuth e scegli gli ambiti per definire quali informazioni vengono visualizzate dagli utenti e dai revisori delle app e registra la tua app in modo da poterla pubblicare in un secondo momento.

Nella tua app, quando inizializzi l'API, devi richiedere esplicitamente gli ambiti specifici di cui hai bisogno per quella sessione. Mentre la console Google Cloud definisce il livello più alto di autorizzazioni che la tua app può richiedere, il codice determina le autorizzazioni effettive per un determinato utente. In questo modo, l'app chiede solo le autorizzazioni necessarie per un'attività specifica.

Puoi dichiarare uno o più ambiti OAuth alla volta nel codice della tua app come array.

Il seguente esempio di codice mostra come dichiarare più ambiti OAuth:

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

Per vedere come vengono dichiarati e utilizzati gli ambiti in un esempio di codice completo, consulta le guide rapide.

Ambiti dell'API Drive

Per definire il livello di accesso concesso alla tua app, devi identificare e dichiarare gli ambiti di autorizzazione. Un ambito di autorizzazione è una stringa URI OAuth 2.0 che contiene il nome dell'app Google Workspace, il tipo di dati a cui accede e il livello di accesso. Gli ambiti sono le richieste dell'app di utilizzare i dati di Google Workspace, inclusi i dati dell'Account Google degli utenti.

Quando l'app viene installata, all'utente viene chiesto di convalidare gli ambiti utilizzati dall'app. In genere, devi scegliere l'ambito più specifico possibile ed evitare di richiedere ambiti che la tua app non richiede. Gli utenti concedono più facilmente l'accesso ad ambiti limitati e descritti chiaramente.

Se possibile, utilizza ambiti non sensibili, in quanto concedono l'accesso per file e restringono l'accesso a funzionalità specifiche necessarie a un'app.

Ambiti non sensibili

I seguenti ambiti dell'API Drive sono consigliati per la maggior parte dei casi d'uso:

Codice ambito Descrizione
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 Visualizzare e gestire i propri dati di configurazione in Google Drive.
https://www.googleapis.com/auth/drive.install Consenti alle app di essere visualizzate sotto forma di opzione nel menu "Apri con…" o "Nuovo".
https://www.googleapis.com/auth/drive.file Creare nuovi file di Drive o modificare quelli esistenti che apri con un'app o che l'utente condivide con un'app utilizzando l'API Google Picker o il selettore di file dell'app.

Ambiti sensibili

Codice ambito Descrizione
https://www.googleapis.com/auth/drive.apps.readonly Visualizza le app autorizzate ad accedere a Drive.

Ambiti con restrizioni

Codice ambito Descrizione
https://www.googleapis.com/auth/drive Visualizza e gestisci tutti i tuoi file di Drive.
https://www.googleapis.com/auth/drive.readonly Visualizzare e scaricare tutti i tuoi file di Drive.
https://www.googleapis.com/auth/drive.activity Visualizza e aggiungi ai record delle attività dei file presenti nel tuo Drive.
https://www.googleapis.com/auth/drive.activity.readonly Visualizza il record delle attività dei file presenti in Drive.
https://www.googleapis.com/auth/drive.meet.readonly Visualizzare i file di Drive creati o modificati da Google Meet.
https://www.googleapis.com/auth/drive.metadata Visualizzare e gestire i metadati dei file in Drive.
https://www.googleapis.com/auth/drive.metadata.readonly Visualizzare i metadati dei file in Drive.
https://www.googleapis.com/auth/drive.scripts Modificare il comportamento degli script di Google Apps Script.

Gli ambiti nelle tabelle precedenti indicano la loro sensibilità, in base alle seguenti definizioni:

Se la tua app richiede l'accesso ad altre API di Google, puoi aggiungere anche questi ambiti. Per saperne di più sugli ambiti delle API di Google, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Per saperne di più sugli ambiti OAuth 2.0 specifici, consulta Ambiti OAuth 2.0 per le API di Google.

Qualifiche per gli ambiti con restrizioni

Solo determinati tipi di applicazioni sono autorizzati a utilizzare ambiti con limitazioni per Google Drive. Per essere idonea, la tua app deve rientrare in una delle seguenti categorie:

  1. Backup e sincronizzazione: app specifiche per piattaforma e web che forniscono la sincronizzazione locale o il backup automatico dei file di Drive degli utenti.

  2. Produttività e istruzione: app con un'interfaccia utente principale che potrebbe comportare l'interazione con file, metadati o autorizzazioni di Drive. Queste app includono app per la gestione delle attività, la creazione di note, le comunicazioni dei gruppi di lavoro e la collaborazione in classe.

  3. Report e sicurezza: app che forniscono informazioni agli utenti o ai clienti su come vengono condivisi o aperti i file.

Per continuare a utilizzare gli ambiti con limitazioni, devi preparare la tua app per la verifica degli ambiti con limitazioni.

Eseguire la migrazione di un'app esistente dagli ambiti con restrizioni

Se la tua app Drive utilizza ambiti con limitazioni, ti consigliamo di eseguire la migrazione a un ambito API Drive non sensibile. L'utilizzo di ambiti non sensibili, come drive.file, concede un accesso limitato e per file a funzionalità specifiche necessarie a un'app.

Molte app possono passare all'accesso per file senza alcuna modifica.

Se utilizzi il tuo selettore di file, ti consigliamo di passare all' API Google Picker, che supporta completamente diversi ambiti.

Vantaggi dell'ambito del file di Drive

L'utilizzo dell'ambito OAuth drive.file in combinazione con l'API Google Picker ottimizza sia l'esperienza utente sia la sicurezza della tua app.

L'ambito OAuth drive.file consente agli utenti di scegliere quali file vogliono condividere con la tua app. In questo modo hanno maggiore controllo e sicurezza che l'accesso della tua app ai loro file sia limitato e più sicuro. Al contrario, richiedere un accesso ampio a tutti i file di Drive potrebbe scoraggiare gli utenti dall'interazione con la tua app.

Di seguito sono riportati alcuni motivi per cui dovresti utilizzare l'ambito drive.file:

  • Usabilità: l'ambito drive.file funziona con tutte le risorse REST dell'API Drive, il che significa che puoi utilizzarlo allo stesso modo in cui utilizzi ambiti OAuth più ampi.

  • Funzionalità: l'API Google Picker fornisce un'interfaccia simile a quella dell'interfaccia utente di Drive. Sono incluse diverse visualizzazioni che mostrano anteprime e miniature dei file di Drive e una finestra modale in linea in modo che gli utenti non escano mai dall'app principale.

  • Comodità: le app possono applicare filtri per determinati tipi di file di Drive (come Documenti, Fogli e foto Google) quando utilizzano un filtro sui file di Google Picker.

  • Verifica semplice: poiché drive.file non è sensibile, consente una procedura di verifica più semplice.

Archiviare in modo sicuro i token di aggiornamento

Per accedere ai dati privati utilizzando l'API Drive, la tua app deve ottenere un token di accesso che conceda l'accesso a questa API. Un singolo token di accesso può concedere vari livelli di accesso a più API, regolati dagli ambiti che richiedi.

Poiché i token di accesso hanno una durata limitata, devi utilizzare i token di aggiornamento per l'accesso a lungo termine all'API Drive. Un token di aggiornamento consente alla tua app di richiedere nuovi token di accesso.

Salva i token di aggiornamento in uno spazio di archiviazione sicuro a lungo termine e continua a utilizzarli finché rimangono validi.

Per saperne di più, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.