Autorisation du module complémentaire de l'éditeur

L'autorisation pour 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 pour les modules complémentaires de 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 qui peuvent ê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 de l'éditeur 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, ce qui rend 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 de l'éditeur dépend de son état, qui dépend de la personne qui l'utilise : l'utilisateur qui a installé le module complémentaire ou un collaborateur.

États du module complémentaire de l'éditeur

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

• Un module complémentaire est installé pour un utilisateur spécifique une fois 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.
• Lorsqu'une personne collabore sur un fichier et qu'elle 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 les deux.

	Installé	Activé
Applicable à	Utilisateur	Document, formulaire, présentation ou feuille de calcul
Causée par	Obtenir un module complémentaire depuis la boutique	Obtenir un module complémentaire depuis la plate-forme en utilisant ce document, ce formulaire, cette présentation ou cette feuille de calcul, ou Utiliser un module complémentaire précédemment 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 de l'éditeur 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 de l'éditeur 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 qu'il est uniquement 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 lui en cliquant dessus ou en exécutant des fonctions personnalisées. Si votre module complémentaire tente d'utiliser ces services dans un champ d'application onOpen(), onInstall() ou global, les autorisations échouent et les autres appels, tels que le remplissage des menus, s'arrêtent. L'option "Aide" est la seule acceptée.

Pour exécuter des appels de service restreints, vous devez utiliser le mode d'autorisation AuthMode.FULL. Les fonctions d'interaction utilisateur, comme le fait de cliquer 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 niveaux d'accès autorisés par l'utilisateur.

Remarque : Seuls les modules complémentaires de l'éditeur publiés peuvent se trouver dans AuthMode.NONE. Les modules complémentaires de l'éditeur non publiés 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 l'un ou l'autre mode 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 ScriptApp.AuthMode d'Apps Script.

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 avec des restrictions légèrement différentes. Dans tous les autres cas, les scripts s'exécutent dans 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() (Sheets uniquement)	Fonctions personnalisées	À tout autre moment, y compris : déclencheurs installables onInstall() google.script.run
Accès aux données utilisateur	Paramètres régionaux uniquement	Paramètres régionaux uniquement	Paramètres régionaux uniquement	Oui
Accès à un document, un formulaire, une présentation ou une feuille de calcul	Non	Oui	Oui – 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 de l'éditeur

Lorsqu'un module complémentaire est installé pour l'utilisateur actuel ou activé dans le fichier actuel, il est 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 est exécuté.

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

Lorsqu'un module complémentaire de l'éditeur est installé depuis le magasin, 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() n'a pas été 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 É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 installés par l'utilisateur actuel ou activés par un collaborateur 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 si un module complémentaire est 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 illustre 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 basés sur des propriétés Apps Script stockées, lire le contenu du fichier actuel ou 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 se charge et toutes les instructions globales s'exécutent sous le même mode d'autorisation que onOpen(). Si le mode d'autorisation interdit les instructions globales, les instructions globales et onOpen() ne peuvent pas s'exécuter. 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. Examinez ensuite votre script pour voir si la fonction onOpen() ou les variables globales appellent des services qui ne sont pas 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 lorsqu'ils s'exécutent 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 qui correspond à 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, si ce n'était pas déjà le cas.

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

Le menu de votre module complémentaire peut ne pas s'afficher 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 la fonction onOpen() pour trouver des mentions de services ou d'objets Apps Script associés, tels que PropertiesService, SpreadsheetApp ou GmailApp.
3. Si un service est utilisé pour autre chose que la création d'éléments d'interface utilisateur, supprimez-le ou placez-le dans un bloc de commentaires. Ne conservez que les méthodes suivantes : .getUi(), .createMenu(), .addItem() et .addToUi(). Recherchez et supprimez également tout service qui se trouve en dehors d'une fonction.
4. Identifiez les fonctions qui pourraient contenir les lignes de code commentées ou supprimées à l'étape précédente, en particulier celles qui utilisent les informations qu'elles produisent, et 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 lors des é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 Configuration est défini sur Installé pour l'utilisateur actuel et que le texte sous la zone de configuration indique Tester dans AuthMode.None.

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

7. Si tous les éléments de menu s'affichent, le problème est résolu. Si seul le menu Aide s'affiche, 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