Déclencheurs des modules complémentaires de l'éditeur

Les déclencheurs Apps Script entraînent l'exécution d'une fonction de script spécifiée (la fonction 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 accepte un ensemble d'événements différent.

Lorsqu'un déclencheur est exécuté, un objet événement est créé. Cette structure JSON contient des détails sur l'événement qui s'est produit. La structure des objets de l'événement est organisée 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éclenchement. La fonction de déclenchement est une fonction de rappel que vous devez implémenter vous-même afin de prendre les mesures appropriées pour répondre à l'événement. Par exemple, dans un module complémentaire d'éditeur, un déclencheur permet de créer des éléments de menu complémentaires lorsqu'un document est ouvert. Dans ce cas, vous implémentez sur la fonction de déclenchement onOpen(e) pour créer les éléments de menu dont le module complémentaire a besoin, en utilisant éventuellement les 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 du module complémentaire 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 de types de déclencheurs disponibles dépend de l'extension de l'application.

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

Événement	Objet événement	Déclencheurs simples	Déclencheurs installables
Ouvrir Un fichier d'éditeur est ouvert.	Objet d'événement Docs onOpen Objet d'événement onon de Forms Objet d'événement Sheets onOpen objet d'événement Slides onOpen	Docs Forms* Sheets Slides function onOpen(e)	Docs Forms* Sheets
Installer Le module complémentaire est installé.	Objet événement onInstall	Docs Forms Sheets Slides function onInstall(e)
Modifier Le contenu des cellules de la feuille de calcul a été modifié.	Objet d'événement onEdit Sheets	Sheets function onEdit(e)	Sheets
Modification Le contenu d'une feuille est modifié ou mis en forme.	Objet d'événement Sheets onChange		Sheets
Envoi de formulaire Un formulaire Google Forms est envoyé.	Objet d'événement d'envoi de formulaire Forms Objet d'événement d'envoi de formulaire Forms avec Sheets		Forms Sheets
En fonction de l'heure Le déclencheur est exécuté à une heure ou à un intervalle spécifiés.	Objet d'événement basé sur le temps		Docs Forms Sheets Slides

* L'événement ouvert pour Google Forms ne se produit pas lorsqu'un utilisateur ouvre un formulaire pour répondre, mais lorsqu'un éditeur ouvre le formulaire 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 activés automatiquement. Dans certains cas, un simple événement déclencheur peut être géré par un déclencheur installable.

Vous pouvez ajouter un déclencheur simple à un module complémentaire en implémentant 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 lors de la réponse au formulaire). Elle ne s'exécute que si l'utilisateur est autorisé à modifier le fichier en question. Elle est le plus souvent utilisée pour créer des éléments de menu.
• onInstall(e) s'exécute lorsqu'un utilisateur installe un module complémentaire. En règle générale, onInstall(e) est simplement utilisé pour appeler onOpen(e). Cela garantit que les menus des modules complémentaires s'affichent immédiatement après l'installation, sans que l'utilisateur ait à actualiser la page.
• onEdit(e) s'exécute lorsqu'un utilisateur modifie une valeur de cellule dans une feuille de calcul. Ce déclencheur ne s'active pas en cas de déplacement de cellule, de mise en forme ou d'autres modifications qui n'affectent pas les valeurs des cellules.

Restrictions

Les déclencheurs simples des modules complémentaires sont soumis aux mêmes restrictions que les déclencheurs simples des autres types de projets Apps Script. Tenez compte en particulier des restrictions suivantes lorsque vous concevez des modules complémentaires:

• Les déclencheurs simples ne s'exécutent pas si un fichier est ouvert en lecture seule (lecture ou commentaire). Ce comportement empêche que les menus de vos modules complémentaires soient remplis.
• 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 d'autres complications, comme décrit dans le modèle d'autorisation d'extension.
• Les déclencheurs simples ne peuvent pas utiliser de services ni effectuer d'autres actions nécessitant une autorisation, sauf comme décrit dans le modèle d'autorisation complémentaire.
• Les déclencheurs simples ne peuvent pas être exécutés pendant plus de 30 secondes. Veillez à minimiser la quantité de traitement effectué dans une simple fonction de déclenchement.
• Les déclencheurs simples sont soumis aux limites de quota d'Apps Script.

Déclencheurs installables dans les modules complémentaires

Les modules complémentaires peuvent créer et modifier par programmation des déclencheurs à installer avec le service Apps Script Script. Il est impossible de créer manuellement des déclencheurs pouvant être installés. Contrairement aux simples déclencheurs, 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 en cas d'erreurs, car dans la plupart des cas, l'utilisateur ne peut pas résoudre le problème. Pour cette raison, vous devez concevoir votre module complémentaire de façon à gérer correctement les erreurs pour le compte de l'utilisateur, dans la mesure du possible.

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

• Les déclencheurs ouverts installables s'exécutent lorsqu'un utilisateur ouvre un document, une feuille de calcul ou un formulaire ouvert dans l'éditeur (mais pas lorsqu'ils répondent au formulaire).
• Les déclencheurs modifiables s'exécutent lorsqu'un utilisateur modifie une valeur de cellule dans une feuille de calcul. Ce déclencheur ne s'active pas en réponse à une mise en forme ou à d'autres modifications qui n'affectent pas les valeurs des cellules.
• Les déclencheurs installables s'exécutent lorsqu'un utilisateur modifie une feuille de calcul, y compris les modifications de mise en forme et les modifications apportées à la feuille de calcul proprement dite (par exemple, l'ajout d'une ligne).

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

• Les déclencheurs temporels (également appelés déclencheurs d'horloge) se déclenchent à une heure spécifique ou à intervalles réguliers.

Autoriser les déclencheurs à installer

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 de nouveau le module la prochaine fois qu'ils l'utilisent.

Toutefois, les modules complémentaires qui utilisent des déclencheurs rencontrent des problèmes d'autorisation particuliers. Imaginez un module complémentaire utilisant un déclencheur pour surveiller l'envoi 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 de modules complémentaires devait mettre à jour le module complémentaire pour utiliser de nouveaux services nécessitant une autorisation supplémentaire, le créateur du formulaire ne verra jamais la boîte de dialogue de réautorisation, car il n'aura jamais rouvert le formulaire, et le module complémentaire cessera de fonctionner.

Contrairement aux déclencheurs des projets Apps Script standards, les déclencheurs des modules complémentaires continuent à s'exécuter même s'ils nécessitent une nouvelle autorisation. Toutefois, le script échoue toujours s'il atteint une ligne de code nécessitant une autorisation qu'il ne possède pas. Pour éviter cette situation, les développeurs peuvent utiliser la méthode ScriptApp.getAuthorizationInfo() pour interdire l'accès aux parties de code qui ont changé 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éclenchement afin d'éviter les pièges liés aux autorisations. 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 nouvelle autorisation est requise, envoie un e-mail d'alerte à l'utilisateur à l'aide d'un modèle HTML.

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

<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 pouvant être installés dans les modules complémentaires sont soumis aux mêmes restrictions que les déclencheurs d'installation des autres types de projets Apps Script.

Outre ces restrictions, plusieurs restrictions s'appliquent spécifiquement aux déclencheurs installés dans les modules complémentaires:

• Chaque module complémentaire ne peut être associé 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, bien que l'utilisateur puisse également avoir un déclencheur "Envoi de formulaire" ou un déclencheur temporel 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. Autrement dit, un module complémentaire utilisé dans le document Google A ne peut pas créer de déclencheur à surveiller lorsque le document Google B est ouvert.
• Les déclencheurs temporels ne peuvent pas être exécutés plus d'une fois par heure.
• Les modules complémentaires n'envoient pas automatiquement un e-mail à l'utilisateur lorsque le code exécuté par un déclencheur installable génère une exception. Il appartient au développeur de rechercher et de gérer correctement les cas de défaillance.
• Les déclencheurs de module complémentaire s'arrêtent dans les situations suivantes :
  • Si le module complémentaire est désinstallé par l'utilisateur,
  • Si le module complémentaire est désactivé dans un document (s'il est réactivé, le déclencheur redevient opérationnel) ; ou
  • Si le développeur annule la publication du module complémentaire ou envoie une version défectueuse au module complémentaire.
• Les fonctions de déclencheur de module complémentaire s'exécutent jusqu'à ce qu'elles atteignent le code qui utilise un service non autorisé, après quoi 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 standard ou un module complémentaire non publié ne s'exécute pas si une partie du script nécessite une autorisation.
• Les déclencheurs installables sont soumis aux limites de quota d'Apps Script.