Scegli gli ambiti API di Google Drive

Questo documento contiene informazioni su autorizzazione e autenticazione specifiche per l'API Google Drive. Prima di leggere questo documento, assicurati di leggere le informazioni generali sull'autenticazione e l'autorizzazione di Google Workspace in 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. Si tratta di una richiesta formale a Google e gli ambiti dichiarati sono quelli che Google mostra agli utenti nella schermata per il consenso. Consente all'utente di comprendere esattamente a quali dati e azioni la tua app sta richiedendo l'accesso.

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

Nell'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 di autorizzazioni più elevato 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:

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

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

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

Per scoprire 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 della tua app di utilizzare i dati di Google Workspace, inclusi i dati dell'Account Google degli utenti.

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

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

Ambiti non sensibili

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

Ambiti sensibili

Ambiti con restrizioni

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

• Non sensibili: questi ambiti forniscono l'ambito di autorizzazione più piccolo e richiedono solo la verifica di base dell'app OAuth. Per ulteriori informazioni consulta i Requisiti di verifica.

• Sensibili: questi ambiti forniscono l'accesso a dati utente di Google specifici che gli utenti autorizzano per la tua app. Richiedono una verifica aggiuntiva dell'app OAuth Verification. Per ulteriori informazioni, consulta Requisiti per gli ambiti sensibili e con restrizioni.

• Con restrizioni: questi ambiti forniscono un ampio accesso ai dati utente di Google e richiedono la verifica dell'app OAuth con ambiti con restrizioni. Per ulteriori informazioni, consulta le Norme relative ai dati utente dei servizi API di Google e i Requisiti aggiuntivi per ambiti API specifici. Consulta anche i Termini di servizio di Google Drive.

  Se memorizzi (o trasmetti) dati con ambiti con restrizioni sui server, devi sottoporti a una valutazione della sicurezza.

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 tipi di applicazioni specifici sono autorizzati a utilizzare ambiti con restrizioni per Google Drive. Per essere idonea, la tua app deve rientrare in una delle seguenti categorie:

1. Backup e sincronizzazione: app web e specifiche della piattaforma 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 presa di appunti, le comunicazioni di gruppo 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 a cui si accede ai file.

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

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

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

Molte app possono passare all'accesso per file senza apportare modifiche.

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

Vantaggi dell'ambito dei 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 i file che vogliono condividere con la tua app. In questo modo, hanno un maggiore controllo e la certezza che l'accesso della tua app ai loro file sia limitato e più sicuro. Al contrario, richiedere un ampio accesso a tutti i file di Drive potrebbe scoraggiare gli utenti dall'interagire 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 nello stesso modo in cui utilizzi ambiti OAuth più ampi.

• Funzionalità: l'API Google Picker fornisce un'interfaccia simile all' 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 debbano mai uscire dall'app principale.

• Praticità: le app possono applicare filtri per determinati tipi di file di Drive (ad esempio 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 diversi 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.

Argomenti correlati

• Per una panoramica dell'autenticazione e dell'autorizzazione in Google Workspace, consulta Informazioni su autenticazione e & autorizzazione.
• Per una panoramica dell'autenticazione e dell'autorizzazione in Google Cloud, consulta Panoramica dell'autenticazione.
• Per saperne di più sui service account, consulta Service accounts.
• Per assistenza nella risoluzione dei problemi, consulta Risolvere gli errori.