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

Les déclencheurs Apps Script permettent d'exécuter une fonction de script spécifiée (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 est compatible avec 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 de la structure de l'objet d'événement sont organisées différemment en fonction du type de déclencheur.

Une fois l'objet d'é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 pour répondre à l'événement. Par exemple, dans un module complémentaire Editor, un déclencheur permet de créer des éléments de menu de module complémentaire lorsqu'un document est ouvert. Dans ce cas, vous implémentez la 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 d'événement.

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

Types de déclencheurs de modules complémentaires d'é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 présente 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 s'ouvre.		 Objet d'événement onOpen Docs
Objet d'événement onOpen Forms
Objet d'événement onOpen Sheets
Objet d'événement onOpen 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 de la cellule de la feuille de calcul est 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 onChange dans Sheets Sheets
Envoi du formulaire
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
Basé sur le temps (horloge)
Le déclencheur se déclenche à une heure ou à un intervalle spécifié.		 Objet d'événement basé sur le temps Docs
Forms
Sheets
Slides

* L'événement d'ouverture pour Google Forms ne se produit pas lorsqu'un utilisateur ouvre un formulaire pour y 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 de services nécessitant une autorisation et sont automatiquement activé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 lorsque vous répondez au formulaire). Elle ne s'exécute que si l'utilisateur est autorisé à modifier le fichier en question et 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 général, onInstall(e) n'est utilisé que pour appeler onOpen(e). Cela garantit que les menus du module complémentaire 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 la valeur d'une cellule dans une feuille de calcul. Ce déclencheur ne se déclenche pas en réponse à un déplacement de cellule, à une 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 d'autres types de projets Apps Script. Prenez particulièrement en compte 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 (vue ou commentaire). Ce comportement empêche le remplissage des menus de vos modules complémentaires.
  • Dans certains cas, les modules complémentaires d'é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 à réduire au maximum le traitement effectué 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 de manière programmatique des déclencheurs installables avec le service Script d'Apps Script. Les déclencheurs installables des 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'il rencontre des erreurs, car dans la plupart des cas, l'utilisateur ne peut pas résoudre le problème. Par conséquent, vous devez concevoir votre module complémentaire pour qu'il gère correctement les erreurs au nom de l'utilisateur dans la mesure du possible.

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

  • Les déclencheurs installables Ouvrir s'exécutent lorsqu'un utilisateur ouvre un document, une feuille de calcul ou un formulaire dans l'éditeur (mais pas lorsqu'il répond au formulaire).
  • Les déclencheurs installables Modifier 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 à une mise en forme ou à d'autres modifications qui ne modifient 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 de la feuille de calcul elle-même (par exemple, l'ajout d'une ligne).

  • Les déclencheurs installables Envoi de formulaire s'exécutent lorsqu'une réponse Google Forms est envoyée.

  • Les déclencheurs basés sur le temps (également appelés déclencheurs de l'horloge) se déclenchent à une heure spécifique ou de manière répétée à un intervalle de temps régulier.

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 à réautoriser 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 particuliers. Imaginons un module complémentaire qui utilise 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 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 standards, les déclencheurs 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 le script 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 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éclencheur pour éviter les écueils d'autorisation. L'exemple de fonction de déclencheur répond à un événement de soumission 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 modèle HTML.

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 avoir 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 qu'il puisse également disposer d'un déclencheur d'envoi de formulaire ou d'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 disposer de son propre ensemble de déclencheurs.
  • Les modules complémentaires ne peuvent créer de déclencheurs que pour le fichier dans lequel ils sont utilisés. Autrement dit, un module complémentaire utilisé dans Google Doc A ne peut pas créer de déclencheur pour surveiller l'ouverture de Google Doc B.
  • Les déclencheurs basés sur le temps 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'une exception est générée par le code exécuté par un déclencheur installable. C'est au développeur de vérifier et de gérer de manière optimale les cas d'échec.
  • Les déclencheurs des modules complémentaires ne se déclenchent plus dans les situations suivantes :
    • Si l'utilisateur désinstalle le module complémentaire,
    • 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 sur la plate-forme de modules complémentaires.
  • Les fonctions de déclencheur de modules complémentaires s'exécutent jusqu'à ce qu'elles atteignent du 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 standard 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.