Trigger per i componenti aggiuntivi Editor

I trigger di Apps Script fanno sì che una funzione di script specificata (la funzione di trigger) venga eseguita ogni volta che si verifica un evento specificato. Solo determinati eventi possono attivare i trigger e ogni applicazione Google Workspace supporta un insieme diverso di eventi.

Quando un trigger viene attivato, viene creato un oggetto evento. Questa struttura JSON contiene i dettagli dell'evento che si è verificato. Le informazioni nella struttura dell'oggetto evento sono organizzate in modo diverso a seconda del tipo di trigger.

Una volta creato l'oggetto evento, Apps Script lo passa come parametro alla funzione di trigger. La funzione di trigger è una funzione di callback che devi implementare tu stesso per intraprendere le azioni appropriate per rispondere all'evento. Ad esempio, in un componente aggiuntivo dell'editor viene utilizzato un trigger per creare voci di menu del componente aggiuntivo quando viene aperto un documento. In questo caso, implementi la funzione di trigger onOpen(e) per creare le voci di menu di cui ha bisogno il componente aggiuntivo, possibilmente utilizzando i dati nell'oggetto evento.

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

Tipi di trigger dei componenti aggiuntivi dell'editor

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

A differenza dei componenti aggiuntivi di Editor, i componenti aggiuntivi di Google Workspace non possono utilizzare trigger semplici o installabili di Apps Script generici. Al contrario, utilizzano trigger progettati specificamente per i componenti aggiuntivi di Google Workspace. Per saperne di più, vedi Trigger dei componenti aggiuntivi di Google Workspace.

La tabella seguente mostra i tipi di trigger semplici e installabili che i componenti aggiuntivi dell'editor possono utilizzare e fornisce link agli oggetti evento corrispondenti:

Evento	Oggetto evento	Trigger semplici	Trigger installabili
Apri Viene aperto un file dell'editor.	Oggetto evento onOpen di Documenti Oggetto evento onOpen di Moduli Oggetto evento onOpen di Fogli Oggetto evento onOpen di Presentazioni	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 viene modificato.	Oggetto evento onEdit di Fogli	Fogli function onEdit(e)	Fogli
Modifica Il contenuto di un foglio viene modificato o formattato.	Oggetto evento onChange di Fogli		Fogli
Invio modulo Viene inviato un modulo Google.	Oggetto evento form-submit di Moduli Oggetto evento form-submit di Fogli		Moduli Fogli
Basato sul tempo (orologio) Il trigger viene attivato a un'ora o a un intervallo specificato.	Oggetto evento basato sul tempo	Documenti Moduli Fogli Presentazioni

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

Trigger semplici nei componenti aggiuntivi

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

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

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

Restrizioni

I trigger semplici nei componenti aggiuntivi sono soggetti alle stesse restrizioni che regolano i trigger semplici in altri tipi di progetti di Apps Script. Tieni presente queste restrizioni in particolare quando progetti i 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 popolamento dei menu dei componenti aggiuntivi.
• In determinate circostanze, i componenti aggiuntivi dell'editor eseguono i trigger semplici onOpen e onEdit in modalità senza autorizzazione. Questa modalità presenta complicazioni come descritto nel modello di autorizzazione dei componenti aggiuntivi.
• I trigger semplici non possono utilizzare servizi o intraprendere altre azioni che richiedono l'autorizzazione, ad eccezione di quanto indicato nel modello di autorizzazione dei componenti aggiuntivi.
• I trigger semplici non possono essere eseguiti per più di 30 secondi. Riduci al minimo la quantità di elaborazione eseguita in una funzione di trigger semplice.
• I trigger semplici sono soggetti ai limiti di quota dei trigger di Apps Script quota limits.

Trigger installabili nei componenti aggiuntivi

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

I trigger installabili nei componenti aggiuntivi non inviano email di errore a l'utente quando si verificano errori, poiché nella maggior parte dei casi un utente non è in grado di risolvere il problema. Per questo motivo, dovresti progettare il componente aggiuntivo in modo che gestisca gli errori in modo corretto per conto dell'utente, ove possibile.

I componenti aggiuntivi possono utilizzare i seguenti trigger installabili:

• I trigger installabili Apri 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 in un foglio di lavoro. Questo trigger non viene attivato in risposta alla formattazione o ad altre modifiche che non alterano i valori delle celle.
• I trigger installabili Modifica vengono eseguiti quando un utente apporta modifiche a un foglio di lavoro, incluse le modifiche di formattazione e le modifiche al foglio di lavoro stesso (ad esempio l'aggiunta di una riga).

• I trigger installabili Invio modulo vengono eseguiti quando viene inviata una risposta di Moduli Google.

  Esistono due versioni dei trigger di invio modulo: una per Fogli (dove vengono raccolte le risposte del modulo) e una per Moduli Google. L' oggetto evento passato a una funzione di trigger di invio modulo di Fogli è più semplice e restituisce i valori di risposta in array semplici. L' oggetto evento passato a una funzione di trigger di invio modulo di Moduli fornisce maggiori informazioni, contenute in un FormResponse oggetto.

• I trigger basati sul tempo (chiamati anche trigger di orologio) vengono attivati a un'ora specifica o ripetutamente a intervalli di tempo regolari.

Autorizzare i trigger installabili

In genere, 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 i trigger presentano sfide di autorizzazione speciali. Immagina un componente aggiuntivo che utilizza un trigger per monitorare gli invii di moduli: un creatore di moduli potrebbe autorizzare il componente aggiuntivo la prima volta che lo utilizza, quindi lasciarlo in esecuzione per mesi o anni senza mai riaprire il modulo. Se lo sviluppatore del componente aggiuntivo dovesse aggiornare il componente aggiuntivo per utilizzare nuovi servizi che richiedono un'autorizzazione aggiuntiva, il creatore del modulo non vedrebbe mai la finestra di dialogo di riautorizzazione perché non ha mai riaperto il modulo e il componente aggiuntivo smetterebbe di funzionare.

A differenza dei trigger nei normali progetti di Apps Script, i trigger nei componenti aggiuntivi continuano ad attivarsi anche se richiedono una riautorizzazione. Tuttavia, lo script non riesce comunque se raggiunge una riga di codice che richiede un'autorizzazione che non ha. Per evitare questo problema, utilizza ScriptApp.getAuthorizationInfo per limitare l'accesso alle parti di codice che sono state modificate tra le versioni di componente aggiuntivo.

Gli esempi seguenti mostrano la struttura consigliata da utilizzare nelle funzioni di trigger per evitare problemi di autorizzazione. La funzione di trigger di esempio risponde a un evento di invio modulo all'interno di un componente aggiuntivo di Fogli Google e, se è richiesta la riautorizzazione, invia all'utente del componente aggiuntivo un'email di avviso utilizzando HTML con modelli.

Code.gs

triggers/form/Code.gs

Visualizza su GitHub

/**
 * 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.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html

Visualizza su GitHub

<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 restrizioni che regolano i trigger installabili in altri tipi di progetti di Apps Script.

Oltre a queste restrizioni, si applicano diverse restrizioni specifiche ai trigger installabili nei componenti aggiuntivi:

• Ogni componente aggiuntivo può avere un solo trigger di ogni tipo, per utente, per documento. Ad esempio, in un determinato foglio di lavoro, un determinato utente può avere un solo trigger di modifica, anche se l'utente potrebbe avere anche un trigger di invio modulo o un trigger basato sul tempo nello stesso foglio di lavoro. Un altro utente con accesso allo stesso foglio di lavoro potrebbe avere il proprio insieme separato di trigger.
• I componenti aggiuntivi possono creare trigger solo per il file in cui viene utilizzato il componente aggiuntivo. Ciò significa che un componente aggiuntivo utilizzato in Documento Google A non può creare un trigger per monitorare l'apertura del Documento Google B.
• 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. Lo sviluppatore deve verificare e gestire i casi di errore in modo corretto.
• I trigger dei componenti aggiuntivi smettono di essere attivati in una delle seguenti situazioni:
  • Se il componente aggiuntivo viene disinstallato dall'utente,
  • Se il componente aggiuntivo è disattivato in un documento (se viene riattivato, il trigger torna operativo) o
  • Se lo sviluppatore annulla la pubblicazione del componente aggiuntivo o invia una versione non funzionante al componente aggiuntivo store.
• Le funzioni di trigger dei componenti aggiuntivi vengono eseguite fino a raggiungere il codice che utilizza un servizio non autorizzato, a quel punto si interrompono. Questo vale solo se il componente aggiuntivo è pubblicato; lo stesso trigger in un normale progetto di Apps Script o in un componente aggiuntivo non pubblicato non viene eseguito affatto se una parte dello script richiede l'autorizzazione.
• I trigger installabili sono soggetti ai limiti di quota dei trigger di Apps Script .