Autorizzazione dei componenti aggiuntivi dell'editor

L'autorizzazione per molte app Google Apps Script è semplice. Il progetto di script richiede le autorizzazioni mancanti di cui ha bisogno quando qualcuno tenta di utilizzarlo.

Il modello di autorizzazione per i componenti aggiuntivi dell'editor è più complesso per diversi motivi:

• Quando un utente crea un file, tutti i componenti aggiuntivi installati dall'utente vengono elencati nel menu Estensioni, anche se l'utente non ha ancora autorizzato questi componenti aggiuntivi.

• Questi componenti aggiuntivi funzionano sui file di Google Drive che possono essere condivisi con i collaboratori. I collaboratori che non hanno installato il componente aggiuntivo dell'editor lo vedono nei documenti in cui il creatore del file lo ha utilizzato.

• I componenti aggiuntivi dell'editor eseguono automaticamente le funzioni onOpen quando viene aperto un documento.

Per proteggere i dati utente, vengono applicate modalità di autorizzazione che rendono alcuni servizi non disponibili per onOpen. Questa guida spiega cosa può fare il tuo codice e quando.

Modello di autorizzazione

La modalità di autorizzazione di un componente aggiuntivo dell'editor dipende dal suo stato, che a sua volta dipende da chi lo utilizza: l'utente che ha installato il componente aggiuntivo o un collaboratore.

Stati dei componenti aggiuntivi dell'editor

I componenti aggiuntivi dell'editor nel menu Estensioni sono installati, attivati o entrambi:

• Un componente aggiuntivo viene installato per un determinato utente dopo che lui o il suo amministratore lo ha scaricato da Google Workspace Marketplace e lo ha autorizzato ad accedere ai suoi dati di Google.
• Un componente aggiuntivo viene attivato in un documento, un modulo, una presentazione o un foglio di lavoro quando chiunque lo utilizza.
• Quando le persone collaborano a un file e una di loro utilizza un componente aggiuntivo, questo viene installato per l'utente e attivato per il file.

La seguente tabella riassume le differenze tra installato e attivato. Quando testi uno script come componente aggiuntivo, puoi eseguire il test in uno o entrambi gli stati.

Modalità di autorizzazione

La funzione onOpen di un componente aggiuntivo dell'editor viene eseguita automaticamente quando un utente apre un documento, un modulo, una presentazione o un foglio di lavoro. Per proteggere i dati degli utenti, Apps Script limita le azioni che la funzione onOpen può eseguire. Lo stato del componente aggiuntivo dell'editor determina la modalità di autorizzazione in cui viene eseguita la funzione onOpen.

Se un componente aggiuntivo dell'editor è attivato nel file, nel modulo, nella presentazione o nel foglio di lavoro, onOpen viene eseguito in AuthMode.LIMITED. Se il componente aggiuntivo non è attivato e viene solo installato, onOpen viene eseguito in AuthMode.NONE.

In AuthMode.NONE, un componente aggiuntivo non può eseguire determinati servizi finché l'utente non interagisce con il componente aggiuntivo facendo clic o eseguendo funzioni personalizzate. Se il componente aggiuntivo tenta di utilizzare questi servizi in onOpen, onInstall o nell'ambito globale, le autorizzazioni non vanno a buon fine e altre chiamate, come il completamento dei menu, si interrompono. L'unica opzione supportata è la Guida.

Per eseguire chiamate di servizi limitati, devi utilizzare la modalità di autorizzazione AuthMode.FULL. Le funzioni di interazione utente, come fare clic su un'opzione di menu, vengono eseguite solo in questa modalità. Dopo che il codice è stato eseguito in modalità AuthMode.FULL, il componente aggiuntivo può utilizzare tutti gli ambiti autorizzati.

Solo i componenti aggiuntivi dell'editor pubblicati possono essere in AuthMode.NONE; i componenti aggiuntivi dell'editor non pubblicati eseguono onOpen in AuthMode.LIMITED. Tuttavia, è previsto in entrambe le modalità di autorizzazione. Per farlo, testa un componente aggiuntivo dell'editor.

Apps Script passa la modalità di autorizzazione come proprietà authMode del parametro evento di Apps Script, e; il valore di e.authMode corrisponde a una costante nell'enumerazione ScriptApp.AuthMode di Apps Script.

Le modalità di autorizzazione si applicano a tutti i metodi di esecuzione di Apps Script, inclusa l'esecuzione dall'editor di script, da una voce di menu o da una chiamata di Apps Script google.script.run. Tuttavia, la proprietà e.authMode può essere esaminata solo se lo script viene eseguito in seguito a un trigger come onOpen, onEdit o onInstall. Le funzioni personalizzate in Fogli Google utilizzano la propria modalità di autorizzazione, AuthMode.CUSTOM_FUNCTION, che è simile a LIMITED ma presenta restrizioni leggermente diverse. In tutti gli altri casi, gli script vengono eseguiti in AuthMode.FULL, come descritto nella tabella seguente.

Ciclo di vita dell'autorizzazione di un componente aggiuntivo dell'editor

Quando un componente aggiuntivo viene installato per l'utente corrente o attivato nel file corrente, il componente aggiuntivo viene caricato per il documento, il modulo, la presentazione o il foglio di lavoro quando viene aperto. Il componente aggiuntivo viene elencato nel menu Estensioni e inizia ad ascoltare i trigger semplici onInstall, onOpen, e onEdit. Se un utente fa clic su una voce di menu Estensioni, questa viene eseguita.

Il componente aggiuntivo dell'editor è installato

Quando un componente aggiuntivo dell'editor viene installato dallo store, la relativa funzione onInstall viene eseguita in AuthMode.FULL. In questa modalità di autorizzazione, il componente aggiuntivo può eseguire una routine di configurazione complessa. Dovresti utilizzare onInstall anche per creare voci di menu, poiché il documento, il modulo, la presentazione o il foglio di lavoro è già aperto e la funzione onOpen non è stata eseguita. Il seguente esempio mostra come chiamare la funzione onOpen dalla funzione onInstall:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Il componente aggiuntivo dell'editor è aperto

Quando viene aperto un documento, un modulo, una presentazione o un foglio di lavoro, vengono caricati tutti i componenti aggiuntivi dell'editor installati dall'utente corrente o attivati da un collaboratore nel file e viene chiamata ciascuna delle funzioni onOpen. La modalità di autorizzazione in cui viene eseguita onOpen dipende dal fatto che un componente aggiuntivo sia installato o attivato.

Se un componente aggiuntivo crea solo un menu di base, la modalità non ha importanza. Il seguente esempio mostra una funzione onOpen di base:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Per aggiungere voci di menu dinamiche in base alle proprietà di Apps Script archiviate, per leggere i contenuti del file corrente o per eseguire altre attività avanzate, devi identificare la modalità di autorizzazione e gestirla in modo appropriato.

Il seguente esempio mostra una funzione onOpen avanzata che modifica la sua azione in base alla modalità di autorizzazione:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

Quando viene eseguita la funzione onOpen, l'intero script viene caricato e le istruzioni globali vengono eseguite nella stessa modalità di autorizzazione di onOpen. Se la modalità di autorizzazione vieta le istruzioni globali, sia le istruzioni globali sia onOpen non vengono eseguite. Se il componente aggiuntivo pubblicato non riesce ad aggiungere le voci di menu, esamina la console del browser per verificare se è stato restituito un errore. Quindi, esamina lo script per verificare se la funzione onOpen o le variabili globali chiamano servizi non consentiti in AuthMode.NONE.

I componenti aggiuntivi non possono aprire barre laterali o finestre di dialogo durante l'esecuzione in AuthMode.LIMITED. Puoi utilizzare voci di menu per aprire barre laterali e finestre di dialogo, poiché vengono eseguite in AuthMode.FULL.

Un utente esegue il componente aggiuntivo dell'editor

Quando un utente fa clic su una voce di menu Estensioni , Apps Script verifica innanzitutto se l'utente ha installato il componente aggiuntivo e, in caso contrario, gli chiede di farlo. Se l'utente ha autorizzato il componente aggiuntivo, lo script esegue la funzione corrispondente alla voce di menu in AuthMode.FULL. Il componente aggiuntivo viene attivato nel documento, nel modulo, nella presentazione o nel foglio di lavoro, se non lo era già.

Risolvere i problemi di rendering dei menu dei componenti aggiuntivi

Il menu del componente aggiuntivo potrebbe non essere sottoposto a rendering se il codice non gestisce correttamente le modalità di autorizzazione. Ad esempio:

• Un componente aggiuntivo tenta di eseguire un servizio Apps Script non supportato dalla modalità di autorizzazione corrente.

• Un componente aggiuntivo tenta di eseguire una chiamata di servizio prima che un utente interagisca con esso.

Per rimuovere o riorganizzare una chiamata di servizio che causa errori di autorizzazione in AuthMode.NONE, prova le seguenti azioni:

1. Apri il progetto Apps Script per il componente aggiuntivo e individua la funzione onOpen.
2. Cerca nella funzione onOpen i riferimenti ai servizi o agli oggetti Apps Script associati, come PropertiesService, SpreadsheetApp o GmailApp.
3. Se un servizio viene utilizzato per qualsiasi altro scopo oltre alla creazione degli elementi dell'interfaccia utente, rimuovilo o racchiudilo in un blocco di commenti. Lascia solo questi metodi: .getUi, .createMenu, .addItem e .addToUi. Trova e rimuovi anche qualsiasi servizio al di fuori di una funzione.
4. Identifica le funzioni che potrebbero contenere le righe di codice commentate o rimosse nel passaggio precedente, in particolare quelle che utilizzano le informazioni che producono, e sposta le chiamate di servizio nelle funzioni che ne hanno bisogno. Riorganizza o riscrivi la codebase per adattarla alle modifiche apportate nei passaggi precedenti.
5. Salva il codice e crea un deployment di test. Quando crei un deployment di test, assicurati che il campo Configurazione sia Installato per l'utente corrente e che il testo sotto la casella Configurazione indichi Test in AuthMode.NONE.
6. Avvia il deployment di test e apri il menu Estensioni.
7. Se vengono visualizzate tutte le voci di menu, il problema è stato risolto. Se vedi solo il menu Guida, torna al passaggio 1. Potresti aver perso una chiamata di servizio.

Argomenti correlati

• App web
• Tipi di componenti aggiuntivi
• Testare un componente aggiuntivo dell'editor