Trigger per componenti aggiuntivi Editor

I attivatori di Apps Script causano l'esecuzione di una funzione script specificata (la funzione trigger) ogni volta che si verifica un evento specificato. Solo alcuni eventi possono causare l'attivazione degli attivatori e ogni applicazione di Google Workspace supporta un insieme diverso di eventi.

Quando si attiva un attivatore, viene creato un oggetto evento. Questa struttura JSON contiene dettagli sull'evento che si è verificato. Le informazioni nella struttura dell'oggetto evento sono organizzate in modo diverso in base al tipo di attivatore.

Una volta creato l'oggetto evento, Apps Script lo passa come parametro alla funzione trigger. La funzione trigger è una funzione di callback che devi implementare autonomamente per eseguire le azioni appropriate per rispondere all'evento. Ad esempio, in un componente aggiuntivo dell'editor un attivatore viene utilizzato per creare voci di menu dei componenti aggiuntivi all'apertura di un documento. In questo caso, implementerai la funzione trigger onOpen(e) per creare le voci di menu necessarie per il componente aggiuntivo, possibilmente utilizzando i dati nell'oggetto evento.

Questa pagina fornisce linee guida sull'utilizzo dei trigger nei progetti dei componenti aggiuntivi dell'editor.

Tipi di attivatori dei componenti aggiuntivi Editor

Puoi utilizzare la maggior parte dei tipi di attivatori generici disponibili per i progetti Apps Script nei componenti aggiuntivi di Editor, inclusi attivatori semplici e la maggior parte degli attivatori installabili. L'insieme esatto di tipi di trigger disponibili dipende dall'applicazione che viene estesa.

La tabella seguente mostra i tipi di trigger semplici e installabili che possono essere utilizzati dai componenti aggiuntivi di Editor e fornisce i link agli oggetti evento corrispondenti:

Evento Oggetto evento Attivatori semplici Trigger installabili
Apri
Viene aperto un file dell'editor.		 Oggetto evento Documenti onOpen
Oggetto evento Moduli onOpen
Oggetto evento Fogli onOpen
Oggetto evento Presentazioni onOpen 		Documenti
Moduli*
Fogli
Presentazioni

function onOpen(e)

 Documenti
Moduli
Fogli
Installa
Il componente aggiuntivo è installato.		 Oggetto evento onInstall Documenti
Moduli
Fogli
Presentazioni

function onInstall(e)
Modifica
Il contenuto della cella del foglio di lavoro è cambiato.		 Oggetto evento Fogli onEdit Fogli

function onEdit(e)

 Fogli
Modifica
I contenuti di un foglio vengono modificati o formattati.		 Oggetto evento Fogli onChange Fogli
Invio di moduli
È stato inviato un modulo Google.		 Oggetto evento form-submit di Moduli
Oggetto evento Fogli form-submit 		Moduli
Fogli
A tempo (orologio)
L'attivatore si attiva a un orario o a un intervallo specificati.		 Oggetto evento a tempo Documenti
Moduli
Fogli
Presentazioni

* L'evento di apertura per Moduli Google non si verifica quando un utente apre un modulo per rispondere, ma piuttosto quando un editor apre il modulo per modificarlo.

Attivatori semplici nei componenti aggiuntivi

I trigger semplici utilizzano un insieme di nomi di funzioni riservati, non possono utilizzare i servizi che richiedono l'autorizzazione e vengono abilitati automaticamente per l'utilizzo. In alcuni casi, un semplice evento di trigger può essere gestito da un attivatore installabile.

Puoi aggiungere un trigger semplice a un componente aggiuntivo implementando semplicemente una funzione con uno dei seguenti nomi riservati:

  • onOpen(e) viene eseguito quando un utente apre un documento, un foglio di lavoro o una presentazione. onOpen(e) può essere eseguito anche quando un modulo viene aperto nell'editor (ma non quando si risponde al modulo). Viene eseguito solo se l'utente dispone dell'autorizzazione per modificare il file in questione e viene utilizzato più spesso per creare voci di menu.
  • onInstall(e) viene eseguito quando un utente installa un componente aggiuntivo. In genere onInstall(e) viene usato soltanto per chiamare onOpen(e); in questo modo, i menu dei componenti aggiuntivi vengono visualizzati subito dopo l'installazione senza che l'utente debba aggiornare la pagina.
  • onEdit(e) viene eseguito quando un utente modifica il valore di una cella in un foglio di lavoro. Questo attivatore non si attiva in risposta allo spostamento, alla formattazione o ad altre modifiche delle celle che non ne alterano i valori.

Restrizioni

I trigger semplici nei componenti aggiuntivi sono soggetti alle stesse limitazioni che regolano i semplici attivatori in altri tipi di progetti Apps Script. Presta particolare attenzione alle seguenti limitazioni durante la progettazione dei componenti aggiuntivi:

  • I trigger semplici non vengono eseguiti se un file viene aperto in modalità di sola lettura (visualizzazione o commento). Questo comportamento impedisce il completamento dei menu dei componenti aggiuntivi.
  • In alcuni casi, i componenti aggiuntivi Editor eseguono i loro semplici trigger onOpen(e) e onEdit(e) in modalità senza autorizzazione. Questa modalità presenta alcune complicazioni aggiuntive, come descritto nel modello di autorizzazione dei componenti aggiuntivi.
  • I trigger semplici non possono utilizzare i servizi o eseguire altre azioni che richiedono l'autorizzazione, ad eccezione di quanto indicato nel modello di autorizzazione dei componenti aggiuntivi.
  • Gli attivatori semplici non possono essere eseguiti per più di 30 secondi. Fai attenzione a ridurre al minimo la quantità di elaborazione eseguita in una semplice funzione di trigger.
  • I trigger semplici sono soggetti ai limiti di quota dei trigger di Apps Script.

Trigger installabili nei componenti aggiuntivi

I componenti aggiuntivi possono creare e modificare in modo programmatico i trigger installabili con il servizio Apps Script Script. I trigger installabili per i componenti aggiuntivi non possono essere creati manualmente. A differenza dei trigger semplici, quelli installabili possono utilizzare i servizi che richiedono l'autorizzazione.

I trigger installabili nei componenti aggiuntivi non inviano email di errore all'utente quando riscontra errori, poiché nella maggior parte dei casi un utente non è in grado di risolvere il problema. Per questo motivo, se possibile, devi progettare il tuo componente aggiuntivo in modo da gestire correttamente gli errori per conto dell'utente.

I componenti aggiuntivi possono utilizzare i seguenti trigger installabili:

  • I trigger installabili aperti vengono eseguiti quando un utente apre un documento, un foglio di lavoro o quando un modulo viene aperto nell'editor (ma non quando si risponde al modulo).
  • I trigger installabili Modifica vengono eseguiti quando un utente modifica il valore di una cella di un foglio di lavoro. Questo attivatore non si attiva in risposta alla formattazione o ad altre modifiche che non alterano i valori delle celle.
  • Gli attivatori installabili Modifica vengono eseguiti quando un utente apporta qualsiasi modifica a un foglio di lavoro, incluse modifiche di formattazione e modifiche al foglio di lavoro stesso (ad esempio l'aggiunta di una riga).

  • Gli attivatori installabili Form-submit vengono eseguiti quando viene inviata una risposta di un modulo Google.

  • Gli attivatori basati sul tempo (chiamati anche trigger di orologio) si attivano in un orario specifico o ripetutamente in un intervallo di tempo regolare.

Autorizzazione dei trigger installabili

Normalmente, se uno sviluppatore aggiorna un componente aggiuntivo per utilizzare nuovi servizi che richiedono un'autorizzazione aggiuntiva, agli utenti viene chiesto di autorizzare nuovamente il componente aggiuntivo la volta successiva che lo utilizzano.

Tuttavia, i componenti aggiuntivi che utilizzano trigger incontrano verifiche di autorizzazione speciali. Immagina un componente aggiuntivo che utilizza un trigger per monitorare gli invii dei moduli: un autore del modulo potrebbe autorizzarlo la prima volta che lo utilizza e poi lasciarlo in esecuzione per mesi o anni senza mai riaprire il modulo. Se lo sviluppatore del componente aggiuntivo aggiorna il componente aggiuntivo in modo da utilizzare nuovi servizi che richiedono un'autorizzazione aggiuntiva, l'autore del modulo non vedrà mai la finestra di dialogo di nuova autorizzazione perché non ha mai riaperto il modulo e il componente aggiuntivo smetterà di funzionare.

A differenza degli attivatori nei normali progetti Apps Script, gli attivatori nei componenti aggiuntivi continuano a essere attivati anche se richiedono una nuova autorizzazione. Tuttavia, lo script continua a non riuscire se raggiunge una riga di codice che richiede un'autorizzazione che lo script non possiede. Per evitare questa situazione, gli sviluppatori possono utilizzare il metodo ScriptApp.getAuthorizationInfo() per limitare l'accesso alle parti di codice che sono state modificate tra le versioni pubblicate del componente aggiuntivo.

Di seguito è riportato un esempio della struttura consigliata da utilizzare nelle funzioni di trigger per evitare inconvenienti di autorizzazione. La funzione di attivazione di esempio risponde a un evento form-submit all'interno di un componente aggiuntivo di Fogli Google e, se è necessaria una nuova autorizzazione, invia all'utente del componente aggiuntivo un'email di avviso utilizzando HTML basato su modelli.

Codice.gs

trigger/modulo/Codice.gs
/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

autorizzazioneemail.html

trigger/modulo/AuthorizationEmail.html
<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Restrizioni

I trigger installabili nei componenti aggiuntivi sono soggetti alle stesse limitazioni che regolano i trigger installabili in altri tipi di progetti Apps Script.

Oltre a queste limitazioni, vengono applicate diverse limitazioni agli attivatori installabili nei componenti aggiuntivi, in particolare:

  • Ogni componente aggiuntivo può avere un solo attivatore di ogni tipo, per utente e per documento. Ad esempio, in un determinato foglio di lavoro, un determinato utente può avere un solo attivatore di modifica, anche se può avere anche un attivatore di invio modulo o un attivatore a tempo nello stesso foglio di lavoro. Un altro utente con accesso allo stesso foglio di lavoro potrebbe avere il proprio insieme separato di attivatori.
  • I componenti aggiuntivi possono creare solo gli attivatori del file in cui vengono utilizzati. Ciò significa che un componente aggiuntivo utilizzato in Documenti Google A non può creare un trigger per monitorare l'apertura di Documenti Google.
  • I trigger basati sul tempo non possono essere eseguiti più di una volta all'ora.
  • I componenti aggiuntivi non inviano automaticamente un'email all'utente quando il codice eseguito da un trigger installabile genera un'eccezione. Spetta allo sviluppatore verificare e gestire agevolmente i casi di errore.
  • Gli attivatori dei componenti aggiuntivi non vengono più attivati in una delle seguenti situazioni:
    • Se il componente aggiuntivo viene disinstallato dall'utente,
    • Se il componente aggiuntivo è disabilitato in un documento (se viene riattivato, l'attivatore diventa di nuovo operativo) oppure
    • Se lo sviluppatore annulla la pubblicazione del componente aggiuntivo o invia una versione non funzionante allo store dei componenti aggiuntivi.
  • Le funzioni di trigger dei componenti aggiuntivi vengono eseguite finché non raggiungono il codice che utilizza un servizio non autorizzato, dopodiché vengono interrotte. Questo vale solo se il componente aggiuntivo è stato pubblicato. Lo stesso attivatore in un normale progetto Apps Script o in un componente aggiuntivo non pubblicato non viene eseguito se una parte dello script richiede l'autorizzazione.
  • I trigger installabili sono soggetti ai limiti di quota dei trigger di Apps Script.