Ambiti di autorizzazione per i componenti aggiuntivi dell'editor

Gli utenti devono autorizzare i componenti aggiuntivi e le 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 le azioni che l'applicazione vuole essere autorizzata a eseguire. Ad esempio, un componente aggiuntivo potrebbe richiedere l'autorizzazione a leggere il messaggio email di un utente o a creare eventi nel suo calendario. Il progetto di script del componente aggiuntivo definisce queste singole autorizzazioni come ambiti OAuth.

Dichiara gli ambiti nel file 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", scritto nel file 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.

Gli ambiti utilizzati da Apps Script per i suoi vari servizi si sovrappongono agli ambiti 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 metodi di servizi Apps Script specifici nella documentazione di riferimento di Apps Script .

Visualizza gli ambiti

Puoi visualizzare gli ambiti attualmente richiesti dal progetto di script procedendo nel seguente modo:

  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 file manifest del progetto, nel campo oauthScopes, ma solo se li hai impostati in modo esplicito.

Imposta ambiti espliciti

Apps Script determina automaticamente gli ambiti necessari a uno script analizzando il codice alla ricerca di chiamate di funzioni che li richiedono. Per la maggior parte degli script è sufficiente e ti fa risparmiare tempo, ma per i componenti aggiuntivi pubblicati dovresti esercitare un controllo più diretto degli ambiti.

Ad esempio, per impostazione predefinita, Apps Script potrebbe assegnare a un progetto di script di un componente aggiuntivo l'ambito molto permissivo https://mail.google.com. Quando un utente autorizza un progetto di script con questo ambito, al progetto viene concesso l'accesso completo al suo account Gmail. 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ù.

Puoi impostare in modo esplicito gli ambiti utilizzati dal progetto di script modificando il relativo 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 utilizzati dal componente aggiuntivo. Determina le modifiche da apportare, ad esempio l'utilizzo di un ambito più ristretto.
  2. Apri il file manifest del componente aggiuntivo.
  3. Individua il campo di primo livello con l'etichetta oauthScopes. Se non è presente, puoi aggiungerlo.

  4. Il oauthScopes campo 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"
   ],
   ...
 }

  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 saperne di più, consulta le guide seguenti:

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 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'el0}elenco completo degli ambiti con restrizioni ambiti prima di tentare di pubblicare. Se il componente aggiuntivo ne utilizza uno, devi rispettare i Requisiti aggiuntivi per gli ambiti API specifici prima della pubblicazione.

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

Ambiti dei componenti aggiuntivi dell'editor

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

Apps Script determina automaticamente gli ambiti richiesti dai servizi che utilizzi man mano che aggiungi codice al progetto di script. Per i componenti aggiuntivi dell'editor, spesso puoi semplicemente fare affidamento su questa raccolta automatica di ambiti anziché determinarli e impostarli in modo esplicito.

Se non imposti gli ambiti in modo esplicito e il componente aggiuntivo dell'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 del file dell'editor impostati su currentonly. Ad esempio, se aggiungi questo commento a un file del progetto di script di un componente aggiuntivo di Fogli, specifichi che il componente aggiuntivo deve avere l'autorizzazione per operare solo sul foglio 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 aperto.