Questa pagina è stata tradotta dall'API Cloud Translation.

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 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 Google Workspace potrebbe utilizzare l'ambito "Leggi messaggio corrente", che è scritto nel file manifest comehttps://www.googleapis.com/auth/gmail.addons.current.message.readonly. Durante la procedura 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.

Visualizzazione degli ambiti

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

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

Visualizza gli ambiti attualmente utilizzati dal tuo componente aggiuntivo. Determina quali modifiche devono essere apportate, ad esempio l'utilizzo di un ambito più ristretto.
Apri il file manifest del componente aggiuntivo.
Individua il campo di primo livello denominato oauthScopes. Se non è presente, puoi aggiungerlo.
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 Google Workspace che espande 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 la verifica del client OAuth del tuo componente aggiuntivo prima che tu possa pubblicarlo. 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.

Scegliere gli ambiti per i componenti aggiuntivi di Google Workspace

Le sezioni seguenti forniscono gli ambiti più comunemente utilizzati per i componenti aggiuntivi di Google Workspace.

Ambiti di editor

Di seguito sono riportati gli ambiti di uso frequente per i componenti aggiuntivi di Google Workspace che estendono Documenti, Fogli e Presentazioni.

Nota: l'ambito currentonly è disponibile solo nei servizi Apps Script. Non sono inclusi i servizi avanzati di Apps Script o le chiamate dirette alle API di Google Workspace.

Ambito
Accesso ai file di Documenti corrente	`https://www.googleapis.com/auth/documents.currentonly` Obbligatorio se il componente aggiuntivo accede all'API Documenti di Apps Script. Concede l'accesso temporaneo ai contenuti del documento aperto.
Accesso ai file di Fogli attuali	`https://www.googleapis.com/auth/spreadsheets.currentonly` Obbligatorio se il componente aggiuntivo accede all'API Fogli di Apps Script. Concede l'accesso temporaneo ai contenuti del foglio di lavoro aperto.
Accesso ai file di Presentazioni attuali	`https://www.googleapis.com/auth/presentations.currentonly` Obbligatorio se il componente aggiuntivo accede all'API di Presentazioni di Apps Script. Concedi l'accesso temporaneo ai contenuti della presentazione aperta.
Accesso per file	`https://www.googleapis.com/auth/drive.file` Obbligatorio per consentire al componente aggiuntivo di utilizzare `onFileScopeGrantedTrigger` e se il componente aggiuntivo accede all'API di Documenti, Fogli, Presentazioni o Drive. Concedi l'accesso a livello di file ai file creati o aperti dall'app utilizzando il servizio Drive avanzato di Apps Script. Tuttavia, non è possibile utilizzare azioni simili con il servizio Drive di base. L'autorizzazione per i file viene concessa su base individuale e viene revocata quando l'utente disattiva l'app.

Gmail

Esistono alcuni ambiti creati appositamente per i componenti aggiuntivi di Google Workspace per contribuire a proteggere i dati di Gmail degli utenti. Devi aggiungere questi ambiti esplicitamente al manifest del componente aggiuntivo, insieme a eventuali altri richiesti dal codice del componente aggiuntivo.

Di seguito sono riportati gli ambiti di uso frequente per i componenti aggiuntivi di Google Workspace che estendono Gmail. quelli contrassegnati come Obbligatorio devono essere aggiunti al manifest del componente aggiuntivo di Google Workspace se il componente aggiuntivo estende Gmail.

Assicurati inoltre di sostituire l'ambito molto ampio https://mail.google.com nel plug-in con un insieme di ambiti più ristretto che consenta solo le interazioni di cui il plug-in ha bisogno.

Ambito
Crea nuove bozze	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obbligatorio se il componente aggiuntivo utilizza attivatori di azioni di composizione. Consente al componente aggiuntivo di creare temporaneamente nuove bozze di messaggi e risposte. Per maggiori dettagli, consulta Scrivere messaggi di bozza. Questo ambito viene spesso utilizzato anche con le azioni di composizione. Richiede un token di accesso.
Leggere 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 l'oggetto o i destinatari). Non consente la lettura dei contenuti dei messaggi e richiede un token di accesso. Obbligatorio se il componente aggiuntivo utilizza i metadati negli attivatori delle azioni di composizione. Per le azioni di composizione, questo ambito è obbligatorio se un attivatore di composizione necessita di accedere ai metadati. In pratica, questo ambito consente a un'azione di composizione di attivare l'accesso 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` Concede l'accesso ai contenuti del messaggio aperto a seguito di un'interazione dell'utente, ad esempio quando viene selezionato un elemento del 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 di accedere 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 intero thread di posta. Avviso: si tratta di un ambito molto ampio e limitato. Utilizzalo solo se assolutamente necessario.

Ambiti di Google Calendar

Di seguito sono riportati gli ambiti di uso 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.
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 sugli 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 `addOns.calendar.eventAccess` è impostato su `READ` o `READ_WRITE`.
Scrivere i 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 sugli 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 Chat, devi autenticarti come utente di Google Chat o come app di Chat. Ogni tipo di autenticazione richiede ambiti diversi e non tutti metodi dell'API Chat supportano l'autenticazione dell'app.

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

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

Metodo	Autenticazione 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 dell'app e l'approvazione dell'amministratore (disponibile in Anteprima per sviluppatori): `chat.app.spaces.create` `chat.app.spaces`
Creare e aggiungere membri a uno spazio	—	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 dell'app e l'approvazione dell'amministratore (disponibile in Anteprima per 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

Di seguito sono riportati gli ambiti di uso frequente per i componenti aggiuntivi di Google Workspace che estendono Google Drive.

Ambito

Leggere i metadati degli elementi selezionati

Ambito
Leggere 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 sugli 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 all'autorizzazione dell'add-on ad 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. Concedi l'accesso a livello di file ai file creati o aperti dall'app utilizzando il servizio Drive avanzato di Apps Script. Tuttavia, non è possibile utilizzare azioni simili con il servizio Drive di base. L'autorizzazione per i file viene concessa su base individuale e viene revocata quando l'utente disattiva l'app. Consulta l' esempio di richiesta di accesso ai file per 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 su Google Drive. I metadati sono limitati all'ID, al titolo, al tipo MIME, all'URL dell'icona dell'elemento e all'autorizzazione dell'add-on ad 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. Concedi l'accesso a livello di file ai file creati o aperti dall'app utilizzando il servizio Drive avanzato di Apps Script. Tuttavia, non è possibile utilizzare azioni simili con il servizio Drive di base. L'autorizzazione per i file viene concessa su base individuale e viene revocata quando l'utente disattiva l'app.

Consulta l' esempio di richiesta di accesso ai file per file selezionati.

Token di accesso

Per proteggere i dati utente, gli ambiti Gmail utilizzati nei componenti aggiuntivi di Google Workspace concedono solo accesso temporaneo ai dati utente. Per attivare 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();
}

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, puoi lasciare che Apps Script li rilevi e aggiorni automaticamente il manifest. Quando modifichi l'elenco degli ambiti del manifest, non rimuovere alcun ambito, a meno che non li sostituisca con un'alternativa più appropriata, ad esempio un ambito più ristretto.

La tabella seguente mostra un elenco di ambiti spesso utilizzati dai componenti aggiuntivi di 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 `UrlFetch` richieste. Questo è necessario anche se il progetto utilizza la libreria OAuth2 per Apps Script.
Leggere le impostazioni internazionali e il 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, consulta Accedere alle impostazioni internazionali e al fuso orario dell'utente.
Creazione di trigger	`https://www.googleapis.com/auth/script.scriptapp` Consente al progetto di creare attivatori.
Anteprima dei link di terze parti	`https://www.googleapis.com/auth/workspace.linkpreview` Obbligatorio se il componente aggiuntivo mostra l'anteprima dei link di un servizio di terze parti. Consente al progetto di vedere un link all'interno di un'applicazione Google Workspace mentre l'utente interagisce con essa. Per scoprire di più, consulta Visualizza l'anteprima dei link con gli 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 inviate dagli utenti al modulo di creazione della risorsa e di inserire un link alla risorsa all'interno di un'applicazione Google Workspace. Per scoprire di più, consulta Creare risorse di terze parti dal menu @.