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'un utilisateur tente pour l'utiliser.

Le modèle d'autorisation pour Modules complémentaires de l'éditeur est plus complexe pour plusieurs raisons:

• Lorsqu'un utilisateur crée un fichier, tous les modules complémentaires qu'il installe sont répertoriés dans le menu Extensions, même si si l'utilisateur n'a pas encore autorisé ces modules complémentaires.

• Ces modules complémentaires fonctionnent sur les fichiers dans Google Drive, que vous pouvez partager avec vos 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 des éditeurs exécutent automatiquement leur onOpen() à l'ouverture d'un document.

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 pouvez 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 après que l'administrateur ou lui-même l'ont obtenu Google Workspace Marketplace et l'autoriser à 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 quand quelqu'un l'utilise.
• Lorsque des personnes collaborent sur un fichier et que l'une d'entre elles utilise un complémentaire, il est installé pour un seul utilisateur, et enabled pour le fichier.

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

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 qu'il uniquement installé, onOpen() s'exécute dans AuthMode.NONE.

Dans AuthMode.NONE, un module complémentaire ne peut pas s'exécuter jusqu'à ce que l'utilisateur interagisse avec le module complémentaire cliquer ou exécuter 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 à un service restreint, vous devez utiliser l'autorisation AuthMode.FULL . Les 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 comme résultat. d'un déclencheur tel que onOpen(), onEdit() ou onInstall(). Fonctions personnalisées dans Google Sheets utilisent leur propre mode d'autorisation, AuthMode.CUSTOM_FUNCTION, qui est semblable à LIMITED, mais avec 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.

Cycle de vie des autorisations d'un module complémentaire Editor

Lorsqu'un module complémentaire est installé pour l'utilisateur actuel ou activée dans le fichier actuel, le module complémentaire est chargé pour le document, le formulaire, la présentation, ou 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'élément de menu Extensions, il s'exécute.

Le module complémentaire Éditeur est installé

Lorsqu'un module complémentaire d'éditeur est installé depuis la boutique, son La fonction onInstall() s'exécute dans AuthMode.FULL. Dans ce mode d'autorisation, peut exécuter une routine de configuration complexe. Vous devez également utiliser onInstall() pour créer des éléments de menu, puisque le document, le formulaire, la présentation, ou la feuille de calcul est déjà ouverte et la 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 s'ouvre.

Lorsqu'un document, un formulaire, une présentation ou une feuille de calcul s'ouvre, il charge tous les ou des modules complémentaires de l'éditeur installés par l'utilisateur actuel activée par un collaborateur dans le fichier, chacune de leurs fonctions onOpen(). Le mode d'autorisation onOpen() s'exécute selon qu'un module complémentaire est installée ou activée.

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();
}

Ajouter des éléments de menu dynamique basés sur Apps Script stockés properties pour lire le contenu des le fichier en cours ou pour effectuer d'autres tâches avancées, doit 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 sa 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é la un module complémentaire, et 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. La est activé dans le document, le formulaire une présentation ou une feuille de calcul si ce n'est déjà fait.

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

Il est possible que le menu du 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 un utilisateur interagit avec elle.

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 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é à autre chose que la création des éléments d'interface utilisateur, le supprimer ou l'encapsuler dans un bloc de commentaires. Ne conservez que les méthodes suivantes: .getUi(), .createMenu(), .addItem(), et .addToUi(). Recherchez et supprimez également tout service extérieur à une fonction.
4. Identifier 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 produisent, et déplacer 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 lors des é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 en dessous de la zone de configuration indique 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.

Articles associés

• Applications Web
• Types de modules complémentaires
• Tester un module complémentaire de l'éditeur