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 L'opzione Componenti aggiuntivi dell'Editor è più complessa 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 in Google Drive che può essere condiviso 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 qual è il tuo codice può fare 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.

• Viene installato un componente aggiuntivo per un determinato all'utente dopo che loro o il loro amministratore lo hanno ottenuto Google Workspace Marketplace e autorizzarlo ad accedere ai propri dati di Google.
• Un componente aggiuntivo viene attivato in un documento, un modulo una presentazione o un foglio di lavoro quando qualcuno 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 tabella seguente riassume le differenze tra i dispositivi installati e abilitati. 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 dell'editor viene eseguita automaticamente quando un utente apre un documento, un modulo, una presentazione o un foglio di lavoro. Per proteggere gli utenti , Apps Script limita ciò che La funzione onOpen() può fare. 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 le tue il componente aggiuntivo prova a usare questi servizi in onOpen(), onInstall(), o in ambito globale, le autorizzazioni non vanno a buon fine e altre chiamate, come riempire i menu, fermarti. L'unica opzione supportata è la guida.

Per eseguire chiamate di servizio limitate, devi utilizzare l'autorizzazione AuthMode.FULL . Funzioni di interazione dell'utente, come fare clic su un'opzione di menu vengono eseguite solo in questa modalità. Dopo l'esecuzione del codice in modalità AuthMode.FULL, 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(). Funzioni personalizzate in Fogli Google usano la propria modalità di autorizzazione, AuthMode.CUSTOM_FUNCTION, che è simile a LIMITED, ma ha limitazioni leggermente diverse. Per tutti in altri casi, gli script vengono eseguiti in AuthMode.FULL, come descritto .

Ciclo di vita dell'autorizzazione di un componente aggiuntivo dell'editor

Quando viene installato un componente aggiuntivo per l'utente corrente o abilitato nel file corrente, il componente aggiuntivo viene caricato per il documento, il modulo, la presentazione o foglio di lavoro quando il file è 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, può eseguire una routine di configurazione complessa. Dovresti inoltre usa 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. 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, questo viene caricato ogni Componente aggiuntivo dell'editor che ha installato o che qualsiasi collaboratore ha abilitato nel file e chiama ciascuna delle loro funzioni di 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. Nell'esempio seguente viene mostrata 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 basata sulla 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 le barre laterali o le finestre di dialogo durante l'esecuzione in AuthMode.LIMITED. Puoi utilizzare le voci del 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 se non lo fa. Se l'utente ha autorizzato lo script esegue la funzione corrisponde alla voce di menu in AuthMode.FULL. La attivato nel documento, nel modulo una presentazione o un 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 vi interagisce.

Per rimuovere o riorganizzare una chiamata di servizio che causa errori di autorizzazione in AuthMode.NONE, prova a eseguire queste 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 che si trovano al di fuori di una funzione.
4. Identificare le funzioni che potrebbero contenere le righe di codice commentate o rimosse nel passaggio precedente, in particolare quelli che usano le informazioni che producono, e trasferire le chiamate ai servizi alle funzioni che ne hanno bisogno. Riordina o riscrivi del codebase per supportare le 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 è visibile 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