Autorizzazione dei componenti aggiuntivi Editor

L'autorizzazione per molte app basate su Apps Script è semplice perché il progetto di script chiede le eventuali autorizzazioni mancanti di cui ha bisogno quando qualcuno tenta per utilizzarlo.

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

• Quando un utente crea un file, vengono installati tutti i componenti aggiuntivi sono elencate 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. Collaboratori che non lo fanno installa il componente aggiuntivo Editor e guardalo nei documenti in cui è stato utilizzato dall'autore del file.

• I componenti aggiuntivi dell'Editor eseguono automaticamente onOpen() all'apertura di un documento.

Per proteggere i dati utente, vengono applicate modalità di autorizzazione che rendono alcuni servizi non disponibile 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 il suo stato, che dipende da chi lo utilizza, ovvero l'utente che ha installato il componente aggiuntivo. o un collaboratore.

Stati dei componenti aggiuntivi Editor

I componenti aggiuntivi Editor nel menu Estensioni sono installato, attivato 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 delle persone collaborano su un file e una di loro utilizza un componente aggiuntivo, viene installato per l'utente e abilitato per il file.

La seguente tabella riassume le differenze tra installato e abilitato. Tieni presente che quando testare 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 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 nel file è attivato un componente aggiuntivo Editor, modulo, presentazione o foglio di lavoro, onOpen() viene eseguito AuthMode.LIMITED. Se il componente aggiuntivo non è abilitato solo installata, onOpen() viene eseguito in AuthMode.NONE.

In AuthMode.NONE, un componente aggiuntivo non può eseguire determinate finché l'utente non interagisce con il componente aggiuntivo fare clic o eseguire 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 interrompono. L'unica opzione supportata è la guida.

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 supera la modalità di autorizzazione come proprietà authMode di Apps Script parametro evento, e; il valore di e.authMode corrisponde a una costante in Apps Script ScriptApp.AuthMode enum.

Le modalità di autorizzazione si applicano a tutti i metodi di esecuzione di Apps Script, ad esempio l'esecuzione dall'editor di script, da una voce di menu o da un Apps Script google.script.run chiamata. 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.

Ciclo di vita dell'autorizzazione di un componente aggiuntivo dell'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 è elencato nel menu Estensioni e inizia a rilevare il attivatori semplici onInstall(), onOpen() e onEdit(). Se un utente fa clic su un Voce di menu Estensioni, viene eseguito.

Il componente aggiuntivo Editor è installato

Quando un componente aggiuntivo Editor viene installato dallo store, La 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 onOpen() in esecuzione dipende dal fatto che un componente aggiuntivo installati o attivati.

Se un componente aggiuntivo crea soltanto un menu di base, la modalità non importa. 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();
}

Aggiungere voci di menu dinamiche basate su Apps Script memorizzato proprietà, per leggere i contenuti corrente o per eseguire altre attività avanzate, deve 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 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 una voce di menu Estensioni, Apps Script verifica innanzitutto se l'utente ha installato il componente aggiuntivo se non lo fa. 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 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 uno script di Google Apps 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 Apps Script servizi o oggetti associati, come PropertiesService, SpreadsheetApp o GmailApp.
3. Se un servizio viene utilizzato per scopi diversi dalla creazione degli elementi UI, rimuoverlo o includerlo in un blocco di commenti. Lascia solo questi metodi: .getUi(), .createMenu(), .addItem() e .addToUi(). Inoltre, trova e rimuovi tutti 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 Config (Configurazione) è Installato per l'utente corrente e il testo sotto la casella Configurazione indica Test in AuthMode.None

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

7. Se sono 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 Editor