Questa pagina è stata tradotta dall'API Cloud Translation.

Mirini con ingrandimento

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'UI del componente aggiuntivo presenta una richiesta di autorizzazione per avviare il flusso di autorizzazione.

Durante questo flusso, la richiesta indica all'utente cosa deve fare 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 tuo manifest utilizzando stringhe di URL. Durante il flusso di autorizzazione, Apps Script presenta all'utente una descrizione leggibile dell'ambito. Ad esempio, il componente aggiuntivo di Google Workspace potrebbe utilizzare l'ambito "Leggi il messaggio corrente", scritto nel manifest come https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Durante il flusso di autorizzazione, un componente aggiuntivo con questo ambito chiede all'utente di consentire il componente aggiuntivo per la visualizzazione dei messaggi email quando il componente è in esecuzione.

Ambiti di visualizzazione

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

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

Puoi anche visualizzare gli ambiti correnti del progetto di script nel manifest del progetto, sotto il campo oauthScopes, ma solo se hai impostato tali ambiti esplicitamente.

Impostazione di ambiti espliciti

Apps Script determina automaticamente gli ambiti di cui uno script ha bisogno, eseguendo la scansione del suo codice per individuare le chiamate delle funzioni che lo richiedono. Per la maggior parte degli script è sufficiente e 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 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 solo.

Puoi impostare esplicitamente gli ambiti utilizzati dal tuo 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, segui questi passaggi:

Visualizzare gli ambiti attualmente utilizzati dal componente aggiuntivo. Determina quali modifiche apportare, ad esempio utilizzando un ambito più ristretto.
Apri il file manifest del componente aggiuntivo.
Individua il campo di primo livello con l'etichetta oauthScopes. Se non è presente, puoi aggiungerla.
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 di Google Workspace che estende Gmail, potresti avere quanto segue:
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
Salva le modifiche al file manifest.

Verifica OAuth

L'utilizzo di determinati ambiti OAuth sensibili potrebbe richiedere il completamento della verifica client OAuth da parte del componente aggiuntivo, prima di poter essere pubblicato. Per saperne di più, consulta le seguenti guide:

Ambiti limitati

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

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

Ambiti del calendario

Di seguito sono riportati gli ambiti più usati per i componenti aggiuntivi di Google Workspace che estendono Google Calendar.

Ambito
Accedi ai metadati degli eventi	`https://www.googleapis.com/auth/calendar.addons.execute` Obbligatorio se il componente aggiuntivo accede ai metadati degli eventi di Calendar. Consente al componente aggiuntivo di accedere ai metadati degli eventi.
Leggere i dati sugli eventi generati dagli utenti	`https://www.googleapis.com/auth/calendar.addons.current.event.read` Obbligatorio se il componente aggiuntivo deve leggere i dati degli eventi generati dagli utenti. Consente al componente aggiuntivo di accedere ai dati sugli eventi generati dagli utenti. Questi dati sono disponibili solo se il campo manifest di `addOns.calendar.eventAccess` è impostato su `READ` o `READ_WRITE`.
Scrivere dati sugli eventi generati dagli utenti	`https://www.googleapis.com/auth/calendar.addons.current.event.write` Obbligatorio se il componente aggiuntivo deve scrivere dati sugli eventi generati dagli utenti. Consente al componente aggiuntivo di modificare i dati degli eventi generati dagli utenti. Questi dati sono disponibili solo se il campo manifest di `addOns.calendar.eventAccess` è impostato su `WRITE` o `READ_WRITE`.

Ambiti Drive

Di seguito sono riportati gli ambiti più usati per i componenti aggiuntivi di Google Workspace che estendono Google Drive.

Ambito

Leggi i metadati degli elementi selezionati

Ambito
Leggi i metadati degli elementi selezionati	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` Obbligatorio se il componente aggiuntivo implementa un'interfaccia contestuale attivata quando l'utente seleziona elementi in Drive. Consente al componente aggiuntivo di leggere metadati limitati relativi agli elementi selezionati da un utente su Google Drive. I metadati sono limitati all'ID, al titolo, al tipo MIME, all'URL dell'icona dell'elemento e al fatto che il componente aggiuntivo abbia l'autorizzazione ad accedere all'elemento.
Accesso per file	`https://www.googleapis.com/auth/drive.file` Consigliato se il componente aggiuntivo deve accedere ai singoli file di Drive. Concede l'accesso per file ai file creati o aperti dall'app, utilizzando il servizio avanzato di Drive di Apps Script. Tuttavia, non consente l'utilizzo di azioni simili mediante il servizio Drive di base. L'autorizzazione dei file viene concessa per file e viene revocata quando l'utente annulla l'autorizzazione dell'app. Vedi l' esempio di richiesta di accesso ai file per i file selezionati.

https://www.googleapis.com/auth/drive.addons.metadata.readonly

Obbligatorio se il componente aggiuntivo implementa un'interfaccia contestuale attivata quando l'utente seleziona elementi in Drive. Consente al componente aggiuntivo di leggere metadati limitati relativi agli elementi selezionati da un utente su Google Drive. I metadati sono limitati all'ID, al titolo, al tipo MIME, all'URL dell'icona dell'elemento e al fatto che il componente aggiuntivo abbia l'autorizzazione ad accedere all'elemento.

Accesso per file

https://www.googleapis.com/auth/drive.file

Consigliato se il componente aggiuntivo deve accedere ai singoli file di Drive. Concede l'accesso per file ai file creati o aperti dall'app, utilizzando il servizio avanzato di Drive di Apps Script. Tuttavia, non consente l'utilizzo di azioni simili mediante il servizio Drive di base. L'autorizzazione dei file viene concessa per file e viene revocata quando l'utente annulla l'autorizzazione dell'app.

Vedi l' esempio di richiesta di accesso ai file per i file selezionati.

Ambiti dei componenti aggiuntivi di Gmail

Esistono alcuni ambiti creati specificamente per i componenti aggiuntivi di Google Workspace al fine di proteggere i dati Gmail degli utenti. Devi aggiungere questi ambiti in modo esplicito al manifest del componente aggiuntivo, insieme a tutti gli altri necessari per il codice del componente aggiuntivo.

Di seguito sono riportati gli ambiti più usati per i componenti aggiuntivi di Google Workspace che estendono Gmail; quelli con l'etichetta Obbligatorio devono essere aggiunti al manifest del componente aggiuntivo di Google Workspace se il componente aggiuntivo estende Gmail.

Assicurati inoltre di sostituire l'ambito https://mail.google.com molto ampio nel componente aggiuntivo con uno più ristretto di ambiti che consentono le interazioni necessarie e il componente aggiuntivo.

Ambito
Creare nuove bozze	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obbligatorio se il componente aggiuntivo utilizza i trigger di azione per la scrittura. Consente al componente aggiuntivo di creare temporaneamente nuove bozze di messaggi e risposte. Per maggiori dettagli, consulta Scrivere bozze dei messaggi; questo ambito è spesso utilizzato anche con le azioni di scrittura. Richiede un token di accesso.
Lettura dei metadati dei messaggi aperti	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Concede l'accesso temporaneo ai metadati del messaggio aperto (come l'oggetto o i destinatari). Non consente la lettura del contenuto dei messaggi e richiede un token di accesso. Obbligatorio se il componente aggiuntivo utilizza metadati nei trigger di azione di scrittura. Per le azioni di scrittura, questo ambito è obbligatorio se un trigger di scrittura richiede l'accesso ai metadati. In pratica, questo ambito consente a un utente di scrivere elenchi di destinatari di accesso (a:, cc: e cc:) di una bozza di email di risposta.
Leggere i contenuti dei messaggi aperti	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Concede l'accesso ai contenuti del messaggio aperto al momento dell'interazione da parte dell'utente, ad esempio quando viene selezionata una voce di menu di un componente aggiuntivo. Richiede un token di accesso.
Lettura dei contenuti dei thread aperti	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` Concede l'accesso temporaneo ai metadati e ai contenuti del messaggio aperto. Concede inoltre l'accesso ai contenuti di altri messaggi nel thread aperto. Richiede un token di accesso.
Leggere i contenuti e i metadati di un messaggio	`https://www.googleapis.com/auth/gmail.readonly` Leggi i metadati e i contenuti delle email, incluso il messaggio aperto. Obbligatorio se devi leggere informazioni su altri messaggi, ad esempio quando esegui una query di ricerca o leggi un intero thread di posta. Avviso: questo è un ambito limitato e molto ampio. Utilizzalo solo se assolutamente necessario.

Token di accesso

Per proteggere i dati utente, gli ambiti Gmail utilizzati nei componenti aggiuntivi di Google Workspace consentono l'accesso temporaneo solo ai dati utente. Per abilitare l'accesso temporaneo, devi chiamare la funzione GmailApp.setCurrentMessageAccessToken(accessToken) utilizzando un token di accesso come argomento. Devi ottenere un token di accesso da un oggetto evento di azione.

Di seguito è riportato un esempio di impostazione di un token di accesso per consentire l'accesso ai metadati di un messaggio. L'unico ambito necessario per questo esempio è https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Ambiti dell'editor

Di seguito sono riportati gli ambiti più usati per i componenti aggiuntivi di Google Workspace che estendono i file di Documenti, Fogli e Presentazioni.

Ambito
Accesso al file Documenti corrente	`https://www.googleapis.com/auth/documents.currentonly` Obbligatorio se il componente aggiuntivo accede all'API Apps Script Docs. Concede l'accesso temporaneo ai contenuti del documento aperto.
Accesso al file Fogli Google attuale	`https://www.googleapis.com/auth/spreadsheets.currentonly` Obbligatorio se il componente aggiuntivo accede all'API Apps Script Sheets. Concede l'accesso temporaneo ai contenuti del foglio di lavoro aperto.
Accesso al file di Presentazioni corrente	`https://www.googleapis.com/auth/presentations.currentonly` Obbligatorio se il componente aggiuntivo accede all'API Apps Script Slides. Concede l'accesso temporaneo ai contenuti della presentazione aperta.
Accesso per file	`https://www.googleapis.com/auth/drive.file` Obbligatorio per l'utilizzo di `onFileScopeGrantedTrigger` e se il componente aggiuntivo accede all'API di Documenti, Fogli, Presentazioni o Drive. Concede l'accesso per file ai file creati o aperti dall'app, utilizzando il servizio avanzato di Drive di Apps Script. Tuttavia, non consente l'utilizzo di azioni simili mediante il servizio Drive di base. L'autorizzazione dei file viene concessa per file e viene revocata quando l'utente annulla l'autorizzazione dell'app.

Altri ambiti

Il tuo componente aggiuntivo potrebbe richiedere ambiti aggiuntivi se utilizza altri servizi di Apps Script. Nella maggior parte dei casi, puoi consentire ad Apps Script di rilevare questi ambiti e aggiornare automaticamente il manifest. Quando modifichi l'elenco degli ambiti del file manifest, non rimuovere alcun ambito, a meno che non li sostituisci con un'alternativa più appropriata, ad esempio un ambito più ristretto.

Come riferimento, ecco un elenco degli ambiti Apps Script che vengono spesso utilizzati in combinazione con i componenti aggiuntivi di Google Workspace:

Ambito
Lettura dell'indirizzo email dell'utente	`https://www.googleapis.com/auth/userinfo.email` Consente al progetto di leggere l'indirizzo email dell'utente corrente.
Consenti chiamate ai servizi esterni	`https://www.googleapis.com/auth/script.external_request` Consente al progetto di effettuare richieste `UrlFetch`. Questa operazione è necessaria anche se il progetto utilizza la libreria OAuth2 per Apps Script.
Lettura delle impostazioni internazionali e del fuso orario dell'utente	`https://www.googleapis.com/auth/script.locale` Consente al progetto di apprendere le impostazioni internazionali e il fuso orario dell'utente corrente. Per informazioni dettagliate, consulta la sezione Accesso alle impostazioni internazionali e al fuso orario dell'utente.
Creazione di trigger	`https://www.googleapis.com/auth/script.scriptapp` Consente al progetto di creare trigger.
Visualizza l'anteprima dei link di terze parti	`https://www.googleapis.com/auth/workspace.linkpreview` Obbligatorio se l'anteprima del componente aggiuntivo rimanda da un servizio di terze parti. Consente al progetto di vedere un link all'interno di un'applicazione Google Workspace durante l'interazione dell'utente. Per scoprire di più, consulta la pagina Visualizzare l'anteprima dei link con smart chip.