Ambiti di autorizzazione per i componenti aggiuntivi 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 UI 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. 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 dello script del componente aggiuntivo definisce queste singole autorizzazioni come ambiti OAuth.

Dichiari gli ambiti nel file manifest utilizzando stringhe URL. Durante il flusso di autorizzazione, Apps Script presenta all'utente una descrizione dell'ambito leggibile da un essere umano. Ad esempio, il tuo componente aggiuntivo potrebbe utilizzare l'ambito "Leggi 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.

Visualizzazione degli ambiti

Per visualizzare gli ambiti attualmente richiesti dal tuo progetto di script, segui questi passaggi:

  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 esplicitamente.

Impostazione di ambiti espliciti

Apps Script determina automaticamente gli ambiti di cui uno script ha bisogno analizzando il codice per individuare le chiamate alle funzioni 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 sugli ambiti.

Ad esempio, per impostazione predefinita, Apps Script potrebbe assegnare a un progetto di script di componenti aggiuntivi 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 all'account Gmail dell'utente. Per i componenti aggiuntivi pubblicati, devi sostituire questo ambito con un insieme più limitato che soddisfi le esigenze dei componenti aggiuntivi e non più.

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, procedi come segue:

  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 denominato oauthScopes. Se non è presente, puoi aggiungerlo.

  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 utilizzare. Ad esempio, per un componente aggiuntivo di Editor che espande Fogli, potresti avere quanto segue:

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

  5. Salva le modifiche al file manifest.

Verifica OAuth

L'utilizzo di determinati ambiti OAuth sensibili potrebbe richiedere la verifica del client OAuth prima di poter pubblicare il componente aggiuntivo. Per ulteriori informazioni, consulta le seguenti guide:

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 Editor che utilizza uno o più ambiti con limitazioni, il componente aggiuntivo deve essere conforme a tutte le limitazioni specificate prima di poter essere pubblicato.

Consulta l'elenco completo degli ambiti con restrizioni prima di tentare di pubblicare. Se il tuo componente aggiuntivo utilizza una di queste API, devi rispettare i Requisiti aggiuntivi per gli ambiti API specifici prima della pubblicazione.

Ambiti dei componenti aggiuntivi dell'editor

Quando crei un componente aggiuntivo di Editor, gli ambiti richiesti sono determinati dal servizio e dai metodi di 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é determinare autonomamente gli ambiti e impostarli esplicitamente.

Se non imposti gli ambiti in modo esplicito e il 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 dello script di un componente aggiuntivo di Fogli Google, specifichi che il componente aggiuntivo ha bisogno dell'autorizzazione solo per operare sul foglio attualmente aperto e non su altri fogli che l'utente potrebbe avere su Google Drive. Al contrario, non devi utilizzare questo commento se il tuo componente aggiuntivo di Fogli deve leggere o scrivere dati in un foglio che l'utente non ha ancora aperto.