Autorisation du module complémentaire de l'éditeur

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Dans la plupart des cas, vous devez autoriser un module complémentaire avant de pouvoir l'utiliser. Pour de nombreux projets Apps Script, tels que les applications Web, l'autorisation est simple : le projet de script demande toutes les autorisations manquantes dont il a besoin pour l'utiliser. Une fois autorisé, vous pouvez utiliser le projet de script librement. Tous les utilisateurs du projet de script l'autorisent séparément.

Le modèle d'autorisation des modules complémentaires d'éditeurs est plus complexe. Étant donné que ces modules complémentaires fonctionnent sur des fichiers résidant dans Google Drive (fichiers pouvant être partagés avec d'autres personnes), vous devez créer des modules complémentaires d'éditeur pour les différents modes d'autorisation. Les applications de l'éditeur Google Workspace proposent également un menu Modules complémentaires dans leur interface utilisateur, qui est renseigné par les modules complémentaires que vous avez installés, même si vous n'avez pas encore autorisé ces modules. Cela ajoute une complexité supplémentaire au modèle d'autorisation.

Modèle d'autorisation

Deux propriétés des modules complémentaires d'éditeur les rendent particulièrement faciles à partager et à utiliser:

  • Une fois que vous avez obtenu un module complémentaire d'éditeur dans la boutique, il apparaît dans le menu "Modules complémentaires" pour chaque document que vous ouvrez ou créez. Les collaborateurs de ces documents ne verront pas le module complémentaire, sauf dans les documents où vous l'utilisez réellement.
  • Une fois que vous avez utilisé un module complémentaire d'éditeur dans un document, vos collaborateurs le voient également dans le menu "Modules complémentaires", mais uniquement pour ce document (sauf s'ils ont également installé ce module).

Ce modèle de partage semble naturel pour la plupart des utilisateurs. Toutefois, comme le module complémentaire de l'éditeur exécute automatiquement sa fonction onOpen(e) pour ajouter des éléments de menu lorsqu'un document s'ouvre, le comportement ci-dessus ajoute une certaine complexité aux règles d'autorisation d'Apps Script. Après tout, les utilisateurs n'ont pas envie d'accéder à des données personnelles chaque fois qu'ils ouvrent un document. Ce guide doit vous aider à comprendre ce que votre code peut faire et quand.

Installée ou activée

Si un module complémentaire de l'éditeur s'affiche dans le menu, il se trouve dans l'un des deux états suivants, ou dans les deux. Un module complémentaire de l'éditeur est installé pour un utilisateur particulier après qu'il a choisi le module complémentaire sur le Play Store et l'autorise à accéder à ses données Google. En revanche, un module complémentaire est activé dans un document donné lorsque tout le monde l'utilise. Si deux personnes collaborent sur un document et que l'une d'entre elles utilise un module complémentaire, celui-ci est installé pour l'utilisateur et activé pour le document.

Le tableau ci-dessous récapitule les deux états. Notez que lorsque vous testez un script en tant que module complémentaire, vous pouvez choisir d'exécuter le test dans l'un de ces états, ou dans les deux.

Installé Activés
Applies to Utilisateur Document
Causée par Obtenir un module complémentaire sur le Play Store Obtenir un module complémentaire du Play Store lorsque vous utilisez ce document
Utiliser un module complémentaire déjà installé dans ce document
Menu visible par Seul cet utilisateur, dans tous les documents qu'il ouvre ou crée Tous les collaborateurs de ce document
onOpen(e) course sur AuthMode.NONE (sauf s'il est également activé, auquel cas AuthMode.LIMITED)) AuthMode.LIMITED

Modes d'autorisation

Un module complémentaire d'éditeur exécute automatiquement sa fonction onOpen(e) pour ajouter des éléments de menu lorsqu'un document s'ouvre. Toutefois, pour protéger les données des utilisateurs, Apps Script limite la fonction de la fonction onOpen(e). Si le module complémentaire n'a pas été utilisé dans le document actuel, ces restrictions deviennent plus graves.

Plus précisément, les états installés et activés déterminent le mode d'autorisation dans lequel la fonction onOpen(e) s'exécute. Apps Script transmet le mode d'autorisation en tant que propriété authMode du paramètre d'événement e (Apps Script). La valeur de e.authMode correspond à une constante de l'énumération ScriptApp.AuthMode Apps Script.

Si un module complémentaire de l'éditeur est activé dans le document actuel, onOpen(e) s'exécute dans AuthMode.LIMITED. Si le module complémentaire n'est pas activé et qu'il est installé uniquement, onOpen(e) s'exécute dans AuthMode.NONE.

Le concept de modes d'autorisation s'applique à toutes les exécutions Apps Script, telles que leur exécution à partir de l'éditeur de scripts, à un élément de menu ou à un appel google.script.run Apps Script, bien que la propriété e.authMode ne puisse être inspectée que si le script s'exécute à la suite d'un déclencheur tel que onOpen(e), onEdit(e) ou onInstall(e). Les fonctions personnalisées de Google Sheets utilisent leur propre mode d'autorisation, AuthMode.CUSTOM_FUNCTION, semblable à LIMITED, mais présente des restrictions légèrement différentes. Le reste du temps, les scripts s'exécutent dans AuthMode.FULL, comme indiqué dans le tableau ci-dessous.

NONE LIMITED CUSTOM_FUNCTION FULL
Se produit pour onOpen(e) (si l'utilisateur a installé un module complémentaire, mais qu'il ne l'a pas activé dans le document) onOpen(e) (toutes les autres heures)
onEdit(e) (uniquement dans Sheets)		 Fonctions personnalisées Tous les autres horaires, y compris:
Déclencheurs installables
onInstall(e)
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 Non Oui Oui (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, 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 complet

Si un module complémentaire est installé pour l'utilisateur actuel ou activé dans le document actuel, il est chargé dans le document, ce qui le fait apparaître dans le menu "Modules complémentaires" et commence à écouter les déclencheurs simples onInstall(e), onOpen(e) et onEdit(e). Si un utilisateur clique sur l'un des éléments de menu du module complémentaire, il s'exécute.

Installation

Lorsqu'un module complémentaire de l'éditeur est installé à partir du magasin, sa fonction onInstall(e) s'exécute dans AuthMode.FULL. Cela permet au module complémentaire d'exécuter une routine de configuration complexe. Toutefois, il est important d'utiliser onInstall(e) pour créer des éléments de menu, car le document est déjà ouvert et votre fonction onOpen(e) n'a pas été exécutée. Pour plus de commodité, vous pouvez simplement appeler onOpen(e) à partir de onInstall(e), comme illustré dans cet exemple:

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

Ouverture

Lorsqu'un document s'ouvre, il charge chaque module complémentaire de l'éditeur que l'utilisateur actuel a installé ou qu'un collaborateur a activé dans le document, et appelle chacune de ses fonctions onOpen(e). Le mode d'autorisation utilisé par onOpen(e) varie selon que le module complémentaire a été installé ou activé.

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

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

Toutefois, si vous souhaitez ajouter des éléments de menu dynamiques basés sur les propriétés Apps Script stockées, lire le contenu du document actuel ou effectuer d'autres tâches avancées, vous devez détecter le mode d'autorisation et le gérer de manière appropriée. Cet exemple montre à quoi peut ressembler une fonction onOpen(e) avancée, en modifiant son comportement 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();
}

Running

Lorsqu'un utilisateur clique sur l'un des éléments de menu d'un module complémentaire, Apps Script vérifie d'abord si l'utilisateur l'a installé et invite à le faire. 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 également activé dans le document, si ce n'est pas déjà fait.