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.
Installée | Activées | |
---|---|---|
Applicable à | Utilisateur | Document, formulaire, présentation ou feuille de calcul |
Causée par | Obtenir un module complémentaire sur le Play Store | Obtention d'un module complémentaire sur le Play Store lors de l'utilisation
ce document, ce formulaire, cette présentation ou cette feuille de calcul, ou L'utilisation d'un module complémentaire déjà installé Document, formulaire, présentation ou 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 sur 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 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.
NONE |
LIMITED |
CUSTOM_FUNCTION |
FULL |
|
---|---|---|---|---|
Concerne | 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 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 Editor 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 crée uniquement 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:
- Ouvrez le projet Apps Script correspondant à votre module complémentaire et recherchez
la fonction
onOpen()
. - Rechercher les mentions d'Apps Script dans la fonction
onOpen()
ou objets qui leur sont associés,PropertiesService
,SpreadsheetApp
ouGmailApp
. - 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. - 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.
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
Lancez le déploiement de test, puis ouvrez le menu Extensions.
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.