Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Autorisation du module complémentaire de l'éditeur

L'autorisation de nombreuses applications Google Apps Script est simple. 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 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 de l'é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 explique 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 l'utilisateur : celui 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 spécifique après que lui ou son administrateur l'a obtenu sur Google Workspace Marketplace et l'a 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 lorsque quelqu'un l'utilise.
Lorsque des personnes collaborent sur un fichier et que l'une d'elles utilise un module complémentaire, il est installé pour cet utilisateur et activé pour le fichier.

Le tableau suivant résume les différences entre l'installation et l'activation. Lorsque vous testez un script en tant que module complémentaire, vous pouvez exécuter le test dans l'un ou les deux états.

	Installé	Activé
Applicable à	Utilisateur	Document, formulaire, présentation ou feuille de calcul
Causée par	Obtention d'un module complémentaire dans le Store	Obtention d'un module complémentaire dans le Store lors de l'utilisation de ce document, formulaire, présentation ou feuille de calcul, ou utilisation d'un module complémentaire précédemment installé dans ce document, formulaire, présentation ou feuille de calcul
Menu visible pour	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 ce que la fonction onOpen peut faire. 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 ou en exécutant des fonctions personnalisées. Si votre module complémentaire tente d'utiliser ces services dans onOpen, onInstall ou une portée globale, les autorisations échouent et les autres appels, tels que le remplissage des menus, s'arrêtent. L'aide est la seule option compatible.

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 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 toutes les portées autorisées.

Seuls les modules complémentaires de l'éditeur publiés peuvent être en mode AuthMode.NONE ; les modules complémentaires de l'éditeur non publiés exécutent onOpen en mode AuthMode.LIMITED. Toutefois, est prévu dans les deux modes d'autorisation. Pour ce faire, testez un module complémentaire de l'éditeur.

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 ScriptScriptApp.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 Apps Script google.script.run. 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 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 fois) `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ètres régionaux uniquement	Paramètres régionaux uniquement	Paramètres régionaux uniquement	Oui
Accès au document, au formulaire, à la présentation ou à la 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 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 s'exécute.

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

Lorsqu'un module complémentaire de l'éditeur est installé à partir du 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 est déjà ouvert 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 est ouvert

Lorsqu'un document, un formulaire, une présentation ou une feuille de calcul s'ouvre, il charge tous les modules complémentaires de l'éditeur que l'utilisateur actuel a installés ou que tout collaborateur a activés dans le fichier, et appelle chacune de leurs fonctions onOpen. Le mode d'autorisation dans lequel onOpen s'exécute dépend de l'installation ou de l'activation d'un module complémentaire.

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 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();
}

Lorsque la fonction onOpen s'exécute, l'ensemble du script se charge et 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 s'exécutent pas. Si le module complémentaire publié ne parvient pas à ajouter ses éléments de menu, consultez la console 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.

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 elles 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 liés au rendu 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 :

Ouvrez le projet Apps Script de votre module complémentaire et recherchez la fonction onOpen.
Recherchez dans la fonction onOpen les mentions de services ou d'objets Apps Script associés, tels que PropertiesService, SpreadsheetApp ou GmailApp.
Si un service est utilisé pour autre chose que la création des éléments d'interface utilisateur, supprimez-le ou placez-le dans un bloc de commentaires. Ne laissez que les méthodes suivantes : .getUi, .createMenu, .addItem et .addToUi. Recherchez et supprimez également tout service qui se trouve en dehors d'une fonction.
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 produisent, et déplacez les appels de service vers les fonctions qui en ont besoin. Réorganisez ou réécrivez votre base de code pour tenir compte des modifications apportées aux étapes précédentes.
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 est défini sur Installé pour l'utilisateur actuel et que le texte sous la zone de configuration indique Test in AuthMode.NONE.
Lancez le déploiement de test et ouvrez le menu Extensions.
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.

Autorisation du module complémentaire de l'éditeur Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.