Autorizzazione dei componenti aggiuntivi dell'editor

L'autorizzazione per molte app basate su Apps Script è semplice perché il progetto di script chiede le autorizzazioni mancanti necessarie 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 vengono elencati nel menu Estensioni, anche se l'utente non li ha ancora autorizzati.

• 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 Editor lo vedono nei documenti in cui è stato utilizzato dal creatore del file.

• I componenti aggiuntivi dell'editor eseguono automaticamente le proprie 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 può aiutarti a capire 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 Google.
• Un componente aggiuntivo è attivato in un documento, modulo, presentazione o 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. Tieni presente che quando testi uno script come componente aggiuntivo puoi eseguire il test in uno o entrambi questi 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 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 vanno a buon fine 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 dell'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 dall'utente.

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 ad ascoltare i attivatori semplici onInstall(), onOpen() e onEdit(). Se un utente fa clic su una voce di menu Estensioni, questa 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 complessa routine di configurazione. Devi anche utilizzare 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.

L'esempio seguente 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();
}

Tieni presente che 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é queste 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 verifica 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 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 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 che si trova 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 tua base di codice 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 Installata 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