Autorizzazione dei componenti aggiuntivi dell'editor

L'autorizzazione per molte app basate su Apps Script è semplice perché 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 che installa sono 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 dall'autore del file.

  • I componenti aggiuntivi di Editor eseguono automaticamente le proprie onOpen() funzioni quando si apre 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 di 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 di 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 è abilitato in un documento, un modulo, una presentazione o un foglio di lavoro quando chiunque lo utilizza.
  • Quando più persone collaborano a un file e una di queste utilizza un plug-in, questo viene installato per l'utente e attivato per il file.

La seguente tabella riassume le differenze tra installato e abilitato. Tieni presente che quando testi uno script come componente aggiuntivo puoi eseguire il test in uno o entrambi questi stati.

Installata Attivato
Si applica a Utente Documento, modulo, presentazione o foglio di lavoro
Causato da Acquistare un componente aggiuntivo dal negozio Scaricare un componente aggiuntivo dal Play Store mentre utilizzi quel documento, modulo, presentazione o foglio di lavoro oppure
Utilizzare 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, moduli, presentazioni o fogli di lavoro che apre o crea Tutti i collaboratori del documento, del modulo, della presentazione o del foglio di lavoro
Modalità di autorizzazione per onOpen() AuthMode.NONE
(a meno che non sia anche attivata, nel qual caso AuthMode.LIMITED)		 AuthMode.LIMITED

Modalità di autorizzazione

La funzione onOpen() di un componente aggiuntivo di 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 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 di Editor è abilitato 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 in ambito onOpen(), onInstall() o globale, le autorizzazioni non vanno a buon fine e altre chiamate, come la compilazione dei menu, si arrestano. Guida è l'unica opzione supportata.

Per eseguire chiamate di servizio con limitazioni, devi utilizzare la modalità di autorizzazione AuthMode.FULL. Le funzioni di interazione con l'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 plug-in 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'enum ScriptApp.AuthMode di Apps Script.

Le modalità di autorizzazione si applicano a tutti i metodi di esecuzione di Apps Script, incluso l'esecuzione dall'editor di script, da un elemento di menu o da una chiamata di Apps Script google.script.run. Tuttavia, la proprietà e.authMode può essere ispezionata solo se lo script viene eseguito come risultato di un attivatore 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. Per tutti gli altri casi, gli script vengono eseguiti in AuthMode.FULL, come descritto nella tabella seguente.

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() (per tutti gli altri orari)
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 un documento, un modulo, una presentazione o un foglio di lavoro No Sì Sì, di sola lettura Sì
Accesso all'interfaccia utente Aggiungere voci del menu Aggiungere voci del menu No Sì
Accesso a Properties No Sì Sì Sì
Accedi a Jdbc, UrlFetch No No Sì Sì
Altri servizi Logger
Utilities		 Eventuali servizi che non accedono ai dati degli utenti Eventuali servizi che non accedono ai dati degli utenti Tutti i servizi

Ciclo di vita dell'autorizzazione di un componente aggiuntivo Editor

Quando un componente aggiuntivo è installato per l'utente corrente o attivato nel file corrente, viene caricato per il documento, il modulo, la presentazione o il foglio di lavoro quando il file viene aperto. Il componente aggiuntivo viene elencato nel menu Estensioni e inizia ad ascoltare gli attivatori semplici onInstall(), onOpen() e onEdit(). Se un utente fa clic su un elemento del menu Estensioni, l'estensione viene eseguita.

Il componente aggiuntivo Editor è installato

Quando un componente aggiuntivo di Editor viene installato dal negozio, la sua funzione onInstall() viene eseguita in AuthMode.FULL. In questa modalità di autorizzazione, il plug-in può eseguire una routine di configurazione complessa. Dovresti anche utilizzare onInstall() 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, vengono caricati tutti i componenti aggiuntivi di Editor installati dall'utente corrente o attivati da qualsiasi collaboratore nel file e vengono chiamate ciascuna delle relative 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 è importante. L'esempio seguente 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 di conseguenza.

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 i componenti del menu per aprire barre laterali e finestre di dialogo, poiché vengono eseguiti in AuthMode.FULL.

Un utente esegue il componente aggiuntivo Editor

Quando un utente fa clic su un elemento di menu Estensioni, Apps Script controlla innanzitutto se l'utente ha installato il componente aggiuntivo e, in caso contrario, lo invita a farlo. Se l'utente ha autorizzato il plug-in, lo script esegue la funzione corrispondente all'elemento del menu in AuthMode.FULL. Il plug-in è attivato nel documento, nel modulo, nella presentazione o nel foglio di lavoro, se non lo era già.

Risolvere i problemi di visualizzazione 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 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() eventuali menzioni di servizi o oggetti di Apps Script associati, ad esempio PropertiesService, SpreadsheetApp o GmailApp.
  3. Se un servizio viene utilizzato per altro che per creare gli 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 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 prodotte, e sposta le chiamate di servizio nelle funzioni che ne hanno bisogno. Riordina o riscrivi la base di codice per adattarla 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 impostato su Installato per l'utente corrente e che il testo sotto la casella di configurazione sia Prova in AuthMode.None.

  6. Avvia il deployment di prova e apri il menu Estensioni.

  7. Se vengono visualizzati tutti gli elementi del menu, il problema è stato risolto. Se vedi solo il menu Guida, torna al passaggio 1. Potresti aver perso una chiamata di servizio.