Autorisation du module complémentaire Editor

L'autorisation pour de nombreuses applications basées sur Apps Script est simple, car le projet de script demande toutes les autorisations manquantes dont il a besoin lorsqu'une personne 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 installés par l'utilisateur sont répertorié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 des éditeurs exécutent automatiquement leurs fonctions onOpen() à l'ouverture d'un document.

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 à quel moment.

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 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 des éditeurs du menu Extensions sont installés, activés ou les deux.

  • Un module complémentaire est installé pour un utilisateur donné après que lui-même ou son administrateur l'a obtenu depuis 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 lorsque tout le monde l'utilise.
  • Lorsque des personnes collaborent sur un fichier et que l'un d'eux utilise un module complémentaire, celui-ci est installé pour l'utilisateur concerné 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 de ces états ou les deux.

Installé Activées
Applicable à Utilisateur Document, formulaire, présentation ou feuille de calcul
Causée par Obtenir un module complémentaire auprès de la boutique obtenir un module complémentaire à partir de la boutique lorsque vous utilisez le document, le formulaire, la présentation ou la feuille de calcul, ou
l'utilisation d'un module complémentaire précédemment installé dans ce document, formulaire, présentation ou feuille de calcul ;
Menu visible par Uniquement cet utilisateur, et ce, 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 de la fonction onOpen(). 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 d'é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 le module complémentaire en cliquant ou en exécutant des fonctions personnalisées. Si votre module complémentaire tente d'utiliser ces services dans onOpen(), onInstall() ou dans un champ d'application global, les autorisations échouent et d'autres appels, tels que le remplissage des menus, arrêtez. 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 autorisés par l'utilisateur.

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 de l'énumération ScriptApp.AuthMode Apps Script.

Les modes d'autorisation s'appliquent à toutes les méthodes d'exécution Apps Script, y compris celles exécutées depuis l'éditeur de script, un élément de menu ou 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 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() (le reste du temps)
onEdit() (uniquement dans Sheets)
Fonctions personnalisées Le reste du temps, 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 au menu Ajouter des éléments au menu Non Oui
Accès à Properties Non Oui Yes Oui
Accès à Jdbc et 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 des autorisations 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 à l'ouverture du fichier. Le module complémentaire est répertorié 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, celui-ci s'exécute.

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

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

Lorsqu'un document, un formulaire, une présentation ou une feuille de calcul s'ouvre, il charge chaque module complémentaire d'éditeur que l'utilisateur actuel a installé ou qu'un collaborateur a activé dans le fichier, et appelle chacune de ses fonctions onOpen(). Le mode d'autorisation dans lequel onOpen() s'exécute varie selon que le 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 les 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();
}

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 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 dans le cas contraire. Si l'utilisateur a autorisé le module complémentaire, le script exécute la fonction correspondant à l'élément de menu dans AuthMode.FULL. S'il ne l'était pas déjà, le module complémentaire est activé dans le document, le formulaire, la présentation ou la feuille de calcul.

Résoudre les problèmes d'affichage des menus complémentaires

Le menu du 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, essayez les actions suivantes:

  1. Ouvrez le projet Apps Script de votre module complémentaire et localisez la fonction onOpen().
  2. Dans la fonction onOpen(), recherchez les 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 commentaire. Ne laissez que les méthodes suivantes: .getUi(), .createMenu(), .addItem() et .addToUi(). Recherchez et supprimez également tout service ne faisant pas partie d'une fonction.
  4. Identifiez les fonctions pouvant 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, puis déplacez les appels de service vers les fonctions qui en ont besoin. Réorganisez ou réécrivez votre codebase pour l'adapter aux modifications apportées aux étapes précédentes.
  5. Enregistrez le code et créez un déploiement test.

    Lorsque vous créez un déploiement test, assurez-vous que le champ Config est Installée 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 test et ouvrez le menu Extensions.

  7. Si tous les éléments du menu sont affichés, 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.