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, la relativa UI presenta una richiesta di autorizzazione per avviare il flusso di autorizzazione.

Durante questo flusso, il prompt comunica all'utente cosa vuole fare l'applicazione con l'autorizzazione. Ad esempio, un componente aggiuntivo potrebbe voler 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 nel manifest è scritto 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.

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.

Visualizza gli ambiti

Per visualizzare gli ambiti attualmente richiesti dal tuo 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.

Impostare ambiti espliciti

Apps Script determina automaticamente gli ambiti necessari a uno script analizzando il codice per individuare 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 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 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 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 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 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 saperne di più, consulta le guide seguenti:

• Verifica del client OAuth per Apps Script
• App non verificate
• Domande frequenti sulla verifica OAuth
• Servizi API di Google: Norme relative ai 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 specificate prima di poter essere pubblicato.

Prima di tentare la pubblicazione, consulta l'elenco completo degli ambiti con limitazioni. Se il tuo componente aggiuntivo ne utilizza uno, devi rispettare i Requisiti aggiuntivi per gli ambiti API specifici prima della pubblicazione.

Nota: evita di utilizzare ambiti con limitazioni nel componente aggiuntivo se puoi. È più facile superare la revisione del componente aggiuntivo per la pubblicazione pubblica se non li utilizzi. Puoi utilizzare gli ambiti con limitazioni liberamente per i componenti aggiuntivi non pubblici.

L'estensione Google Workspace Strumenti per sviluppatori 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 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 fare affidamento su questa raccolta automatica degli ambiti invece di determinarli autonomamente 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 script:

/**
 * @OnlyCurrentDoc
 */

Questo commento indica ad Apps Script di restringere gli ambiti dei file dell'editor che imposta su currentonly. Ad esempio, se aggiungi questo commento a un file di progetto di script del componente aggiuntivo Fogli, specifichi che il componente aggiuntivo ha bisogno solo dell'autorizzazione per operare 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 Fogli deve leggere o scrivere dati in un foglio che l'utente non ha 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.