Autorisation du module complémentaire de l'éditeur

L'autorisation de nombreuses applications basées sur Apps Script est simple, car le projet de script demande les autorisations manquantes dont il a besoin lorsqu'un utilisateur tente de l'utiliser.

Le modèle d'autorisation des modules complémentaires pour l'éditeur est plus complexe pour plusieurs raisons:

• Lorsqu'un utilisateur crée un fichier, tous les modules complémentaires qu'il installe sont listés dans le menu Extensions, même s'il ne les a pas encore autorisés.

• Ces modules complémentaires fonctionnent sur les fichiers Google Drive pouvant être partagés avec des collaborateurs. Les collaborateurs qui n'ont pas installé le module complémentaire Éditeur le voient dans les documents où le créateur du fichier l'a utilisé.

• Les modules complémentaires Editor exécutent automatiquement leurs fonctions onOpen() lorsqu'un document s'ouvre.

Pour protéger les données utilisateur, des modes d'autorisation sont appliqués qui rendent certains services indisponibles pour onOpen(). Ce guide peut vous aider à comprendre ce que votre code peut faire et quand.

Modèle d'autorisation

Le mode d'autorisation d'un module complémentaire Éditeur dépend de son état, qui dépend de l'utilisateur qui l'utilise: l'utilisateur qui a installé le module complémentaire ou un collaborateur.

États des modules complémentaires de l'éditeur

Les modules complémentaires de l'éditeur dans le menu Extensions sont installés, activés ou les deux.

• Un module complémentaire est installé pour un utilisateur particulier après que lui ou son administrateur l'ont obtenu sur Google Workspace Marketplace et l'ont autorisé à accéder à ses données Google.
• Un module complémentaire est activé dans un document, un formulaire, une présentation ou une feuille de calcul lorsqu'un utilisateur l'utilise.
• Lorsque des utilisateurs collaborent sur un fichier et que l'un d'eux utilise un module complémentaire, celui-ci est installé pour cet utilisateur et activé pour le fichier.

Le tableau suivant récapitule les différences entre "installé" et "activé". Notez que lorsque vous testez un script en tant que module complémentaire, vous pouvez exécuter le test dans l'un ou l'autre de ces états, ou dans les deux.

	Installée	Activé
Applicable à	Utilisateur	Document, formulaire, présentation ou feuille de calcul
Causée par	Obtenir un module complémentaire sur le Google Store	Obtenir un module complémentaire depuis le Play Store lorsque vous utilisez ce document, ce formulaire, cette présentation ou cette feuille de calcul Utiliser un module complémentaire déjà installé dans ce document, ce formulaire, cette présentation ou cette feuille de calcul
Menu visible par	Seul cet utilisateur, dans tous les documents, formulaires, présentations ou feuilles de calcul qu'il ouvre ou crée	Tous les collaborateurs de ce document, formulaire, présentation ou feuille de calcul
Mode d'autorisation pour onOpen()	AuthMode.NONE (sauf s'il est également activé, auquel cas : AuthMode.LIMITED)	AuthMode.LIMITED

Modes d'autorisation

La fonction onOpen() d'un module complémentaire Editor s'exécute automatiquement lorsqu'un utilisateur ouvre un document, un formulaire, une présentation ou une feuille de calcul. Pour protéger les données des utilisateurs, Apps Script limite les actions que la fonction onOpen() peut effectuer. L'état du module complémentaire de l'éditeur détermine le mode d'autorisation dans lequel la fonction onOpen() s'exécute.

Si un module complémentaire Editor est activé dans le fichier, le formulaire, la présentation ou la feuille de calcul, onOpen() s'exécute dans AuthMode.LIMITED. Si le module complémentaire n'est pas activé et n'est que installé, onOpen() s'exécute dans AuthMode.NONE.

Dans AuthMode.NONE, un module complémentaire ne peut pas exécuter certains services tant que l'utilisateur n'interagit pas avec le module complémentaire en cliquant dessus ou en exécutant des fonctions personnalisées. Si votre module complémentaire tente d'utiliser ces services dans une portée onOpen(), onInstall() ou globale, les autorisations échouent et d'autres appels, tels que le remplissage de menus, s'arrêtent. L'aide est la seule option acceptée.

Pour exécuter des appels de service restreints, vous devez utiliser le mode d'autorisation AuthMode.FULL. Les fonctions d'interaction utilisateur, telles que le clic sur une option de menu, ne s'exécutent que dans ce mode. Une fois le code exécuté en mode AuthMode.FULL, le module complémentaire peut utiliser tous les champs d'application que l'utilisateur a autorisés.

Remarque :Seuls les modules complémentaires publiés peuvent être dans AuthMode.NONE. Les modules complémentaires non publiés exécutent onOpen() dans AuthMode.LIMITED. Toutefois, vous pouvez tester un module complémentaire de l'Éditeur pour vérifier qu'un module complémentaire en cours de développement se comporte comme prévu dans les deux modes d'autorisation.

Apps Script transmet le mode d'autorisation en tant que propriété authMode du paramètre d'événement Apps Script, e. La valeur de e.authMode correspond à une constante dans l'énumération Apps Script ScriptApp.AuthMode.

Les modes d'autorisation s'appliquent à toutes les méthodes d'exécution Apps Script, y compris l'exécution à partir de l'éditeur de script, d'un élément de menu ou d'un appel google.script.run Apps Script. Toutefois, la propriété e.authMode ne peut être inspectée que si le script s'exécute à la suite d'un déclencheur tel que onOpen(), onEdit() ou onInstall(). Les fonctions personnalisées dans Google Sheets utilisent leur propre mode d'autorisation, AuthMode.CUSTOM_FUNCTION, qui est semblable à LIMITED, mais présente des restrictions légèrement différentes. Dans tous les autres cas, les scripts s'exécutent en AuthMode.FULL, comme décrit dans le tableau suivant.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Se produit pour	onOpen() (si l'utilisateur a installé un module complémentaire, mais ne l'a pas activé dans le document, le formulaire, la présentation ou la feuille de calcul)	onOpen() (toutes les autres heures) onEdit() (uniquement dans Sheets)	Fonctions personnalisées	Toutes les autres fois, y compris: déclencheurs installables onInstall() google.script.run
Accès aux données utilisateur	Paramètre régional uniquement	Paramètre régional uniquement	Paramètre régional uniquement	Oui
Accès à un document, un formulaire, une présentation ou une feuille de calcul	Non	Oui	Oui : en lecture seule	Oui
Accès à l'interface utilisateur	Ajouter des éléments de menu	Ajouter des éléments de menu	Non	Oui
Accès à Properties	Non	Oui	Oui	Oui
Accès à Jdbc, UrlFetch	Non	Non	Oui	Oui
Autres services	Logger Utilities	Tous les services qui n'accèdent pas aux données utilisateur	Tous les services qui n'accèdent pas aux données utilisateur	Tous les services

Cycle de vie de l'autorisation d'un module complémentaire d'éditeur

Lorsqu'un module complémentaire est installé pour l'utilisateur actuel ou activé dans le fichier actuel, il est téléchargé pour le document, le formulaire, la présentation ou la feuille de calcul lorsque ce fichier est ouvert. Le module complémentaire est listé dans le menu Extensions et commence à écouter les déclencheurs simples onInstall(), onOpen() et onEdit(). Si un utilisateur clique sur un élément de menu Extensions, il s'exécute.

Le module complémentaire de l'éditeur est installé

Lorsqu'un module complémentaire Editor est installé depuis le Play Store, sa fonction onInstall() s'exécute dans AuthMode.FULL. Dans ce mode d'autorisation, le module complémentaire peut exécuter une routine de configuration complexe. Vous devez également utiliser onInstall() pour créer des éléments de menu, car le document, le formulaire, la présentation ou la feuille de calcul sont déjà ouverts et votre fonction onOpen() ne s'est pas exécutée. L'exemple suivant montre comment appeler la fonction onOpen() à partir de la fonction onInstall():

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Le module complémentaire de l'éditeur s'ouvre.

Lorsqu'un document, un formulaire, une présentation ou une feuille de calcul s'ouvre, tous les modules complémentaires de l'Éditeur que l'utilisateur actuel a installés ou que n'importe quel collaborateur a activés dans le fichier sont chargés, et chacune de leurs fonctions onOpen() est appelée. Le mode d'autorisation dans lequel onOpen() s'exécute dépend de la présence ou non d'un module complémentaire installé ou activé.

Si un module complémentaire ne crée qu'un menu de base, le mode n'a pas d'importance. L'exemple suivant montre une fonction onOpen() de base:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Pour ajouter des éléments de menu dynamiques en fonction des propriétés Apps Script stockées, pour lire le contenu du fichier actuel ou pour effectuer d'autres tâches avancées, vous devez identifier le mode d'autorisation et le gérer de manière appropriée.

L'exemple suivant montre une fonction onOpen() avancée qui modifie son action en fonction du mode d'autorisation:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

Avertissement :Lorsque la fonction onOpen() s'exécute, l'intégralité du script est chargée et toutes les instructions globales sont exécutées sous le même mode d'autorisation que onOpen(). Si le mode d'autorisation interdit les instructions globales, les instructions globales et onOpen() ne s'exécutent pas. Si le module complémentaire publié ne parvient pas à ajouter ses éléments de menu, consultez la console JavaScript du navigateur pour voir si une erreur a été renvoyée. Ensuite, examinez votre script pour voir si la fonction onOpen() ou les variables globales appellent des services non autorisés dans AuthMode.NONE.

Notez que les modules complémentaires ne peuvent pas ouvrir de barres latérales ni de boîtes de dialogue lors de l'exécution dans AuthMode.LIMITED. Vous pouvez utiliser des éléments de menu pour ouvrir des barres latérales et des boîtes de dialogue, car ils s'exécutent dans AuthMode.FULL.

Un utilisateur exécute le module complémentaire de l'éditeur

Lorsqu'un utilisateur clique sur un élément de menu Extensions, Apps Script vérifie d'abord si l'utilisateur a installé le module complémentaire, et l'invite à le faire si ce n'est pas le cas. Si l'utilisateur a autorisé le module complémentaire, le script exécute la fonction correspondant à l'élément de menu dans AuthMode.FULL. Le module complémentaire est activé dans le document, le formulaire, la présentation ou la feuille de calcul, s'il ne l'était pas déjà.

Résoudre les problèmes de non-affichage des menus des modules complémentaires

Il est possible que le menu de votre module complémentaire ne s'affiche pas si votre code ne gère pas correctement les modes d'autorisation. Exemple :

• Un module complémentaire tente d'exécuter un service Apps Script qui n'est pas compatible avec le mode d'autorisation actuel.

• Un module complémentaire tente d'exécuter un appel de service avant qu'un utilisateur n'interagisse avec lui.

Pour supprimer ou réorganiser un appel de service qui provoque des erreurs d'autorisation dans AuthMode.NONE, procédez comme suit:

1. Ouvrez le projet Apps Script de votre module complémentaire et recherchez la fonction onOpen().
2. Recherchez dans la fonction onOpen() des mentions de services ou d'objets Apps Script qui leur sont associés, tels que PropertiesService, SpreadsheetApp ou GmailApp.
3. Si un service est utilisé pour autre chose que la création des éléments d'interface utilisateur, supprimez-le ou encapsulez-le dans un bloc de commentaires. Ne laissez que les méthodes suivantes: .getUi(), .createMenu(), .addItem() et .addToUi(). Recherchez et supprimez également tout service en dehors d'une fonction.
4. Identifiez les fonctions susceptibles de contenir les lignes de code commentées ou supprimées à l'étape précédente, en particulier celles qui utilisent les informations qu'elles génèrent, puis déplacez les appels de service vers les fonctions qui en ont besoin. Réorganisez ou réécrivez votre codebase pour tenir compte des modifications apportées aux étapes précédentes.

5. Enregistrez le code et créez un déploiement de test.

   Lorsque vous créez un déploiement de test, assurez-vous que le champ Config (Configuration) est défini sur Installed for current user (Installé pour l'utilisateur actuel) et que le texte sous la zone de configuration indique Test in AuthMode.None (Tester dans AuthMode.None).

6. Lancez le déploiement de test et ouvrez le menu Extensions.

7. Si tous les éléments du menu s'affichent, le problème est résolu. Si vous ne voyez que le menu Aide, revenez à l'étape 1. Vous avez peut-être manqué un appel de service.

Articles associés

• Applications Web
• Types de modules complémentaires
• Tester un module complémentaire de l'éditeur