Autorizzazione componente aggiuntivo Editor

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

  • Questi componenti aggiuntivi funzionano su file di Google Drive che possono essere condivisi con i collaboratori. I collaboratori che non hanno installato il componente aggiuntivo Editor lo visualizzano nei documenti in cui l'autore del file lo ha utilizzato.

  • I componenti aggiuntivi dell'editor eseguono automaticamente le funzioni onOpen() all'apertura di 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 dell'editor dipende dal suo stato, che dipende da chi lo utilizza: dall'utente che ha installato il componente aggiuntivo o da un collaboratore.

Stati dei componenti aggiuntivi 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 quest'ultimo o il suo amministratore lo hanno ricevuto da Google Workspace Marketplace e dopo averlo autorizzato ad accedere ai propri dati di Google.
  • Un componente aggiuntivo viene attivato in un documento, modulo, presentazione o foglio di lavoro quando qualsiasi utente lo utilizza.
  • Quando le persone collaborano a un file e uno di loro utilizza un componente aggiuntivo, il componente viene installato per l'utente e attivato per il file.

La tabella seguente riassume le differenze tra installazione e attivazione. Tieni presente che quando testi uno script come componente aggiuntivo, puoi eseguire il test in uno o entrambi gli stati.

Installata Abilitati
Si applica a Utente Documento, modulo, presentazione o foglio di lavoro
Causato da Recupero di un componente aggiuntivo dallo store Scaricare un componente aggiuntivo dallo store mentre utilizzi quel documento, modulo, presentazione o foglio di lavoro oppure
Usare un componente aggiuntivo installato in precedenza in quel documento, modulo, presentazione o foglio di lavoro
Menu visibile a Solo quell'utente, in tutti i documenti, i moduli, le presentazioni o i fogli di lavoro che apre o crea Tutti i collaboratori per il documento, il modulo, la presentazione o il foglio di lavoro in questione
Modalità di autorizzazione per onOpen() AuthMode.NONE
(a meno che non sia anche attivato, nel qual caso AuthMode.LIMITED)		 AuthMode.LIMITED

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 operazioni eseguibili dalla funzione onOpen(). Lo stato del componente aggiuntivo Editor determina in quale modalità di autorizzazione 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 è abilitato 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 in ambito globale, le autorizzazioni non andranno a buon fine e altre chiamate, come la compilazione dei menu, interrompi. Guida è l'unica opzione supportata.

Per eseguire chiamate di servizi limitati, 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à. Una volta eseguito il codice in modalità AuthMode.FULL, il componente aggiuntivo può utilizzare tutti gli ambiti autorizzati dall'utente.

Apps Script trasmette la modalità di autorizzazione come proprietà authMode del parametro evento e di Apps Script; il valore 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 a google.script.run. Tuttavia, la proprietà e.authMode può essere ispezionata solo se lo script viene eseguito da un attivatore come onOpen(), onEdit() o onInstall(). In Fogli Google, le funzioni personalizzate utilizzano la propria modalità di autorizzazione, AuthMode.CUSTOM_FUNCTION, che è simile a LIMITED ma presenta limitazioni leggermente diverse. In tutti gli altri casi, gli script vengono eseguiti in AuthMode.FULL, come descritto nella seguente tabella.

NONE LIMITED CUSTOM_FUNCTION FULL
Si verifica per onOpen() (se l'utente ha installato un componente aggiuntivo ma non lo ha attivato nel documento, nel modulo, nella presentazione o nel foglio di lavoro) onOpen() (tutte le altre volte)
onEdit() (solo in Fogli)		 Funzioni personalizzate Tutti gli altri momenti, inclusi:
attivatori installabili
onInstall()
google.script.run
Accesso ai dati utente Solo locale Solo locale Solo locale Sì
Accesso a documenti, moduli, presentazioni o fogli di lavoro No Sì Sì: sola lettura Sì
Accesso all'interfaccia utente Aggiungere voci del menu Aggiungere voci del menu No Sì
Accedi a Properties No Sì Sì Sì
Accesso a Jdbc, UrlFetch No No Sì Sì
Altri servizi Logger
Utilities		 Tutti i servizi che non accedono ai dati utente Tutti i servizi che non accedono ai dati utente Tutti i servizi

Ciclo di autorizzazione di un componente aggiuntivo Editor

Quando un componente aggiuntivo viene installato per l'utente corrente o è abilitato nel file corrente, il componente aggiuntivo viene caricato per il documento, il modulo, la presentazione o il foglio di lavoro all'apertura di quel file. Il componente aggiuntivo è elencato nel menu Estensioni e inizia ad ascoltare i semplici attivatori 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 dall'archivio, la relativa funzione onInstall() viene eseguita in AuthMode.FULL. In questa modalità di autorizzazione, il componente aggiuntivo può eseguire una routine di configurazione complessa. Utilizza onInstall() anche per creare voci di menu, poiché il documento, il modulo, la presentazione o il foglio di lavoro sono già aperti e la funzione onOpen() non è stata eseguita. L'esempio seguente mostra come chiamare la funzione onOpen() dalla funzione onInstall():

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

Il componente aggiuntivo Editor è aperto

Quando si apre un documento, un modulo, una presentazione o un foglio di lavoro, carica ogni componente aggiuntivo dell'editor installato dall'utente corrente o che qualsiasi collaboratore ha attivato nel file e richiama ciascuna delle funzioni onOpen(). La modalità di autorizzazione in cui viene eseguito onOpen() dipende dal fatto che un componente aggiuntivo sia installato o abilitato.

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 basate sulle proprietà di Apps Script archiviate, leggere i contenuti del file corrente o eseguire altre attività avanzate, devi identificare la modalità di autorizzazione e gestirla in modo appropriato.

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

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 che corrisponde alla voce di menu in AuthMode.FULL. Se non lo è già, il componente aggiuntivo è attivato nel documento, nel modulo, nella presentazione o nel foglio di lavoro.

Risolvere i problemi relativi al rendering dei menu dei componenti aggiuntivi

Il menu del componente aggiuntivo 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 vi interagisca con il componente.

Per rimuovere o riorganizzare una chiamata al 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() le menzioni di servizi o oggetti Apps Script associati, ad esempio PropertiesService, SpreadsheetApp o GmailApp.
  3. Se un servizio viene utilizzato per qualcosa di diverso dalla creazione degli elementi UI, rimuovilo o aggregalo in un blocco di commenti. Lascia solo questi metodi: .getUi(), .createMenu(), .addItem() e .addToUi(). Inoltre, trova e rimuovi i servizi esterni a 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 generate, e sposta le chiamate ai servizi nelle funzioni che le richiedono. Riordina o riscrivi il codebase per adattarlo alle modifiche apportate nei passaggi precedenti.

  5. Salva il codice e crea un deployment di prova.

    Quando crei un deployment di prova, assicurati che il campo Configurazione sia Installato per l'utente corrente e che il testo sotto la casella Configurazione riporti la dicitura Test in AuthMode.None.

  6. Avvia il deployment di prova 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.