Déclencheurs pour les modules complémentaires d'éditeurs

Les déclencheurs Apps Script permettent d'exécuter une fonction de script spécifique (la fonction de déclencheur) chaque fois qu'un événement spécifié se produit. Seuls certains événements peuvent déclencher des déclencheurs, et chaque application Google Workspace prend en charge un ensemble d'événements différent.

Lorsqu'un déclencheur se déclenche, un objet d'événement est créé. Cette structure JSON contient des informations sur l'événement qui s'est produit. Les informations contenues dans la structure de l'objet d'événement sont organisées différemment en fonction du type de déclencheur.

Une fois l'objet événement créé, Apps Script le transmet en tant que paramètre à la fonction de déclencheur. La fonction de déclencheur est une fonction de rappel que vous devez implémenter vous-même pour effectuer les actions appropriées en réponse à l'événement. Par exemple, dans un module complémentaire Editor, un déclencheur est utilisé pour créer des éléments de menu de module complémentaire lorsqu'un document est ouvert. Dans ce cas, vous implémentez une fonction de déclencheur onOpen(e) pour créer les éléments de menu dont le module complémentaire a besoin, éventuellement à l'aide des données de l'objet événement.

Cette page fournit des consignes sur l'utilisation des déclencheurs dans les projets de modules complémentaires de l'éditeur.

Types de déclencheurs des modules complémentaires de l'éditeur

Vous pouvez utiliser la plupart des types de déclencheurs génériques disponibles pour les projets Apps Script dans les modules complémentaires de l'éditeur, y compris les déclencheurs simples et la plupart des déclencheurs installables. L'ensemble exact des types de déclencheurs disponibles dépend de l'application étendue.

Le tableau suivant indique les types de déclencheurs simples et installables que les modules complémentaires de l'éditeur peuvent utiliser, et fournit des liens vers les objets d'événement correspondants :

Événement Objet d'événement Déclencheurs simples Déclencheurs installables
Ouvrir
Un fichier d'éditeur est ouvert.		 Objet d'événement onOpen de Docs
Objet d'événement onOpen de Forms
Objet d'événement onOpen de Sheets
Objet d'événement onOpen de Slides 		Docs
Forms*
Sheets
Slides

function onOpen(e)

 Docs
Forms
Sheets
Installer
Le module complémentaire est installé.		 Objet d'événement onInstall Docs
Forms
Sheets
Slides

function onInstall(e)
Modifier
 Le contenu d'une cellule de feuille de calcul a été modifié.		 Objet d'événement Sheets onEdit Sheets

function onEdit(e)

 Sheets
Modifier
 : le contenu d'une feuille est modifié ou mis en forme.		 Objet d'événement onChange de Sheets Sheets
Form-submit
Un formulaire Google est envoyé.		 Objet d'événement d'envoi de formulaire Forms
Objet d'événement d'envoi de formulaire Sheets 		Forms
Sheets
Déclencheur basé sur le temps (horloge)
Le déclencheur se déclenche à une heure ou à un intervalle spécifiés.		 Objet d'événement basé sur le temps Docs
Forms
Sheets
Slides

* L'événement d'ouverture de Google Forms ne se produit pas lorsqu'un utilisateur ouvre un formulaire pour y répondre, mais lorsqu'un éditeur l'ouvre pour le modifier.

Déclencheurs simples dans les modules complémentaires

Les déclencheurs simples utilisent un ensemble de noms de fonctions réservés, ne peuvent pas utiliser les services qui nécessitent une autorisation et sont automatiquement activés pour être utilisés. Dans certains cas, un événement de déclencheur simple peut être géré par un déclencheur installable.

Vous pouvez ajouter un déclencheur simple à un module complémentaire en implémentant simplement une fonction avec l'un des noms réservés suivants :

  • onOpen(e) s'exécute lorsqu'un utilisateur ouvre un document, une feuille de calcul ou une présentation. onOpen(e) peut également s'exécuter lorsqu'un formulaire est ouvert dans l'éditeur (mais pas lorsqu'une réponse est envoyée). Il ne s'exécute que si l'utilisateur est autorisé à modifier le fichier en question. Il est le plus souvent utilisé pour créer des éléments de menu.
  • onInstall(e) s'exécute lorsqu'un utilisateur installe un module complémentaire. En général, onInstall(e) est utilisé uniquement pour appeler onOpen(e). Cela permet de s'assurer que les menus du module complémentaire s'affichent immédiatement après l'installation, sans que l'utilisateur ait besoin d'actualiser la page.
  • onEdit(e) s'exécute lorsqu'un utilisateur modifie la valeur d'une cellule dans une feuille de calcul. Ce déclencheur ne se déclenche pas en réponse aux déplacements de cellules, à la mise en forme ou à d'autres modifications qui n'altèrent pas les valeurs des cellules.

Restrictions

Les déclencheurs simples dans les modules complémentaires sont soumis aux mêmes restrictions que les déclencheurs simples dans d'autres types de projets Apps Script. Tenez particulièrement compte de ces restrictions lorsque vous concevez des modules complémentaires :

  • Les déclencheurs simples ne s'exécutent pas si un fichier est ouvert en mode lecture seule (affichage ou commentaire). Ce comportement empêche le remplissage des menus de vos modules complémentaires.
  • Dans certains cas, les modules complémentaires de l'éditeur exécutent leurs déclencheurs simples onOpen(e) et onEdit(e) en mode sans autorisation. Ce mode présente quelques complications supplémentaires, comme indiqué dans le modèle d'autorisation des modules complémentaires.
  • Les déclencheurs simples ne peuvent pas utiliser de services ni effectuer d'autres actions nécessitant une autorisation, sauf dans les cas décrits dans le modèle d'autorisation des modules complémentaires.
  • Les déclencheurs simples ne peuvent pas s'exécuter pendant plus de 30 secondes. Veillez à minimiser la quantité de traitement effectuée dans une fonction de déclencheur simple.
  • Les déclencheurs simples sont soumis aux limites de quota des déclencheurs Apps Script.

Déclencheurs installables dans les modules complémentaires

Les modules complémentaires peuvent créer et modifier des déclencheurs installables de manière programmatique avec le service Script Apps Script. Les déclencheurs installables de modules complémentaires ne peuvent pas être créés manuellement. Contrairement aux déclencheurs simples, les déclencheurs installables peuvent utiliser des services nécessitant une autorisation.

Les déclencheurs installables dans les modules complémentaires n'envoient pas d'e-mails d'erreur à l'utilisateur lorsqu'ils rencontrent des erreurs, car dans la plupart des cas, l'utilisateur n'est pas en mesure de résoudre le problème. Pour cette raison, vous devez concevoir votre module complémentaire de manière à gérer correctement les erreurs au nom de l'utilisateur chaque fois que cela est possible.

Les modules complémentaires peuvent utiliser les déclencheurs installables suivants :

  • Les déclencheurs installables Open s'exécutent lorsqu'un utilisateur ouvre un document ou une feuille de calcul, ou lorsqu'un formulaire est ouvert dans l'éditeur (mais pas lorsqu'il y répond).
  • Les déclencheurs installables Edit s'exécutent lorsqu'un utilisateur modifie la valeur d'une cellule dans une feuille de calcul. Ce déclencheur ne se déclenche pas en réponse à des modifications de mise en forme ou à d'autres modifications qui n'altèrent pas les valeurs des cellules.
  • Les déclencheurs installables Change s'exécutent lorsqu'un utilisateur apporte une modification à une feuille de calcul, y compris des modifications de mise en forme et des modifications à la feuille de calcul elle-même (comme l'ajout d'une ligne).

  • Les déclencheurs installables Form-submit s'exécutent lorsqu'une réponse à un formulaire Google Forms est envoyée.

  • Déclencheurs temporels (également appelés déclencheurs d'horloge) se déclenchent à une heure spécifique ou de manière répétée à intervalles réguliers.

Autoriser les déclencheurs installables

Normalement, si un développeur met à jour un module complémentaire pour utiliser de nouveaux services nécessitant une autorisation supplémentaire, les utilisateurs sont invités à autoriser à nouveau le module complémentaire la prochaine fois qu'ils l'utilisent.

Toutefois, les modules complémentaires qui utilisent des déclencheurs rencontrent des problèmes d'autorisation spécifiques. Imaginez un module complémentaire qui utilise un déclencheur pour surveiller les envois de formulaires : un créateur de formulaire peut autoriser le module complémentaire la première fois qu'il l'utilise, puis le laisser s'exécuter pendant des mois ou des années sans jamais rouvrir le formulaire. Si le développeur du module complémentaire devait le mettre à jour pour utiliser de nouveaux services nécessitant une autorisation supplémentaire, le créateur du formulaire ne verrait jamais la boîte de dialogue de réautorisation, car il n'a jamais rouvert le formulaire, et le module complémentaire cesserait de fonctionner.

Contrairement aux déclencheurs des projets Apps Script classiques, ceux des modules complémentaires continuent de se déclencher même s'ils doivent être réautorisés. Toutefois, le script échoue toujours s'il rencontre une ligne de code qui nécessite une autorisation dont il ne dispose pas. Pour éviter cette situation, les développeurs peuvent utiliser la méthode ScriptApp.getAuthorizationInfo() pour contrôler l'accès aux parties du code qui ont été modifiées entre les versions publiées du module complémentaire.

Vous trouverez ci-dessous un exemple de structure recommandée à utiliser dans les fonctions de déclencheur pour éviter les pièges liés à l'autorisation. L'exemple de fonction de déclencheur répond à un événement d'envoi de formulaire dans un module complémentaire Google Sheets et, si une réautorisation est requise, envoie à l'utilisateur du module complémentaire un e-mail d'alerte à l'aide d'un code HTML basé sur un modèle.

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>

Restrictions

Les déclencheurs installables dans les modules complémentaires sont soumis aux mêmes restrictions que les déclencheurs installables dans d'autres types de projets Apps Script.

En plus de ces restrictions, plusieurs restrictions s'appliquent spécifiquement aux déclencheurs installables dans les modules complémentaires :

  • Chaque module complémentaire ne peut comporter qu'un seul déclencheur de chaque type, par utilisateur et par document. Par exemple, dans une feuille de calcul donnée, un utilisateur donné ne peut avoir qu'un seul déclencheur de modification, même s'il peut également avoir un déclencheur d'envoi de formulaire ou un déclencheur basé sur le temps dans la même feuille de calcul. Un autre utilisateur ayant accès à la même feuille de calcul peut avoir son propre ensemble de déclencheurs.
  • Les modules complémentaires ne peuvent créer des déclencheurs que pour le fichier dans lequel ils sont utilisés. En d'autres termes, un module complémentaire utilisé dans le document Google Docs A ne peut pas créer de déclencheur pour surveiller l'ouverture du document Google Docs B.
  • Les déclencheurs basés sur l'heure ne peuvent pas s'exécuter plus d'une fois par heure.
  • Les modules complémentaires n'envoient pas automatiquement d'e-mail à l'utilisateur lorsqu'un code exécuté par un déclencheur installable génère une exception. Il incombe au développeur de vérifier et de gérer les cas d'échec de manière optimale.
  • Les déclencheurs de modules complémentaires cessent de se déclencher dans les situations suivantes :
    • Si l'utilisateur désinstalle le module complémentaire,
    • Si le module complémentaire est désactivé dans un document (si vous le réactivez, le déclencheur redevient opérationnel)
    • Si le développeur annule la publication du module complémentaire ou envoie une version défectueuse à la boutique de modules complémentaires.
  • Les fonctions de déclencheur de module complémentaire s'exécutent jusqu'à ce qu'elles atteignent un code qui utilise un service non autorisé, auquel cas elles s'arrêtent. Cela n'est vrai que si le module complémentaire est publié. Le même déclencheur dans un projet Apps Script normal ou un module complémentaire non publié ne s'exécute pas du tout si une partie du script nécessite une autorisation.
  • Les déclencheurs installables sont soumis aux limites de quota des déclencheurs Apps Script.