Trigger per i componenti aggiuntivi Editor

I trigger Apps Script fanno sì che una funzione di script specificata (la funzione 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 viene attivato un trigger, viene creato un oggetto evento. Questa struttura JSON contiene i dettagli dell'evento verificatosi. Le informazioni nella struttura dell'oggetto evento sono organizzate in modo diverso in base al tipo di trigger.

Una volta creato l'oggetto evento, Apps Script lo trasmette come parametro alla funzione trigger. La funzione di trigger è una funzione di callback che devi implementare personalmente 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 all'apertura di un documento. In questo caso, implementi la funzione di attivazione 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 attivatori dei componenti aggiuntivi dell'editor

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

A differenza dei componenti aggiuntivi dell'editor, i componenti aggiuntivi di Google Workspace non possono utilizzare trigger semplici o installabili di Apps Script generici. Utilizzano invece attivatori progettati appositamente 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 ai corrispondenti oggetti evento:

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.	onInstall event object	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 I contenuti di un foglio vengono modificati o formattati.	Oggetto evento onChange di Fogli		Fogli
Form-submit 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 orario o a un intervallo specifici.	Oggetto evento basato sul tempo	Documenti Moduli Fogli Presentazioni

* L'evento di apertura per Google Moduli 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 trigger semplice può essere gestito invece da un trigger installabile.

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 dispone dell'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, formattazione o altre modifiche che non alterano i valori delle celle.

Limitazioni

I trigger semplici nei componenti aggiuntivi sono soggetti alle stesse limitazioni che regolano i trigger semplici in altri tipi di progetti Apps Script. Tieni particolarmente presenti queste limitazioni 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 la compilazione dei menu dei componenti aggiuntivi.
• In determinate circostanze, i componenti aggiuntivi Editor eseguono i trigger onOpen e onEdit semplici 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 eseguire altre azioni che richiedono autorizzazione, ad eccezione di quanto descritto 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 semplice funzione di attivazione.
• 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 trigger installabili con il servizio Apps Script 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 all'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 tuo componente aggiuntivo in modo da gestire gli errori per conto dell'utente nel miglior modo possibile.

I componenti aggiuntivi possono utilizzare i seguenti trigger installabili:

• I trigger installabili Open 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 Change vengono eseguiti quando un utente apporta una modifica a un foglio di lavoro, incluse le modifiche alla formattazione e al foglio di lavoro stesso (ad esempio l'aggiunta di una riga).

• I trigger installabili Form-submit vengono eseguiti quando viene inviata una risposta a un modulo Google.

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

• Attivatori basati sul tempo (chiamati anche attivatori di orologio) si attivano a un'ora specifica o ripetutamente a intervalli di tempo regolari.

Autorizzare i 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 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 aggiornasse il componente aggiuntivo per utilizzare nuovi servizi che richiedono un'autorizzazione aggiuntiva, l'autore 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 Apps Script, i trigger nei componenti aggiuntivi continuano a essere attivati anche se richiedono una nuova autorizzazione. Tuttavia, lo script non funziona se raggiunge una riga di codice che richiede un'autorizzazione che non ha. Per evitare questo problema, utilizza ScriptApp.getAuthorizationInfo per controllare l'accesso a parti di codice che sono cambiate tra le versioni del componente aggiuntivo.

Gli esempi seguenti mostrano la struttura consigliata da utilizzare nelle funzioni di trigger per evitare problemi di autorizzazione. La funzione di attivazione di esempio risponde a un evento di invio di un modulo 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.

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>

Limitazioni

Gli attivatori installabili nei componenti aggiuntivi sono soggetti alle stesse limitazioni che regolano gli attivatori installabili in altri tipi di progetti Apps Script.

Oltre a queste limitazioni, si applicano diverse limitazioni ai trigger installabili nei componenti aggiuntivi in particolare:

• 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 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 set separato di trigger.
• I componenti aggiuntivi possono creare trigger solo per il file in cui viene utilizzato il componente aggiuntivo. ovvero un componente aggiuntivo utilizzato nel 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. Spetta allo sviluppatore controllare e gestire i casi di errore in modo appropriato.
• Gli attivatori dei componenti aggiuntivi smettono di attivarsi 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 danneggiata allo store di componenti aggiuntivi.
• Le funzioni di attivazione dei componenti aggiuntivi vengono eseguite fino a quando non raggiungono il codice che utilizza un servizio non autorizzato, a quel punto si interrompono. Ciò è vero solo se il componente aggiuntivo è pubblicato; lo stesso trigger 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.