Autorizzazione componente aggiuntivo Editor

Nella maggior parte dei casi, è necessario autorizzare un componente aggiuntivo prima di poterlo utilizzare. Per molti progetti Apps Script come le app web, l'autorizzazione è semplice: il progetto di script richiede le autorizzazioni mancanti di cui ha bisogno quando provi a utilizzarla. Dopo aver ricevuto l'autorizzazione, puoi utilizzare il progetto di script liberamente. Tutti gli utenti che utilizzano il progetto di script lo autorizzano separatamente.

Il modello di autorizzazione per i componente aggiuntivo di editor è più complesso. Questi componenti aggiuntivi funzionano sui file che si trovano su Google Drive, file che possono essere condivisi con altri utenti, quindi devi creare componenti aggiuntivi per l'editor tenendo presenti le diverse modalità di autorizzazione. Nelle applicazioni dell'editor di Google Workspace è disponibile anche un menu Componenti aggiuntivi nelle UI che viene completato dai componenti aggiuntivi installati, anche se non hai ancora autorizzato questi componenti. Ciò aggiunge ulteriore complessità al modello di autorizzazione.

Modello di autorizzazione

Le due proprietà dei componente aggiuntivo di Editor li rendono particolarmente facili da condividere e utilizzare:

  • Quando ricevi un componente aggiuntivo dell'editor dallo store, lo vedrai nel menu Componenti aggiuntivi per ogni documento che apri o crei. I collaboratori su quei documenti vedranno il componente aggiuntivo tranne nei documenti in cui lo utilizzi effettivamente.
  • Dopo aver utilizzato un componente aggiuntivo dell'editor in un documento, i tuoi collaboratori lo visualizzano anche nel menu Componenti aggiuntivi, ma solo per quel documento (a meno che non lo abbiano anche installato).

Questo modello di condivisione risulta naturale per la maggior parte degli utenti. Tuttavia, poiché un componente aggiuntivo di un editor esegue automaticamente la sua funzione onOpen(e) per aggiungere voci di menu all'apertura di un documento, il comportamento sopra descritto complica la gestione delle regole di autorizzazione di Apps Script. Dopo tutto, gli utenti non sarebbero a loro agio con il componente aggiuntivo che accede ai dati personali ogni volta che aprono un documento. Questa guida dovrebbe aiutarti a capire cosa può fare il tuo codice e quando.

Installate e attivate

Se un componente aggiuntivo di Editor nel menu è in uno (o entrambi) dei due stati: Installato e Attivato. Un componente aggiuntivo dell'editor viene installato per un determinato utente dopo aver scelto il componente aggiuntivo nello store e autorizzalo ad accedere ai suoi dati di Google. Un componente aggiuntivo, invece, viene attivato in un determinato documento quando viene utilizzato da chiunque. Se due persone collaborano su un documento e una di loro utilizza un componente aggiuntivo, questo viene installato per l'utente e abilitato per il documento.

La tabella seguente riepiloga i due stati. Tieni presente che quando esegui il test di uno script come componente aggiuntivo puoi scegliere di eseguire il test in uno o in entrambi gli stati.

Installato Attivato
Si applica a Utente Documento
Causato da Ricevere un componente aggiuntivo dallo store Ottenere un componente aggiuntivo dallo store mentre utilizzi il documento oppure
Utilizzare un componente aggiuntivo installato in precedenza in quel documento
Menu visibile a Solo l'utente in tutti i documenti che apre o crea Tutti i collaboratori sul documento
onOpen(e) in esecuzione AuthMode.NONE (a meno che non sia abilitato anche in questo caso AuthMode.LIMITED) AuthMode.LIMITED

Modalità di autorizzazione

Un componente aggiuntivo di Editor esegue automaticamente la sua funzione onOpen(e) per aggiungere voci di menu all'apertura di un documento. Tuttavia, per proteggere i dati degli utenti, Apps Script limita le operazioni eseguibili con la funzione onOpen(e). Se il componente aggiuntivo non è stato utilizzato nel documento corrente, queste limitazioni diventano più gravi.

In particolare, gli stati installati e attivati determinano la modalità di autorizzazione in cui viene eseguita la funzione onOpen(e). Apps Script trasmette la modalità di autorizzazione come proprietà authMode del parametro evento Apps Script e; il valore di e.authMode corrisponde a una costante nell'enumerazione di Script di Apps Script.

Se un componente aggiuntivo dell'editor è attivato nel documento corrente, onOpen(e) viene eseguito in AuthMode.LIMITED. Se il componente aggiuntivo non è attivato e viene installato solo, onOpen(e) viene eseguito in AuthMode.NONE.

Il concetto di modalità di autorizzazione si applica a tutte le esecuzioni di Apps Script (come quelle eseguite dall'editor dello script, da una voce di menu o da una chiamata di Apps Script google.script.run), sebbene la proprietà e.authMode possa essere controllata solo se lo script viene eseguito come risultato di un trigger come onOpen(e), onEdit(e) o onInstall(e). Le funzioni personalizzate in Fogli Google utilizzano la propria modalità di autorizzazione, AuthMode.CUSTOM_FUNCTION, che è simile a LIMITED, ma prevede restrizioni leggermente diverse. Il resto del tempo, gli script vengono eseguiti in AuthMode.FULL, come descritto nella tabella sottostante.

NONE LIMITED CUSTOM_FUNCTION FULL
Si verifica per onOpen(e) (se l'utente ha installato un componente aggiuntivo ma non lo ha attivato nel documento) onOpen(e) (tutte le altre volte)
onEdit(e) (solo in Fogli)
Funzioni personalizzate In tutti gli altri momenti, inclusi:
Trigger installabili
onInstall(e)
google.script.run
Accesso ai dati utente Solo local Solo local Solo local
Accesso al documento No Sì: sola lettura
Accesso all'interfaccia utente Aggiungere voci di menu Aggiungere voci di menu No
Accesso a Properties No
Accesso a Jdbc, UrlFetch No No
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

Il ciclo di vita completo

Se un componente aggiuntivo è installato per l'utente corrente o abilitato, nel documento corrente viene caricato nel documento e viene visualizzato nel menu Componenti aggiuntivi e inizia ad ascoltare i semplici attivatori onInstall(e), onOpen(e) e onEdit(e). Se un utente fa clic su una delle voci di menu del componente aggiuntivo, viene eseguito.

Installazione in corso…

Quando un componente aggiuntivo dell'editor viene installato dallo store, la sua funzione onInstall(e) viene eseguita in AuthMode.FULL. Questo consente al componente aggiuntivo di eseguire una routine di configurazione complessa, ma è importante utilizzare anche onInstall(e) per creare voci di menu, dal momento che il documento è già aperto e quindi la tua funzione onOpen(e) non è stata eseguita. Per comodità, puoi chiamare onOpen(e) dal numero onInstall(e), come mostrato in questo esempio:

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

Apertura

Quando viene aperto un documento, vengono caricati tutti i componenti aggiuntivi dell'editor che l'utente corrente ha installato o che un collaboratore ha attivato nel documento e richiama ognuna delle funzioni onOpen(e). La modalità di autorizzazione in cui viene eseguito onOpen(e) dipende dal fatto che un componente aggiuntivo sia installato o abilitato.

Se un componente aggiuntivo crea solo un menu di base, la modalità non è importante. Questo esempio mostra l'aspetto di un onOpen(e) semplice:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Tuttavia, se vuoi aggiungere voci di menu dinamiche in base alle proprietà Apps Script archiviate, leggere i contenuti del documento corrente o eseguire altre attività avanzate, devi rilevare la modalità di autorizzazione e gestirla in modo appropriato. Questo esempio mostra l'aspetto che potrebbe avere una funzione onOpen(e) avanzata, modificandone il comportamento 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();
}

In esecuzione

Quando un utente fa clic su una delle voci di menu di un componente aggiuntivo, Apps Script controlla innanzitutto se l'utente ha installato il componente aggiuntivo e gli chiede di eseguire questa operazione. Se l'utente ha autorizzato il componente aggiuntivo, lo script esegue la funzione che corrisponde alla voce di menu in AuthMode.FULL. Il componente aggiuntivo viene attivato anche nel documento, se non lo è già.