Cette page a été traduite par l'API Cloud Translation.

Autorisation du module complémentaire Editor

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 vous avez 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 de l'éditeur est plus complexe. Étant donné que ces modules complémentaires fonctionnent sur des fichiers stockés dans Google Drive (fichiers pouvant être partagés avec d'autres personnes), vous devez créer des modules complémentaires de l'éditeur en tenant compte des différents modes d'autorisation. Les éditeurs Google Docs fournissent également un menu Modules complémentaires dans leurs UI, renseigné par les modules complémentaires que vous avez installés, même si vous n'avez pas encore autorisé ces modules complémentaires. Cela ajoute une complexité supplémentaire au modèle d'autorisation.

Modèle d'autorisation

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 de l'éditeur sur le magasin, il apparaît dans le menu des modules complémentaires pour chaque document, formulaire, présentation ou feuille de calcul que vous ouvrez ou créez. Les collaborateurs ne verront pas le module complémentaire, sauf dans les documents, les formulaires, les présentations et les feuilles de calcul où vous l'utilisez réellement.
Une fois que vous avez utilisé un module complémentaire d'éditeur dans un document, un formulaire, une présentation ou une feuille de calcul, vos collaborateurs y ont également accès dans le menu des modules complémentaires, mais uniquement pour ce fichier (sauf s'ils ont également installé ce module complémentaire).

Ce modèle de partage semble naturel pour la plupart des utilisateurs. Toutefois, comme un module complémentaire d'éditeur exécute automatiquement sa fonction onOpen(e) pour ajouter des éléments de menu lorsqu'un éditeur Google Docs s'ouvre, le comportement ci-dessus complique les règles d'autorisation d'Apps Script. En effet, les utilisateurs n'auraient pas envie de disposer d'un module complémentaire pour accéder à leurs données personnelles à chaque fois qu'ils ouvrent un document, un formulaire, une présentation ou une feuille de calcul. Ce guide doit vous aider à comprendre ce que le code peut faire et quand.

Installée ou activée

Si un module complémentaire d'éditeur s'affiche dans le menu, il existe deux états : installé et activé. Un module complémentaire d'é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, un formulaire, une présentation ou une feuille de calcul spécifiques lorsqu'il est utilisé par un autre utilisateur. Si deux personnes collaborent et que l'une d'elles utilise un module complémentaire, celui-ci est installé pour le même utilisateur et activé pour le fichier.

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 ou l'autre de ces états, ou dans les deux.

	Installé	Activées
Applies to	Utilisateur	Document, formulaire, présentation ou feuille de calcul
Causée par	Obtenir un module complémentaire sur la boutique	Obtenir un module complémentaire sur la boutique lorsqu'il utilise ce document, formulaire, présentation ou feuille de calcul Utiliser un module complémentaire déjà installé dans ce document, formulaire, présentation ou 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 sur ce document, ce formulaire, cette présentation ou cette feuille de calcul
`onOpen(e)` s'exécute dans	`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, un formulaire, une présentation ou une feuille de calcul s'ouvre. 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, le formulaire, la présentation ou la feuille de calcul actuels, ces restrictions deviennent plus strictes.

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 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, le formulaire, la présentation ou la feuille de calcul actuels, onOpen(e) s'exécute dans AuthMode.LIMITED. Si le module complémentaire n'est pas activé et n'est installé que, onOpen(e) s'exécute dans AuthMode.NONE.

Le concept de mode 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, semblable à LIMITED, mais qui comporte des restrictions légèrement différentes. Le reste du temps, les scripts s'exécutent dans AuthMode.FULL, comme détaillé 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 ne l'a pas activé dans le document, le formulaire, la présentation ou la feuille de calcul)	`onOpen(e)` (toutes les autres fois) `onEdit(e)` (uniquement dans Sheets)	Fonctions personnalisées	Autres heures: 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, au formulaire, à la présentation ou à la feuille de calcul	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	Oui	Oui
Accès à `Jdbc`, `UrlFetch`	Non	Non	Oui	Oui
Autres services	`Logger` `Utilities`	Les services qui n'accèdent pas aux données utilisateur	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 fichier actuel, il est chargé dans le document, le formulaire, la présentation ou la feuille de calcul. Il apparaît alors dans le menu des 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, mais il est également important d'utiliser onInstall(e) 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(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 l'exemple suivant:

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

Ouverture

Lorsqu'un document, un formulaire, une présentation ou une feuille de calcul s'ouvre, il charge chaque module complémentaire de l'éditeur que l'utilisateur actuel a installé ou que tout collaborateur a activé dans le fichier, 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 ne crée qu'un menu de base, le mode n'a pas d'importance. Cet exemple montre à quoi pourrait ressembler une 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 en fonction des propriétés Apps Script stockées, lire le contenu du document, du formulaire, de la présentation ou de la feuille de calcul actuels, 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();
}

En cours

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 a installé le module complémentaire, puis 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. Il s'active également dans le document, le formulaire, la présentation ou la feuille de calcul, si ce n'est pas déjà fait.