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 lorsque vous essayez de l'utiliser. Une fois autorisé, vous pouvez utiliser le projet de script librement. Toute personne utilisant le projet de script l'autorise séparément.

Le modèle d'autorisation pour les modules complémentaires de l'éditeur est plus complexe. Étant donné que ces modules complémentaires fonctionnent sur les fichiers stockés dans Google Drive (fichiers pouvant être partagés avec d'autres personnes), vous devez créer des modules complémentaires d'éditeur en gardant à l'esprit les différents modes d'autorisation. Les applications d'édition 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 ne les avez pas encore autorisés. Cela accroît la complexité du modèle d'autorisation.

Modèle d'autorisation

Les deux propriétés des modules complémentaires de l'éditeur les rendent particulièrement faciles à partager et à utiliser:

  • Une fois que vous avez obtenu un module complémentaire d'éditeur sur le Play Store, il apparaît dans le menu "Modules complémentaires" pour chaque document que vous ouvrez ou créez. Les collaborateurs travaillant sur ces documents ne verront pas le module complémentaire, sauf dans les documents où vous l'utilisez.
  • 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, étant donné qu'un module complémentaire de l'éditeur exécute automatiquement sa fonction onOpen(e) pour ajouter des éléments de menu à l'ouverture d'un document, le comportement ci-dessus ajoute de la complexité aux règles d'autorisation d'Apps Script. Après tout, les utilisateurs n'ont pas envie de disposer d'un module complémentaire pour accéder à leurs données à 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 vous voyez un module complémentaire d'éditeur dans le menu, cela signifie qu'il est installé ou activé. Un module complémentaire d'éditeur est installé pour un utilisateur particulier après qu'il a choisi ce module 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 Télécharger 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 précédemment installé dans ce document
Menu visible par Uniquement cet utilisateur, dans tous les documents qu'il ouvre ou crée Tous les collaborateurs de ce document
onOpen(e) s'exécute dans AuthMode.NONE (sauf s'il est également activé, auquel cas AuthMode.LIMITED)) AuthMode.LIMITED

Modes d'autorisation

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

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 Apps Script, e. La valeur de e.authMode correspond à une constante de l'énumération ScriptApp.AuthMode Apps Script.

Si un module complémentaire d'é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 seulement installé, onOpen(e) s'exécute dans AuthMode.NONE.

Le concept de modes d'autorisation s'applique à toutes les exécutions Apps Script, telles que l'exécution depuis 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, qui est semblable à LIMITED, mais comporte 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 moments, 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 Yes
Accès au document Non Yes Oui (lecture seule) Yes
Accès à l'interface utilisateur Ajouter des éléments au menu Ajouter des éléments au menu Non Yes
Accès à Properties Non Yes Yes Yes
Accès à Jdbc, UrlFetch Non Non Yes Yes
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. Il apparaît alors 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 d'é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 donc 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 tous les modules complémentaires de l'éditeur que l'utilisateur actuel a installés ou que tout collaborateur a activés 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 est installé ou activé.

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

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 du module complémentaire, Apps Script commence par vérifier si l'utilisateur a installé le module complémentaire, puis invite l'utilisateur à 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. Il s'active également dans le document, si ce n'est pas déjà fait.