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 agire per suo conto. Quando un utente esegue un componente aggiuntivo per la prima volta, la UI del componente aggiuntivo presenta una richiesta di autorizzazione per avviare il flusso di autorizzazione.

Durante questo flusso, il prompt comunica all'utente cosa vuole l'applicazione l'autorizzazione per farlo. Ad esempio, un componente aggiuntivo potrebbe richiedere l'autorizzazione per leggere messaggio email dell'utente o creare eventi nel proprio calendario. Script del componente aggiuntivo il progetto definisce queste singole autorizzazioni come ambiti OAuth.

Dichiari gli ambiti nel file manifest utilizzando stringhe URL. Durante il flusso di autorizzazione, Apps Script presenta una descrizione leggibile dell'ambito per l'utente. Ad esempio, il componente aggiuntivo di Google Workspace potrebbe utilizzare il pulsante "Leggi il messaggio corrente" che è scritto nel file manifest come https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Durante flusso di autorizzazione, un componente aggiuntivo con questo ambito chiede all'utente di autorizzare componente aggiuntivo per: visualizzare i tuoi messaggi email quando il componente aggiuntivo è in esecuzione.

Visualizzazione degli ambiti

Puoi vedere gli ambiti attualmente richiesti dal progetto di script eseguendo la seguenti:

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 oauthScopes ma solo se hai impostato questi ambiti esplicitamente.

Impostazione di ambiti espliciti

Apps Script determina automaticamente gli ambiti necessari per uno script analizzando e il proprio codice per le chiamate di funzione che le richiedono. Per la maggior parte degli script, sufficiente e ti fa risparmiare tempo, ma per i componenti aggiuntivi pubblicati dovresti un controllo più diretto degli ambiti.

Ad esempio, Apps Script potrebbe dare a un progetto di script di componenti aggiuntivi l'ambito https://mail.google.com per impostazione predefinita. Quando un utente autorizza uno script progetto con questo ambito, al progetto viene concesso l'accesso completo ai campi Gmail dell'utente . Per i componenti aggiuntivi pubblicati, devi sostituire questo ambito con un altro un insieme limitato di dispositivi in grado di soddisfare tutte le esigenze dei componenti aggiuntivi e niente più.

Puoi impostare esplicitamente gli ambiti utilizzati dal progetto di script modificando e il relativo file manifest. Il campo manifest oauthScopes è un array di tutti gli ambiti utilizzati dal componente aggiuntivo. Per impostare gli ambiti del progetto, esegui la seguenti:

Visualizza gli ambiti attualmente utilizzati dal tuo componente aggiuntivo. Determina cosa modifiche da apportare, ad esempio utilizzando un ambito più ristretto.
Apri il file manifest del componente aggiuntivo.
Individua il campo di primo livello oauthScopes. Se non è presente, puoi aggiungerlo.
La oauthScopes specifica un array di stringhe. Per impostare gli ambiti utilizzato dal tuo progetto, sostituisci i contenuti di questo array con gli ambiti che vuoi usare. 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 può richiedere la verifica del componente aggiuntivo Verifica del client OAuth prima di pubblicarlo. Per ulteriori informazioni, consulta le seguenti guide:

Ambiti con restrizioni

Alcuni ambiti sono limitati e soggetti a regole aggiuntive che consentono proteggere i dati degli utenti. Se intendi pubblicare un componente aggiuntivo di Gmail o Editor che utilizzi uno o più ambiti con restrizioni, il componente aggiuntivo deve rispettare tutte le prima di poter essere pubblicato.

Consulta l'elenco completo degli ambiti con restrizioni prima di tentare la pubblicazione. Se il componente aggiuntivo ne utilizza uno, devi rispettare con Ulteriori requisiti per ambiti API specifici prima della pubblicazione.

Ambiti di calendario

Di seguito sono riportati gli ambiti utilizzati di frequente 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 per accedere ai metadati dell'evento.
Lettura dei 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 disponibile solo se `addOns.calendar.eventAccess` campo manifest è impostato su `READ` o `READ_WRITE`.
Scrivi 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 disponibile solo se `addOns.calendar.eventAccess` campo manifest è impostato su `WRITE` o `READ_WRITE`.

Ambiti Drive

Di seguito sono riportati gli ambiti utilizzati di frequente 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 su Drive. Consente al componente aggiuntivo di leggere metadati limitati sugli elementi di cui l'utente ha selezionate su Google Drive. I metadati sono limitati all'ID dell'elemento, titolo, tipo MIME, URL dell'icona e se il componente aggiuntivo è autorizzato a accedere all'elemento.
Accesso per file	`https://www.googleapis.com/auth/drive.file` Consigliato se il componente aggiuntivo deve accedere a un singolo Drive . Concede l'accesso per file ai file creati o aperti dall'app, utilizzando Advanced Drive di Apps Script assistenza. Non è consentito l'utilizzo di azioni simili mediante l'attributo il servizio Drive di base, in ogni caso. L'autorizzazione dei file viene concessa per ogni singolo file ed è revocato quando l'utente annulla l'autorizzazione dell'app. Consulta le 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 su Drive. Consente al componente aggiuntivo di leggere metadati limitati sugli elementi di cui l'utente ha selezionate su Google Drive. I metadati sono limitati all'ID dell'elemento, titolo, tipo MIME, URL dell'icona e se il componente aggiuntivo è autorizzato a accedere all'elemento.

Accesso per file

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

Consigliato se il componente aggiuntivo deve accedere a un singolo Drive . Concede l'accesso per file ai file creati o aperti dall'app, utilizzando Advanced Drive di Apps Script assistenza. Non è consentito l'utilizzo di azioni simili mediante l'attributo il servizio Drive di base, in ogni caso. L'autorizzazione dei file viene concessa per ogni singolo file ed è revocato quando l'utente annulla l'autorizzazione dell'app.

Consulta le Esempio di richiesta di accesso ai file per i file selezionati.

Ambiti dei componenti aggiuntivi di Gmail

Esistono alcuni ambiti creati appositamente per Componenti aggiuntivi di Google Workspace per contribuire a proteggere gli utenti di Gmail e i dati di Google Cloud. Devi aggiungi questi ambiti in modo esplicito al file manifest del componente aggiuntivo, insieme a eventuali altri del componente aggiuntivo.

Di seguito sono riportati gli ambiti utilizzati di frequente per i componenti aggiuntivi di Google Workspace che estendono Gmail. quelle contrassegnate con l'etichetta Obbligatorie devono essere aggiunte al tuo Manifest del componente aggiuntivo Google Workspace se il componente aggiuntivo si estende Gmail.

Assicurati di sostituire anche l'ambito molto ampio di https://mail.google.com nel tuo con un insieme più ristretto di ambiti che consentono le interazioni e basta.

Ambito
Creare nuove bozze	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obbligatorio se il componente aggiuntivo utilizza trigger di azione di scrittura. Consente al componente aggiuntivo di creare temporaneamente nuove bozze di messaggi e risposte. Vedi Composizione di bozze di messaggi per maggiori dettagli. questo ambito viene spesso utilizzato . di scrittura. 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 (come il 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 metadati nell'azione di scrittura trigger. Per azioni di scrittura, questo ambito è obbligatorio se è presente un trigger di scrittura richiede l'accesso ai metadati. In pratica, questo ambito consente attivare gli elenchi di destinatari di accesso (to:, cc: e bcc:) di una risposta bozza di email.
Leggi i contenuti dei messaggi aperti	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Concede l'accesso ai contenuti del messaggio aperto in seguito a un'interazione dell'utente. ad esempio quando viene selezionata un'opzione di menu aggiuntiva. Richiede un accesso di accesso.
Leggi i 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 anche l'accesso ai contenuti di altri messaggi in aperta . Richiede un token di accesso.
Leggi i contenuti e i metadati dei messaggi	`https://www.googleapis.com/auth/gmail.readonly` Leggi tutti i metadati e i contenuti delle email, incluso il messaggio aperto. Obbligatorio se devi leggere informazioni su altri messaggi, come quando esegui una query di ricerca o leggi un intero thread di messaggi. Avviso: si tratta di un parametro molto generico, ambito limitato. Usala solo se assolutamente necessarie.

Token di accesso

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

Di seguito è riportato un esempio di impostazione di un token di accesso per consentire l'accesso a i 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ù utilizzati per i componenti aggiuntivi di Google Workspace che estendono Documenti, Fogli e Presentazioni.

Ambito
Accesso attuale ai file di Documenti	`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 attuale ai file di Fogli	`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 ai 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 consentire al componente aggiuntivo di utilizzare `onFileScopeGrantedTrigger` e se il componente aggiuntivo accede alle API Documenti, Fogli, Presentazioni o Drive. Concede l'accesso per file ai file creati o aperti dall'app, utilizzando Advanced Drive di Apps Script assistenza. Non è consentito l'utilizzo di azioni simili mediante l'attributo il servizio Drive di base, in ogni caso. L'autorizzazione dei file viene concessa per ogni singolo file ed è revocata quando l'utente annulla l'autorizzazione dell'app.

Altri ambiti

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

Come riferimento, di seguito è riportato un elenco degli ambiti di Apps Script spesso utilizzati in 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 le chiamate a servizi esterni	`https://www.googleapis.com/auth/script.external_request` Consente al progetto di `UrlFetch` richieste. Questa operazione è necessaria anche se il progetto utilizza 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. Vedi Accesso alle impostazioni internazionali e al fuso orario dell'utente per informazioni dettagliate.
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 mostra in anteprima i link da un servizio di terze parti. Consente al progetto di visualizzare un link all'interno di un'applicazione Google Workspace mentre l'utente interagisce con quest'ultima. Per ulteriori informazioni, vedi Visualizza l'anteprima dei link con smart chip.
Crea 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 a il modulo di creazione delle risorse inserire un link alla risorsa in un'applicazione Google Workspace. Per ulteriori informazioni, vedi Crea risorse di terze parti dal menu @.