Ambiti di autorizzazione per i componenti aggiuntivi di Editor

Gli utenti devono autorizzare i componenti aggiuntivi e altre applicazioni che accedono ai loro dati o agiscono per loro conto. Quando un utente esegue un componente aggiuntivo per la prima volta, la relativa UI presenta una richiesta di autorizzazione per avviare il flusso di autorizzazione.

Durante questo flusso, la richiesta indica all'utente cosa vuole fare l'applicazione. Ad esempio, un componente aggiuntivo potrebbe richiedere l'autorizzazione per leggere i messaggi email di un utente o creare eventi nel suo calendario. Il progetto di script del componente aggiuntivo definisce queste singole autorizzazioni come ambiti OAuth.

Gli ambiti vengono dichiarati nel manifest mediante stringhe URL. Durante il flusso di autorizzazione, Apps Script presenta all'utente una descrizione leggibile dell'ambito. Ad esempio, il componente aggiuntivo potrebbe utilizzare l'ambito "Leggi il documento corrente", scritto nel manifest come https://www.googleapis.com/auth/documents.currentonly. Durante il flusso di autorizzazione, un componente aggiuntivo con questo ambito chiede all'utente di consentirlo: Visualizzare e gestire i documenti in cui è stata installata questa applicazione.

Nota: gli ambiti utilizzati da Apps Script per i suoi vari servizi si sovrappongono a quelli utilizzati dall'API correlata. Ad esempio, il servizio Calendar di Apps Script utilizza molti degli stessi ambiti dell'API Calendar. Puoi cercare gli ambiti richiesti da determinati metodi di servizio di Apps Script nella documentazione di riferimento di Apps Script.

Ambiti di visualizzazione

Per vedere gli ambiti attualmente richiesti dal progetto di script:

1. Apri il progetto di script.
2. A sinistra, fai clic su Panoramica .
3. Visualizza gli ambiti in "Ambiti OAuth del progetto".

Puoi anche visualizzare gli ambiti attuali del progetto di script nel manifest del progetto, sotto il campo oauthScopes, ma solo se li hai impostati in modo esplicito.

Impostazione di ambiti espliciti

Apps Script determina automaticamente gli ambiti necessari a uno script analizzando il suo codice per individuare le chiamate alle funzioni che li richiedono. Per la maggior parte degli script questo è sufficiente e consente di risparmiare tempo, ma per i componenti aggiuntivi pubblicati devi esercitare un controllo più diretto degli ambiti.

Ad esempio, Apps Script potrebbe assegnare a un progetto di script per componenti aggiuntivi l'ambito molto permissivo https://mail.google.com per impostazione predefinita. Quando un utente autorizza un progetto di script con questo ambito, al progetto viene concesso l'accesso completo all'account Gmail dell'utente. Per i componenti aggiuntivi pubblicati, devi sostituire questo ambito con un insieme più limitato che copra le esigenze dei componenti aggiuntivi e non solo.

Attenzione: utilizza sempre l'ambito meno permissivo possibile. Per proteggere le informazioni degli utenti, i componenti aggiuntivi e le altre applicazioni pubblicate non dovrebbero mai chiedere più autorizzazioni di ambito di cui hanno assolutamente bisogno. Gli ambiti richiesti dal componente aggiuntivo vengono esaminati durante la procedura di revisione dei componenti aggiuntivi della pubblicazione. Se il componente aggiuntivo utilizza ambiti troppo ampi, non può superare la revisione.

Puoi impostare esplicitamente gli ambiti utilizzati dal progetto di script modificando il file manifest. Il campo manifest oauthScopes è un array di tutti gli ambiti utilizzati dal componente aggiuntivo. Per impostare gli ambiti del progetto, segui questi passaggi:

1. Visualizza gli ambiti attualmente utilizzati dal componente aggiuntivo. Determina quali modifiche devono essere apportate, ad esempio l'utilizzo di un ambito più ristretto.
2. Apri il file manifest del componente aggiuntivo.
3. Individua il campo di primo livello denominato oauthScopes. Se non è presente, puoi aggiungerla.

4. Il campo oauthScopes specifica un array di stringhe. Per impostare gli ambiti utilizzati dal progetto, sostituisci i contenuti di questo array con gli ambiti che vuoi che utilizzi. Ad esempio, per un componente aggiuntivo dell'editor che estende Fogli potresti avere quanto segue:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/script.container.ui",
       "https://www.googleapis.com/auth/spreadsheets.currentonly"
     ],
     ...
   }
   

5. Salva le modifiche apportate al file manifest.

Verifica OAuth

L'utilizzo di determinati ambiti OAuth sensibili potrebbe richiedere che il componente aggiuntivo venga sottoposto alla verifica del client OAuth prima di poter essere pubblicato. Per ulteriori informazioni, consulta le seguenti guide:

• Verifica del client OAuth per Apps Script
• App non verificate
• Domande frequenti sulla verifica OAuth
• Servizio API di Google: norme relative ai dati utente

Ambiti con restrizioni

Alcuni ambiti sono limitati e soggetti a regole aggiuntive che aiutano a proteggere i dati utente. Se intendi pubblicare un componente aggiuntivo di Gmail o dell'Editor che utilizza uno o più ambiti con restrizioni, il componente aggiuntivo deve rispettare tutte le restrizioni specificate prima di poter essere pubblicato.

Esamina l'elenco completo degli ambiti con restrizioni prima di provare a pubblicare. Se il componente aggiuntivo ne utilizza uno, devi rispettare i Requisiti aggiuntivi per gli ambiti API specifici prima della pubblicazione.

Nota: se possibile, evita di utilizzare ambiti con restrizioni nel componente aggiuntivo: è più semplice superare la revisione dei componenti aggiuntivi per la pubblicazione pubblica se non li utilizzi. Puoi utilizzare liberamente ambiti con restrizioni per i componenti aggiuntivi non pubblici.

Ambiti dei componenti aggiuntivi di Editor

Quando crei un componente aggiuntivo dell'editor, gli ambiti richiesti sono determinati dal servizio Apps Script e dai metodi utilizzati dal codice del componente aggiuntivo. Ad esempio, un componente aggiuntivo di Fogli potrebbe richiedere l'ambito https://www.googleapis.com/auth/spreadsheets.readonly per leggere informazioni da diversi Fogli Google.

Apps Script determina automaticamente gli ambiti richiesti dai servizi che utilizzi quando aggiungi codice al progetto di script. Per i componenti aggiuntivi di Editor, spesso è possibile affidarsi a questa raccolta di ambito automatico invece di determinare autonomamente gli ambiti e di impostarli in modo esplicito.

Se non imposti gli ambiti in modo esplicito e il componente aggiuntivo Editor legge o scrive sempre e solo nel file aperto dell'editor, aggiungi il seguente commento a uno dei file di progetto di script:

  /**
   * @OnlyCurrentDoc
   */

Questo commento indica ad Apps Script di restringere gli ambiti dei file dell'editor impostati a currentonly. Ad esempio, se aggiungi questo commento a un file di progetto di script per componenti aggiuntivi di Fogli Google, specifichi che il componente aggiuntivo deve avere l'autorizzazione per funzionare solo sul foglio attualmente aperto e non su altri Fogli Google che l'utente potrebbe avere su Google Drive. e non se il componente aggiuntivo di Fogli deve leggere o scrivere dati in un foglio che l'utente non ha aperto attualmente.