Déclencheurs installables

Comme les déclencheurs simples, les déclencheurs installables permettent à Google Apps Script d'exécuter automatiquement une fonction lorsqu'un événement spécifique se produit, par exemple lorsqu'un document est ouvert. Toutefois, les déclencheurs installables offrent plus de flexibilité que les déclencheurs simples : ils peuvent appeler des services qui nécessitent une autorisation, ils proposent plusieurs types d'événements supplémentaires, y compris des déclencheurs temporels (horloge), et ils peuvent être contrôlés de manière programmatique. Pour les déclencheurs simples et installables, Apps Script transmet à la fonction déclenchée un objet d'événement qui contient des informations sur le contexte dans lequel l'événement s'est produit.

Pour en savoir plus sur l'utilisation des déclencheurs dans les modules complémentaires, consultez Déclencheurs pour les modules complémentaires Google Workspace.

Restrictions

Bien que les déclencheurs installables offrent plus de flexibilité que les déclencheurs simples, ils sont toujours soumis à plusieurs restrictions :

  • Ils ne s'exécutent pas si un fichier est ouvert en mode lecture seule (affichage ou commentaire). Pour les scripts autonomes, les utilisateurs doivent au moins disposer d'un accès en lecture au fichier de script pour que les déclencheurs s'exécutent correctement.

  • Les exécutions de script et les requêtes API n'entraînent pas l'exécution des déclencheurs. Par exemple, l'appel FormResponse.submit() pour envoyer une nouvelle réponse de formulaire n'entraîne pas l'exécution du déclencheur d'envoi du formulaire.

    Form.submitGrades() constitue une exception à cette restriction. Si votre code utilise un déclencheur onFormSubmit, l'appel de Form.submitGrades() déclenche la condition onFormSubmit et provoque une boucle infinie. Pour éviter la boucle infinie, ajoutez du code qui vérifie si des notes existent déjà avant d'appeler submitGrades().

  • Les déclencheurs installables s'exécutent toujours sous le compte de la personne qui les a créés. Par exemple, si vous créez un déclencheur d'ouverture installable, il s'exécute lorsque votre collègue ouvre le document (s'il dispose d'un accès en modification), mais il s'exécute en tant que votre compte. Cela signifie que si vous créez un déclencheur pour envoyer un e-mail lorsqu'un document est ouvert, l'e-mail est toujours envoyé depuis votre compte, et pas nécessairement depuis le compte qui a ouvert le document. Toutefois, vous pouvez créer un déclencheur installable pour chaque compte, ce qui entraîne l'envoi d'un e-mail depuis chaque compte.

  • Un compte donné ne peut pas voir les déclencheurs installés à partir d'un deuxième compte, même si le premier compte peut toujours activer ces déclencheurs.

  • Les déclencheurs installables sont soumis aux limites de quota des déclencheurs Apps Script .

Déclencheurs temporels

Un déclencheur temporel (également appelé déclencheur d'horloge) est semblable à une tâche Cron sous Unix. Les déclencheurs temporels permettent aux scripts de s'exécuter à une heure spécifique ou à un intervalle récurrent, aussi souvent que toutes les minutes ou aussi rarement qu'une fois par mois. (Un module complémentaire peut utiliser un déclencheur temporel au maximum une fois par heure.) L'heure peut être légèrement aléatoire. Par exemple, si vous créez un déclencheur récurrent à 9h, Apps Script choisit une heure entre 9h et 10h, puis conserve cette heure de manière cohérente d'un jour à l'autre afin que 24 heures s'écoulent avant que le déclencheur ne se déclenche à nouveau.

Déclencheurs basés sur les événements

Les déclencheurs installables basés sur les événements sont conceptuellement semblables aux déclencheurs simples tels que onOpen(), mais ils peuvent répondre à des événements supplémentaires et se comportent différemment.

Par exemple, le déclencheur d'ouverture installable pour Google Sheets s'active chaque fois que la feuille de calcul est ouverte par un utilisateur disposant d'un accès en modification, tout comme le déclencheur simple onOpen(). Toutefois, la version installable peut appeler des services qui nécessitent une autorisation. La version installable s'exécute avec l'autorisation de l'utilisateur qui a créé le déclencheur, même si un autre utilisateur disposant d'un accès en modification ouvre la feuille de calcul.

Il existe plusieurs déclencheurs installables pour les applications Google Workspace :

  • Un déclencheur d'ouverture installable s'exécute lorsqu'un utilisateur ouvre une feuille de calcul, un document ou un formulaire qu'il est autorisé à modifier.
  • Un déclencheur de modification installable s'exécute lorsqu'un utilisateur modifie une valeur dans une feuille de calcul.
  • Un déclencheur de modification installable s'exécute lorsqu'un utilisateur modifie la structure d'une feuille de calcul elle-même, par exemple en ajoutant une feuille ou en supprimant une colonne.
  • Un déclencheur d'envoi de formulaire installable s'exécute lorsqu'un utilisateur répond à un formulaire. Il existe deux versions du déclencheur d'envoi de formulaire : une pour Google Forms et une pour Sheets si le formulaire est envoyé à une feuille de calcul.
  • Un déclencheur d'événement d'agenda installable s'exécute lorsque les événements d'agenda d'un utilisateur sont mis à jour (créés, modifiés ou supprimés).

Les déclencheurs installables sont disponibles dans les scripts autonomes et liés. Par exemple, un script autonome peut créer de manière programmatique un déclencheur installable pour un fichier Google Sheets arbitraire en appelant TriggerBuilder.forSpreadsheet(key) et en transmettant l'ID de la feuille de calcul.

Gérer les déclencheurs manuellement

Pour créer manuellement un déclencheur installable dans l'éditeur de script, procédez comme suit :

  1. Ouvrez votre projet Apps Script.
  2. À gauche, cliquez sur Déclencheurs .
  3. En bas à droite, cliquez sur Ajouter un déclencheur.
  4. Sélectionnez et configurez le type de déclencheur que vous souhaitez créer.
  5. Cliquez sur Enregistrer.

Gérer les déclencheurs de manière programmatique

Créez et supprimez des déclencheurs de manière programmatique avec le service Script. Commencez par appeler ScriptApp.newTrigger(functionName), qui renvoie un TriggerBuilder.

L'exemple suivant montre comment créer deux déclencheurs temporels : un qui se déclenche toutes les six heures et un qui se déclenche tous les lundis à 9h (dans le fuseau horaire défini pour votre script).

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger("myFunction")
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.MONDAY)
    .atHour(9)
    .create();
}

L'exemple suivant montre comment créer un déclencheur d'ouverture installable pour une feuille de calcul. Contrairement à un déclencheur onOpen() simple, le script du déclencheur installable n'a pas besoin d'être lié à la feuille de calcul. Pour créer ce déclencheur à partir d'un script autonome, remplacez SpreadsheetApp.getActive() par un appel à SpreadsheetApp.openById(id).

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();
}

Pour modifier de manière programmatique un déclencheur installable existant, vous devez le supprimer et en créer un. Si vous avez déjà stocké l'ID d'un déclencheur, supprimez-le en transmettant l'ID en tant qu'argument à la fonction suivante.

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Avant de créer un déclencheur, vérifiez que la fonction associée dispose de toutes les autorisations OAuth nécessaires.

Erreurs dans les déclencheurs

Lorsqu'un déclencheur installable se déclenche, mais que la fonction génère une exception ou ne s'exécute pas correctement, aucun message d'erreur ne s'affiche à l'écran. En effet, lorsqu'un déclencheur temporel s'exécute ou qu'un autre utilisateur active votre déclencheur d'envoi de formulaire, vous n'êtes peut-être même pas devant votre ordinateur.

Apps Script envoie alors un e-mail semblable à celui-ci :

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

L'e-mail inclut un lien permettant de désactiver ou de reconfigurer le déclencheur. Si le script est lié à un fichier Google Sheets, Docs ou Forms file, l'e-mail inclut également un lien vers ce fichier. Ces liens vous permettent de désactiver le déclencheur ou de modifier le script pour corriger le bug.

Pour résoudre les erreurs dans votre script, cliquez sur le lien de l'e-mail de notification afin d'ouvrir votre projet de script. Une fois le projet ouvert, affichez les journaux d'exécution en cliquant sur Exécutions dans le panneau de navigation de gauche. Les journaux indiquent les exécutions qui ont échoué et incluent des messages d'erreur pour vous aider à diagnostiquer et à résoudre le problème.

Les déclencheurs installables créés par des modules complémentaires n'envoient pas ces notifications par e-mail aux utilisateurs.

Pour examiner tous les déclencheurs associés à votre compte Google et désactiver ceux dont vous n'avez plus besoin, procédez comme suit :

  1. Accédez à script.google.com.
  2. À gauche, cliquez sur Mes déclencheurs.
  3. Pour supprimer un déclencheur, cliquez sur Plus > Supprimer le déclencheur à droite de celui-ci.

Si un déclencheur est désactivé, les notifications d'échec correspondantes sont également désactivées. Les notifications d'échec font partie intégrante d'un déclencheur actif. Par conséquent, pour ne plus recevoir de notifications d'échec pour un déclencheur spécifique, désactivez ou supprimez le déclencheur lui-même. Lorsqu'un déclencheur est actif, vous ne pouvez ajuster que la fréquence de ces notifications.

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

Déclencheurs dans les modules complémentaires

En plus des déclencheurs installables, utilisez des déclencheurs de fichier manifeste dans les modules complémentaires. Pour en savoir plus, consultez Déclencheurs pour les modules complémentaires Google Workspace.