Autorisation du module complémentaire Editor

L'autorisation de nombreuses applications basées sur Apps Script est simple, car 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 pour 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 pouvant être partagés avec des collaborateurs. Les collaborateurs qui n'ont pas installer le module complémentaire Éditeur le consulter dans les documents où le créateur du fichier l'a utilisé.

  • Les modules complémentaires Editor 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 afin que certains services non disponible pour onOpen(). Ce guide peut vous aider à comprendre ce que votre code peut faire et quand.

Modèle d'autorisation

Le mode d'autorisation d'un module complémentaire Editor son état, qui dépend de l'utilisateur: l'utilisateur qui a installé le module complémentaire. ou un collaborateur.

États des modules complémentaires d'éditeur

Dans le menu Extensions, les modules complémentaires de l'éditeur sont installé, activé ou les deux.

  • Un module complémentaire est installé pour un utilisateur particulier après que lui ou son administrateur l'ont obtenu sur 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 lorsqu'un utilisateur l'utilise.
  • Lorsque des utilisateurs collaborent sur un fichier et que l'un d'eux utilise un module complémentaire, il est installé pour cet utilisateur et activé pour le fichier.

Le tableau suivant récapitule les différences entre les versions "installée" et "activée". Notez que lorsque vous testez un script en tant que module complémentaire, vous pouvez exécuter le test dans l'un ou l'autre de ces états, ou dans les deux.

Installée Activé
Applicable à Utilisateur Document, formulaire, présentation ou feuille de calcul
Causée par Obtenir un module complémentaire depuis le magasin Obtenir un module complémentaire depuis le Play Store lorsque vous utilisez ce document, ce formulaire, cette présentation ou cette feuille de calcul
Utiliser un module complémentaire déjà installé dans ce document, ce formulaire, cette présentation ou cette feuille de calcul
Menu visible par Seul cet utilisateur, dans tous les documents, formulaires, présentations, ou des feuilles de calcul qu'ils ouvrent ou créent Tous les collaborateurs de ce document, formulaire, présentation ou feuille de calcul
Mode d'autorisation pour onOpen() AuthMode.NONE
(sauf si elle est également activée, auquel cas AuthMode.LIMITED)		 AuthMode.LIMITED

Modes d'autorisation

La fonction onOpen() d'un module complémentaire Editor 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 données, Apps Script limite ce que la fonction onOpen(). État du module complémentaire É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, formulaire, présentation ou feuille de calcul, onOpen() s'exécute AuthMode.LIMITED Si le module complémentaire n'est pas activé et n'est installé que, 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 dessus ou en exécutant des fonctions personnalisées. Si votre tente d'utiliser ces services dans onOpen(), onInstall() ou le champ d'application global, les autorisations échouent et d'autres appels, tels que pour remplir les menus, arrêter. "Aide" est la seule option acceptée.

Pour exécuter des appels de service restreints, vous devez utiliser le mode d'autorisation AuthMode.FULL. Fonctions d'interaction de l'utilisateur, comme cliquer sur une option de menu, ne s'exécuter que dans ce mode. Une fois le code exécuté en mode AuthMode.FULL, peut utiliser tous les niveaux d'accès autorisés par l'utilisateur.

Apps Script passe le mode autorisation en tant que propriété authMode d'Apps Script ; paramètre d'événement, e; la valeur de e.authMode correspond à une constante dans Apps Script. Énumération ScriptApp.AuthMode.

Les modes d'autorisation s'appliquent à toutes les méthodes d'exécution d'Apps Script, y compris depuis l'éditeur de script, un élément de menu ou un script Apps Script Appel 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. Pour tous Dans d'autres cas, les scripts s'exécutent dans AuthMode.FULL, comme décrit dans les tableau.

NONE LIMITED CUSTOM_FUNCTION FULL
Se produit pour onOpen() (si l'utilisateur a installé un mais que vous ne l'avez pas activé dans le document, le formulaire, présentation ou feuille de calcul) onOpen() (toutes les autres heures)
onEdit() (uniquement dans Sheets)		 Fonctions personnalisées Toutes les autres heures, 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 à un document, un formulaire, une présentation ou une feuille de calcul Non Oui Oui (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 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 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 téléchargé pour le document, le formulaire, la présentation ou la feuille de calcul lorsque ce fichier est ouvert. Le module complémentaire est dans le menu Extensions et commence à écouter 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 pour l'éditeur est installé depuis le Play 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 sont déjà ouverts 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 s'ouvre.

Lorsqu'un document, un formulaire, une présentation ou une feuille de calcul s'ouvre, il charge tous les de l'éditeur que l'utilisateur actuel a installé ou activé par un collaborateur dans le fichier, chacune de leurs fonctions onOpen(). Le mode d'autorisation dans lequel onOpen() s'exécute dépend de la présence ou non d'un module complémentaire 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 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 en fonction des 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 pendant leur exécution dans AuthMode.LIMITED Vous pouvez utiliser des éléments de menu pour ouvrir les barres latérales et les boîtes de dialogue, car elles sont exécutées 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 le script exécute la fonction correspond à 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 d'affichage des menus des modules complémentaires

Il est possible que le menu de votre module complémentaire ne s'affiche pas si votre code ne gère pas correctement les modes d'autorisation. Exemple :

  • Un module complémentaire tente d'exécuter un script Apps Script qui n'est pas pris en charge par 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 :

  1. Ouvrez le projet Apps Script correspondant à votre module complémentaire et recherchez la fonction onOpen().
  2. Rechercher les mentions d'Apps Script dans la fonction onOpen() ou objets qui leur sont associés, 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 commentaires. Ne laissez que les méthodes suivantes : .getUi(), .createMenu(), .addItem() et .addToUi(). Recherchez et supprimez également tout service en dehors d'une fonction.
  4. 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 génèrent, puis déplacez les appels de service vers les fonctions qui en ont besoin. Réorganiser ou réécrire votre codebase pour s'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 de test, assurez-vous que le champ Config (Configuration) est défini sur Installed for current user (Installé 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 de test, puis ouvrez le menu Extensions.

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