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'interfaccia utente 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 a leggere i messaggi email di un utente o creare eventi nel suo calendario. Il progetto di script del componente aggiuntivo definisce queste singole autorizzazioni come ambiti OAuth.
Puoi dichiarare gli ambiti nel manifest
utilizzando le stringhe 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 attuale", che è 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.
Visualizzazione degli ambiti
Puoi vedere gli ambiti attualmente richiesti dal tuo progetto di script:
- 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 manifest del progetto, sotto il campo oauthScopes
, ma solo se li hai impostati in modo esplicito.
Impostazione di ambiti espliciti
Apps Script determina automaticamente gli ambiti necessari a uno script analizzando il codice alla ricerca di chiamate a funzioni che li richiedono. Per la maggior parte degli script questo è sufficiente e consente di risparmiare tempo, ma per i componenti aggiuntivi pubblicati dovresti esercitare un controllo più diretto degli ambiti.
Ad esempio, Apps Script potrebbe assegnare a un progetto di script di componenti aggiuntivi 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 dei componenti aggiuntivi.
Puoi impostare esplicitamente gli ambiti utilizzati dal progetto di script modificando il file manifest. Il campo del manifest oauthScopes
è un array di tutti gli ambiti utilizzati dal componente aggiuntivo. Per impostare gli ambiti del progetto, segui questi passaggi:
- Visualizza gli ambiti attualmente utilizzati dal componente aggiuntivo. Determinate quali modifiche devono essere apportate, ad esempio utilizzando 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 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 componente aggiuntivo venga sottoposto a verifica del client OAuth prima di poterlo pubblicare. 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 relative ai dati utente
Ambiti con restrizioni
Alcuni ambiti sono limitati e soggetti a regole aggiuntive che aiutano a proteggere i dati utente. Se intendi pubblicare un componente aggiuntivo di Gmail o dell'Editor che utilizza uno o più ambiti con restrizioni, il componente aggiuntivo deve rispettare tutte le restrizioni specificate prima di poter essere pubblicato.
Consulta l'elenco completo degli ambiti con restrizioni prima di provare a pubblicare. Se il componente aggiuntivo ne utilizza uno, devi rispettare i requisiti aggiuntivi per 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 | |
---|---|
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 |
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 |
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 su Drive. Consente al componente aggiuntivo di leggere metadati limitati relativi agli elementi selezionati da un utente su Google Drive. I metadati sono limitati a ID dell'elemento, titolo, tipo MIME, URL dell'icona e indica se il componente aggiuntivo è autorizzato 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.
Concede l'accesso per file ai file creati o aperti dall'app utilizzando il servizio avanzato di Drive di Apps Script. Tuttavia, non è possibile utilizzare azioni simili con il servizio Drive di base. L'autorizzazione dei file viene concessa in base al singolo file e viene revocata quando l'utente disautorizza l'app. |
Ambiti dei componenti aggiuntivi di Gmail
Esistono alcuni ambiti che sono stati creati appositamente per i componenti aggiuntivi di Google Workspace per proteggere i dati di Gmail degli utenti. Devi aggiungere questi ambiti esplicitamente al manifest del componente aggiuntivo, insieme a tutti gli 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. Quelli con l'etichetta Obbligatorio devono essere aggiunti al file manifest del componente aggiuntivo di Google Workspace se il componente aggiuntivo estende Gmail.
Assicurati anche di sostituire l'ambito https://mail.google.com
molto ampio nel
componente aggiuntivo con un insieme più ristretto di ambiti che consentano le interazioni necessarie per il componente aggiuntivo
e niente di più.
Ambito | |
---|---|
Crea nuove bozze |
https://www.googleapis.com/auth/gmail.addons.current.action.compose
Obbligatorio se il componente aggiuntivo utilizza gli attivatori di azione di scrittura. Consente al componente aggiuntivo di creare temporaneamente nuove bozze di messaggi e risposte. Per i dettagli, consulta la sezione Composizione di bozze di messaggi. Questo ambito viene spesso utilizzato anche con le azioni di scrittura. 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 (come 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 dell'azione di scrittura. Per le azioni di scrittura, questo ambito è obbligatorio se un trigger di scrittura deve accedere ai metadati. In pratica, questo ambito consente all'attivatore di scrittura di accedere agli elenchi di destinatari (to:, cc: e bcc:) di una bozza di un'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 selezionata una voce di menu del 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. |
Leggi i contenuti e i metadati dei messaggi |
https://www.googleapis.com/auth/gmail.readonly
Leggere 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. |
Token di accesso
Per proteggere i dati utente, gli ambiti di Gmail utilizzati nei componenti aggiuntivi di Google Workspace concedono solo l'accesso temporaneo 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 editor
Di seguito sono riportati gli ambiti utilizzati di frequente 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 ai file di Fogli corrente |
https://www.googleapis.com/auth/spreadsheets.currentonly
Obbligatorio se il componente aggiuntivo accede all'API Apps Script Sheet. Concede l'accesso temporaneo ai contenuti del foglio di lavoro aperto. |
Accesso ai file di Presentazioni attuale |
https://www.googleapis.com/auth/presentations.currentonly
Obbligatorio se il componente aggiuntivo accede all'API Apps Script Presentazioni. Concede l'accesso temporaneo ai contenuti della presentazione aperta. |
Accesso per file |
https://www.googleapis.com/auth/drive.file
Obbligatorio per il componente aggiuntivo per utilizzare |
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 aggiornare automaticamente il manifest. Quando modifichi l'elenco degli ambiti del manifest, non rimuovere nessun ambito, a meno che tu non li sostituisca con un'alternativa più appropriata, ad esempio un ambito più ristretto.
Come riferimento, ecco un elenco di ambiti di Apps Script che spesso vengono utilizzati insieme ai 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 effettuare richieste
|
Lettura impostazioni internazionali e 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 maggiori dettagli, vedi 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 trigger. |
Visualizza l'anteprima dei link di terze parti |
https://www.googleapis.com/auth/workspace.linkpreview
Obbligatorio se il componente aggiuntivo mostra l'anteprima dei 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 scoprire di più, consulta Visualizzare l'anteprima dei link con smart chip. |
Creazione di 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 in un'applicazione Google Workspace. Per scoprire di più, consulta la pagina Creare risorse di terze parti dal menu @. |