Ambiti di autorizzazione per i componenti aggiuntivi dell'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, l'interfaccia utente del componente aggiuntivo mostra una richiesta di autorizzazione per avviare il flusso di autorizzazione.

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

Dichiari gli ambiti nel manifest utilizzando stringhe URL. Durante il flusso di autorizzazione, Apps Script presenta all'utente una descrizione dell'ambito leggibile. Ad esempio, il componente aggiuntivo potrebbe utilizzare l'ambito "Leggi il documento corrente", che è 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 consentire al componente aggiuntivo di: visualizzare e gestire i documenti in cui è stata installata questa applicazione.

Nota:l'ambito currentonly è disponibile solo all'interno dei servizi Apps Script. Non sono inclusi i servizi avanzati di Apps Script o le chiamate dirette alle API Google Workspace.

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 Apps Script nella documentazione di riferimento di Apps Script.

Visualizzazione degli ambiti

Per visualizzare gli ambiti attualmente richiesti dal progetto di script, procedi nel seguente modo:

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

Puoi anche visualizzare gli ambiti attuali del progetto di script nel manifest del progetto, nel 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 codice per le chiamate di funzione che li richiedono. Per la maggior parte degli script, questo è sufficiente e ti fa 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 del componente aggiuntivo l'ambito https://mail.google.com molto permissivo 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 del componente aggiuntivo e non di più.

Avviso: utilizza sempre l'ambito meno permissivo possibile. Per proteggere le informazioni degli utenti, i componenti aggiuntivi e le altre applicazioni pubblicate non devono mai richiedere autorizzazioni di ambito superiori a quelle strettamente necessarie. Gli ambiti richiesti dal tuo componente aggiuntivo vengono esaminati durante la procedura di revisione del componente aggiuntivo; 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:

1. Visualizza gli ambiti attualmente utilizzati dal tuo 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 etichettato oauthScopes. Se non è presente, puoi aggiungerlo.

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

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

5. Salva le modifiche apportate al file manifest.

Verifica OAuth

L'utilizzo di determinati ambiti OAuth sensibili potrebbe richiedere che il tuo componente aggiuntivo venga sottoposto a verifica del client OAuth prima di poterlo pubblicare. Per ulteriori informazioni, consulta le seguenti guide:

• Verifica del client OAuth per Apps Script
• App non verificate
• Domande frequenti sulla verifica OAuth
• Servizi API di Google: Norme sui dati utente

Ambiti con restrizioni

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

Prima di tentare la pubblicazione, consulta l'elenco completo degli ambiti con restrizioni. Se il tuo 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 limitazioni nel tuo componente aggiuntivo. In questo modo, sarà più facile superare la revisione del componente aggiuntivo per la pubblicazione pubblica. Puoi utilizzare liberamente gli ambiti con limitazioni per i componenti aggiuntivi non pubblici.

L'estensione Google Workspace Developer Tools per Visual Studio Code fornisce informazioni diagnostiche per tutti gli ambiti, inclusi la descrizione dell'ambito e se è sensibile o con limitazioni.

Ambiti dei componenti aggiuntivi dell'editor

Quando crei un componente aggiuntivo per Editor, gli ambiti richiesti sono determinati dal servizio e dai metodi Apps Script 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 man mano che aggiungi codice al progetto di script. Per i componenti aggiuntivi di Editor, spesso puoi fare affidamento su questa raccolta automatica degli ambiti anziché determinarli manualmente e impostarli in modo esplicito.

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

  /**
   * @OnlyCurrentDoc
   */

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

Nota:l'ambito currentonly è disponibile solo all'interno dei servizi Apps Script. Non sono inclusi i servizi avanzati di Apps Script o le chiamate dirette alle API Google Workspace.