Autorizzazione dei componenti aggiuntivi dell'editor

L'autorizzazione per molte app Google Apps Script è semplice. Il progetto di script chiede le autorizzazioni mancanti necessarie quando qualcuno tenta di utilizzarlo.

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

• Quando un utente crea un file, tutti i componenti aggiuntivi installati sono 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 essere condivisi con i collaboratori. I collaboratori che non hanno installato il componente aggiuntivo Editor lo vedono nei documenti in cui è stato utilizzato dal creatore del file.

• I componenti aggiuntivi di Editor eseguono automaticamente le relative 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 Editor dipende dal suo stato, che dipende da chi lo utilizza: l'utente che ha installato il componente aggiuntivo o un collaboratore.

Stati del componente aggiuntivo 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 hanno scaricato da Google Workspace Marketplace e lo hanno autorizzato ad accedere ai suoi dati di Google.
• Un componente aggiuntivo è attivato in un documento, un modulo, una presentazione o un foglio di lavoro quando viene utilizzato da chiunque.
• 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 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 Editor determina la modalità di autorizzazione in cui viene eseguita la funzione onOpen.

Se un componente aggiuntivo 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 ed è 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 tuo componente aggiuntivo tenta di utilizzare questi servizi nell'ambito onOpen, onInstall o globale, le autorizzazioni non vengono concesse e altre chiamate, come il riempimento dei menu, si interrompono. L'unica opzione supportata è l'assistenza.

Per eseguire chiamate di servizio con limitazioni, devi utilizzare la modalità di autorizzazione AuthMode.FULL. Le funzioni di interazione utente, ad esempio il clic su un'opzione di menu, vengono eseguite solo in questa modalità. Dopo l'esecuzione del codice in modalità AuthMode.FULL, il componente aggiuntivo può utilizzare tutti gli ambiti autorizzati.

Solo i componenti aggiuntivi per editor pubblicati possono essere in AuthMode.NONE; i componenti aggiuntivi per editor non pubblicati vengono eseguiti onOpen in AuthMode.LIMITED. Tuttavia, previsto in entrambe le modalità di autorizzazione. Per farlo, testa un componente aggiuntivo 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 google.script.run di Apps Script. Tuttavia, la proprietà e.authMode può essere ispezionata 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, simile a LIMITED, ma con limitazioni 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 il file viene aperto. Il componente aggiuntivo è elencato nel menu Estensioni e inizia a monitorare gli attivatori semplici onInstall, onOpen e onEdit. Se un utente fa clic su una voce di menu Estensioni, viene eseguita.

Il componente aggiuntivo 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. Devi utilizzare anche onInstall 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.
}

Si apre il componente aggiuntivo Editor.

Quando viene aperto un documento, un modulo, una presentazione o un foglio di lavoro, vengono caricati tutti i componenti aggiuntivi Editor installati dall'utente corrente o attivati da un collaboratore nel file e vengono chiamate le rispettive funzioni onOpen. La modalità di autorizzazione in cui viene eseguito 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 memorizzate, 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 cambia 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 con la stessa modalità di autorizzazione di onOpen. Se la modalità di autorizzazione vieta le istruzioni globali, sia le istruzioni globali che 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. Poi, 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 le voci di menu per aprire barre laterali e finestre di dialogo, poiché vengono eseguite in AuthMode.FULL.

Un utente esegue il componente aggiuntivo Editor

Quando un utente fa clic su una voce di menu Estensioni, Apps Script controlla innanzitutto se l'utente ha installato il componente aggiuntivo e gli chiede di farlo in caso contrario. Se l'utente ha autorizzato il componente aggiuntivo, lo script esegue la funzione corrispondente alla voce di menu in AuthMode.FULL. Il componente aggiuntivo è 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 dei componenti aggiuntivi potrebbe non essere visualizzato 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 attuale.

• 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 tuo componente aggiuntivo e individua la funzione onOpen.
2. Cerca nella funzione onOpen menzioni di servizi o oggetti Apps Script associati, ad esempio PropertiesService, SpreadsheetApp o GmailApp.
3. Se un servizio viene utilizzato per scopi diversi dalla creazione degli elementi dell'interfaccia utente, rimuovilo o inseriscilo 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 il tuo codebase per adattarlo 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 tutti gli elementi del menu vengono visualizzati, il problema è 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 Editor