Ambiti

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 tuo componente aggiuntivo 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 al componente aggiuntivo di: Visualizzare i messaggi email quando il componente aggiuntivo è in esecuzione.

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:

Apri il progetto di script.
A sinistra, fai clic su Panoramica .
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ù.

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:

Visualizza gli ambiti utilizzati dal componente aggiuntivo. Determina le modifiche da apportare, ad esempio l'utilizzo di un ambito più ristretto.
Apri il file manifest del componente aggiuntivo.
Individua il campo di primo livello etichettato oauthScopes. Se non è presente, puoi aggiungerlo.
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 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 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 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.

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.

Scegliere gli ambiti per i componenti aggiuntivi di Google Workspace

Le sezioni seguenti forniscono gli ambiti di uso comune per i componenti aggiuntivi di Google Workspace.

Ambiti dell'editor

I seguenti ambiti utilizzati di frequente per i componenti aggiuntivi di Google Workspace estendono Documenti Google, Fogli Google e Presentazioni Google.

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.

Ambito
Accesso ai file di Documenti corrente	`https://www.googleapis.com/auth/documents.currentonly` Obbligatorio se il componente aggiuntivo accede all'API Google Apps Script Docs. Concede l'accesso temporaneo ai contenuti del documento aperto.
Accesso al file Fogli corrente	`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 attuale	`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 del componente aggiuntivo `onFileScopeGrantedTrigger` e se il componente aggiuntivo accede all'API Documenti, Fogli, Presentazioni o Drive. Concede l'accesso per file ai file creati o aperti dall'app utilizzando il servizio avanzato di Google Drive di Apps Script. Ciò non consente azioni simili utilizzando il servizio Drive di base. L'autorizzazione dei file viene concessa per singolo file e viene revocata quando l'utente annulla l'autorizzazione dell'app.

Gmail

Esistono ambiti creati appositamente per i componenti aggiuntivi di Google Workspace per proteggere i dati Gmail degli utenti. Aggiungi questi ambiti in modo esplicito al manifest del componente aggiuntivo, insieme a tutti gli altri necessari.

La tabella seguente elenca gli ambiti utilizzati di frequente per i componenti aggiuntivi di Google Workspace che estendono Gmail. Se il tuo componente aggiuntivo estende Gmail, devi aggiungere tutti gli ambiti etichettati come Obbligatori al manifest del componente aggiuntivo Google Workspace.

Sostituisci l'ambito https://mail.google.com ampio con un insieme più ristretto di ambiti che consentono le interazioni necessarie al tuo componente aggiuntivo.

Ambito
Crea nuove bozze	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obbligatorio se il componente aggiuntivo utilizza trigger di azioni di composizione. Consente al componente aggiuntivo di creare temporaneamente nuove bozze di messaggi e risposte. Per i dettagli, consulta Composizione di bozze di messaggi; questo ambito viene spesso utilizzato con [azioni di composizione] (/workspace/add-ons/gmail/extending-compose-ui). Richiede un token di accesso.
Leggi i metadati dei messaggi aperti	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Concede l'accesso temporaneo ai metadati del messaggio aperto (ad esempio oggetto o destinatari). Non consente la lettura dei contenuti dei messaggi e richiede un token di accesso. Obbligatorio se il componente aggiuntivo utilizza i metadati nei trigger dell'azione di composizione. Per le azioni di composizione, questo ambito è necessario se un trigger di composizione deve accedere ai metadati. In pratica, questo ambito consente a un trigger di composizione di accedere agli elenchi dei destinatari (A:, Cc: e Ccn:) di una bozza di email di risposta.
Leggere i contenuti dei messaggi aperti	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Consente l'accesso ai contenuti del messaggio aperto in seguito all'interazione dell'utente, ad esempio quando seleziona una voce di menu del componente aggiuntivo. Richiede un token di accesso.
Leggere i contenuti del thread aperto	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` Concede l'accesso temporaneo ai metadati e ai contenuti del messaggio aperto. Consente inoltre l'accesso ai contenuti di altri messaggi nel thread aperto. Richiede un token di accesso.
Leggere i contenuti e i metadati di qualsiasi messaggio	`https://www.googleapis.com/auth/gmail.readonly` Leggere i metadati e i contenuti di qualsiasi email, incluso il messaggio aperto. Obbligatorio se devi leggere informazioni su altri messaggi, ad esempio quando esegui una query di ricerca o leggi un'intera thread di email. Avviso: questo è un ambito molto ampio con restrizioni. Utilizzalo solo se è assolutamente necessario.

Ambiti di Google Calendar

La tabella seguente elenca gli ambiti utilizzati di frequente per i componenti aggiuntivi di Google Workspace che estendono Google Calendar.

Ambito
Accedere 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.
Leggi i dati degli 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 degli eventi generati dagli utenti. Questi dati sono disponibili solo se il campo manifest `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 degli 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 `addOns.calendar.eventAccess` è impostato su `WRITE` o `READ_WRITE`.

Ambiti di Google Chat

Per chiamare l'API Google Chat, esegui l'autenticazione come utente Google Chat o come app Google Chat. Ogni tipo di autenticazione richiede ambiti diversi e non tutti i metodi dell'API Chat supportano l'autenticazione dell'app.

Per scoprire di più sugli ambiti di Chat e sui tipi di autenticazione, vedi la panoramica di autenticazione e autorizzazione dell'API Chat .

La tabella seguente mostra i metodi e gli ambiti dell'API Chat utilizzati di frequente in base ai tipi di autenticazione supportati:

Metodo	Autenticazione dell'app supportata	Ambiti di autorizzazione supportati
Invia un messaggio		Con l'autenticazione utente: `chat.messages.create` `chat.messages` `chat.import` Con l'autenticazione app: `chat.bot`
Creare uno spazio		Con l'autenticazione utente: `chat.spaces.create` `chat.spaces` `chat.import` Con l'autenticazione delle app e l'approvazione dell'amministratore (disponibili nell'anteprima per gli sviluppatori): `chat.app.spaces.create` `chat.app.spaces`
Creare uno spazio e aggiungere membri	—	Con l'autenticazione utente: `chat.spaces.create` `chat.spaces`
Aggiungere un utente a uno spazio		Con l'autenticazione utente: `chat.memberships` `chat.memberships.app` `chat.import` Con l'autenticazione delle app e l'approvazione dell'amministratore (disponibili nell'anteprima per gli sviluppatori): `chat.app.memberships`
Elenca attività o eventi da uno spazio di Chat	—	Con l'autenticazione utente, devi utilizzare un ambito per ogni tipo di evento incluso nella richiesta: Per gli eventi relativi ai messaggi: `chat.messages` `chat.messages.readonly` Per gli eventi relativi alle reazioni: `chat.messages.reactions` `chat.messages.reactions.readonly` `chat.messages` `chat.messages.readonly` Per gli eventi relativi agli abbonamenti: `chat.memberships` `chat.memberships.readonly` Per gli eventi relativi allo spazio: `chat.spaces` `chat.spaces.readonly`

Ambiti di Google Drive

La tabella seguente elenca gli ambiti utilizzati di frequente per i componenti aggiuntivi di Google Workspace che estendono Google Drive.

Ambito

Leggi i metadati dell'elemento selezionato

Ambito
Leggi i metadati dell'elemento selezionato	`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 sugli elementi selezionati da un utente in Google Drive. I metadati sono limitati all'ID, al titolo, al tipo MIME, all'URL dell'icona e all'indicazione se il componente aggiuntivo dispone dell'autorizzazione per accedere all'elemento.
Accesso per file	`https://www.googleapis.com/auth/drive.file` Consigliato se il componente aggiuntivo deve accedere a singoli file di Drive. Concede l'accesso per file ai file creati o aperti dall'app utilizzando il servizio avanzato Drive di Apps Script. Ciò non consente azioni simili utilizzando il servizio Drive di base. L'autorizzazione dei file viene concessa per singolo file e viene revocata quando l'utente annulla l'autorizzazione dell'app. Consulta 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 sugli elementi selezionati da un utente in Google Drive. I metadati sono limitati all'ID, al titolo, al tipo MIME, all'URL dell'icona e all'indicazione se il componente aggiuntivo dispone dell'autorizzazione per accedere all'elemento.

Accesso per file

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

Consigliato se il componente aggiuntivo deve accedere a singoli file di Drive. Concede l'accesso per file ai file creati o aperti dall'app utilizzando il servizio avanzato Drive di Apps Script. Ciò non consente azioni simili utilizzando il servizio Drive di base. L'autorizzazione dei file viene concessa per singolo file e viene revocata quando l'utente annulla l'autorizzazione dell'app. Consulta l' esempio di richiesta di accesso ai file per i file selezionati.

Token di accesso

Per proteggere i dati utente, gli ambiti Gmail utilizzati nei componenti aggiuntivi di Google Workspace concedono l'accesso temporaneo ai dati utente. Per attivare l'accesso temporaneo, chiama GmailApp.setCurrentMessageAccessToken utilizzando un token di accesso da un oggetto evento azione.

Il token di accesso che attiva gli ambiti Gmail non è lo stesso del token di accesso restituito da ScriptApp.getOAuthToken. Utilizza il token fornito nell'oggetto evento 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();
}

Altri ambiti di Google Workspace

Il componente aggiuntivo potrebbe richiedere ambiti aggiuntivi se utilizza altri servizi Google Workspace o Apps Script. Nella maggior parte dei casi, Apps Script rileva questi ambiti e aggiorna automaticamente il manifest. Quando modifichi l'elenco degli ambiti del manifest, non rimuovere alcun ambito a meno che non lo sostituisci con un'alternativa più ristretta.

La tabella seguente mostra gli ambiti utilizzati spesso dai componenti aggiuntivi Google Workspace:

Ambito
Leggere l'indirizzo email dell'utente	`https://www.googleapis.com/auth/userinfo.email` Consente al progetto di leggere l'indirizzo email dell'utente corrente.
Consenti chiamate a 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 della lingua e del fuso orario dell'utente	`https://www.googleapis.com/auth/script.locale` Consente al progetto di conoscere le impostazioni internazionali e il fuso orario dell'utente corrente. Per maggiori dettagli, vedi 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.
Visualizzare l'anteprima dei link di terze parti	`https://www.googleapis.com/auth/workspace.linkpreview` Obbligatorio se il componente aggiuntivo visualizza l'anteprima dei link di un servizio di terze parti. Consente al progetto di visualizzare un link all'interno di un'applicazione Google Workspace mentre l'utente interagisce con il link. Per saperne di più, vedi Visualizzare l'anteprima dei link con smart chip.
Creare risorse di terze parti	`https://www.googleapis.com/auth/workspace.linkcreate` Obbligatorio se il componente aggiuntivo crea risorse in un servizio di terze parti. Consente al progetto di leggere le informazioni che gli utenti inviano al modulo di creazione delle risorse e inserire un link alla risorsa all'interno di un'applicazione Google Workspace. Per scoprire di più, consulta Creare risorse di terze parti dal menu @.