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 presenta una richiesta di autorizzazione per avviare il flusso di autorizzazione.
Durante questo flusso, il prompt indica all'utente cosa vuole l'applicazione l'autorizzazione. 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 all'utente una descrizione dell'ambito leggibile da un essere umano. 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
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 necessari per uno script analizzando e il proprio codice per le chiamate di funzione che le 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 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 che soddisfano le esigenze dei componenti aggiuntivi e niente 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 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. Il campo
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 potrebbe richiedere la verifica del client OAuth prima di poter pubblicare il componente aggiuntivo. Per ulteriori informazioni, consulta le seguenti guide:
- Verifica del client OAuth per Apps Script
- App non verificate
- Domande frequenti sulla verifica OAuth
- Servizio API di Google: norme dati utente
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 di Calendar
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 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
disponibile solo se
|
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
disponibili solo se il
campo manifest |
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 |
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 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 per i file viene concessa su base individuale e viene revocata quando l'utente disattiva l'app. |
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 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 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 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 | |
---|---|
Creare 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. |
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 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. |
Leggere 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 token 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. Consente inoltre di accedere ai contenuti di altri messaggi nel thread aperto. Richiede un token di accesso. |
Leggi i contenuti e i metadati dei messaggi |
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, come quando esegui una query di ricerca o leggi un intero thread di email. |
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 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 di editor
Di seguito sono riportati gli ambiti di uso frequente per i componenti aggiuntivi di Google Workspace che estendono Documenti, Fogli e Presentazioni.
Ambito | |
---|---|
Accesso ai file di 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 attuale ai file di Fogli |
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 corrente |
https://www.googleapis.com/auth/presentations.currentonly
Obbligatorio se il componente aggiuntivo accede all'API Apps Script Slides. 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 |
Altri ambiti
Il componente aggiuntivo potrebbe richiedere ambiti aggiuntivi se utilizza altri servizi Apps Script. Nella maggior parte dei casi, puoi lasciare che sia Apps Script a rilevare questi ambiti e aggiornare 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.
Come riferimento, di seguito è riportato un elenco di 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 chiamate a servizi esterni |
https://www.googleapis.com/auth/script.external_request
Consente al progetto di
|
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 in anteprima i link da 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 Visualizzare 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 ulteriori informazioni, vedi Crea risorse di terze parti dal menu @. |