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 un attivatore si attiva, 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 passa 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

Nei componenti aggiuntivi dell'editor puoi utilizzare la maggior parte dei tipi di trigger generici disponibili per i progetti Apps Script, inclusi i trigger semplici e la maggior parte dei trigger installabili. L'insieme esatto di tipi di trigger disponibili dipende dall'applicazione in fase di estensione.

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.		 onInstall event object Documenti
Moduli
Fogli
Presentazioni

function onInstall(e)
Modifica
Il contenuto della cella del foglio di lavoro è stato 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 di invio modulo di Moduli
Oggetto evento di invio modulo di Fogli 		Moduli
Fogli
Basato sul tempo (orologio)
L'attivatore si attiva 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 lo apre 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 semplice trigger a un componente aggiuntivo implementando 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. Di solito onInstall(e) viene utilizzato solo per chiamare onOpen(e); in questo modo, i menu dei componenti aggiuntivi vengono visualizzati immediatamente dopo l'installazione senza richiedere all'utente di aggiornare la pagina.
  • onEdit(e) 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.

Restrizioni

I trigger semplici nei componenti aggiuntivi sono soggetti alle stesse limitazioni che regolano i trigger semplici in altri tipi di progetti Apps Script. Presta particolare attenzione a queste 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 popolamento dei menu dei componenti aggiuntivi.
  • In determinate circostanze, i componenti aggiuntivi Editor eseguono i trigger onOpen(e) e onEdit(e) semplici 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 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. 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 gli attivatori installabili con il servizio Script di Apps Script. Gli attivatori installabili dei componenti aggiuntivi non possono essere creati manualmente. A differenza dei semplici trigger, 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, devi progettare il componente aggiuntivo in modo da gestire gli errori per conto dell'utente, se 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 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 qualsiasi 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 di Moduli Google.

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

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 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 quest'ultimo 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 viene eseguito se raggiunge una riga di codice che richiede un'autorizzazione che non ha. Per evitare questa situazione, gli sviluppatori possono utilizzare il metodo ScriptApp.getAuthorizationInfo() per controllare l'accesso alle parti di codice che sono cambiate tra le versioni pubblicate del componente aggiuntivo.

Di seguito è riportato un esempio della 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 Google Sheets 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
/**
 * 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
<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

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 e 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 del 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 vengono utilizzati. 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 verificare e gestire i casi di errore in modo appropriato.
  • I trigger 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 a funzionare) o
    • Se lo sviluppatore annulla la pubblicazione del componente aggiuntivo o invia una versione danneggiata al negozio di componenti aggiuntivi.
  • Le funzioni di attivazione dei componenti aggiuntivi vengono eseguite finché non raggiungono 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 Apps Script o 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.