Champs d'application des autorisations pour les modules complémentaires d'éditeur

Les utilisateurs doivent autoriser les modules complémentaires et autres applications qui accèdent à leurs données ou agissent en leur nom. Lorsqu'un utilisateur exécute un module complémentaire pour la première fois, l'interface utilisateur du module complémentaire affiche une invite d'autorisation pour démarrer le flux d'autorisation.

Au cours de ce flux, l'invite indique à l'utilisateur ce que l'application souhaite faire. Par exemple, un module complémentaire peut demander l'autorisation de lire le message électronique d'un utilisateur ou de créer des événements dans son agenda. Le projet de script du module complémentaire définit ces autorisations individuelles en tant que niveaux d'accès OAuth.

Vous déclarez les niveaux d'accès dans votre fichier manifeste à l'aide de chaînes d'URL. Pendant le flux d'autorisation, Apps Script présente à l'utilisateur une description lisible du niveau d'accès. Par exemple, votre module complémentaire peut utiliser le niveau d'accès "Lire le document actuel", qui est écrit dans votre fichier manifeste sous la forme https://www.googleapis.com/auth/documents.currentonly. Pendant le flux d'autorisation, un module complémentaire avec ce niveau d'accès demande à l'utilisateur d'autoriser le module complémentaire à : Afficher et gérer les documents dans lesquels cette application a été installée.

Remarque : Le niveau d'accès currentonly n'est disponible que dans les services Apps Script Services. Cela n'inclut pas les services avancés Apps Script ni les appels directs aux API Google Workspace.

Les niveaux d'accès utilisés par Apps Script pour ses différents services se chevauchent avec ceux utilisés par l'API associée. Par exemple, le service Agenda d'Apps Script utilise de nombreux niveaux d'accès identiques à ceux de l'API Agenda. Vous pouvez rechercher les niveaux d'accès requis par des méthodes de service Apps Script spécifiques dans la documentation de référence Apps Script .

Afficher les champs d'application

Pour afficher les niveaux d'accès actuellement requis par votre projet de script, procédez comme suit :

1. Ouvrez le projet de script.
2. À gauche, cliquez sur Présentation .
3. Affichez les niveaux d'accès sous "Niveaux d'accès OAuth du projet".

Vous pouvez également afficher les niveaux d'accès actuels du projet de script dans le fichier manifeste du projet, sous le champ oauthScopes, mais uniquement si vous avez défini ces niveaux d'accès de manière explicite.

Définir des niveaux d'accès explicites

Apps Script détermine automatiquement les niveaux d'accès dont un script a besoin en analysant son code pour détecter les appels de fonction qui les requièrent. Pour la plupart des scripts, cela suffit et vous fait gagner du temps, mais pour les modules complémentaires publiés, vous devez exercer un contrôle plus direct sur les niveaux d'accès.

Par exemple, Apps Script peut attribuer par défaut au projet de script d'un module complémentaire le niveau d'accès très permissif https://mail.google.com. Lorsqu'un utilisateur autorise un projet de script avec ce niveau d'accès, le projet bénéficie d'un accès complet au compte Gmail de l'utilisateur. Pour les modules complémentaires publiés, vous devez remplacer ce niveau d'accès par un ensemble plus limité qui couvre les besoins des modules complémentaires, et rien de plus.

Avertissement : Utilisez toujours l'ensemble de niveaux d'accès le moins permissif possible. Pour protéger les informations des utilisateurs, les modules complémentaires et autres applications publiées ne doivent jamais demander plus d'autorisations de niveau d'accès que nécessaire. Les niveaux d'accès requis par votre module complémentaire sont examinés lors du processus d'examen du module complémentaire de publication. Si le module complémentaire utilise des niveaux d'accès trop larges, il ne peut pas être approuvé.

Vous pouvez définir explicitement les niveaux d'accès utilisés par votre projet de script en modifiant son fichier manifeste. Le champ du fichier manifeste oauthScopes est un tableau de tous les niveaux d'accès utilisés par le module complémentaire. Pour définir les niveaux d'accès de votre projet, procédez comme suit :

1. Affichez les niveaux d'accès utilisés par votre module complémentaire. Déterminez les modifications à apporter, par exemple en utilisant un niveau d'accès plus étroit.
2. Ouvrez le fichier manifeste de votre module complémentaire.
3. Recherchez le champ de premier niveau libellé oauthScopes. S'il n'est pas présent, vous pouvez l'ajouter.

4. Le oauthScopes champ spécifie un tableau de chaînes. Pour définir les niveaux d'accès utilisés par votre projet, remplacez le contenu de ce tableau par les niveaux d'accès que vous souhaitez utiliser. Par exemple, pour un module complémentaire de l'éditeur qui étend Sheets, vous pouvez avoir les éléments suivants :

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/script.container.ui",
        "https://www.googleapis.com/auth/spreadsheets"
      ],
      ...
    }
   

5. Enregistrez les modifications apportées au fichier manifeste.

Validation OAuth

L'utilisation de certains niveaux d'accès OAuth sensibles peut nécessiter que votre module complémentaire soit soumis à la validation du client OAuth avant de pouvoir le publier. Pour en savoir plus, consultez les guides suivants :

• Validation du client OAuth pour Apps Script
• Applications non validées
• Questions fréquentes sur la validation OAuth
• Règlement relatif aux données utilisateur dans les services d'API Google

Niveaux d'accès restreints

Certains niveaux d'accès sont restreints et soumis à des règles supplémentaires qui contribuent à protéger les données des utilisateurs. Si vous prévoyez de publier un module complémentaire Gmail ou de l'éditeur qui utilise un ou plusieurs niveaux d'accès restreints, le module complémentaire doit respecter toutes les restrictions spécifiées avant de pouvoir être publié.

Consultez la liste complète des niveaux d'accès restreints avant de tenter de publier. Si votre module complémentaire en utilise vous devez respecter les exigences supplémentaires pour les niveaux d'accès d'API spécifiques avant de publier.

Remarque : Évitez d'utiliser des niveaux d'accès restreints dans votre module complémentaire si vous le pouvez. Il est plus facile de réussir l'examen du module complémentaire pour une publication publique si vous ne les utilisez pas. Vous pouvez utiliser librement des niveaux d'accès restreints pour les modules complémentaires non publics.

L'extension Google Workspace Developer Tools pour Visual Studio Code fournit des informations de diagnostic pour tous les niveaux d'accès, y compris la description du niveau d'accès et s'il est sensible ou restreint.

Niveaux d'accès des modules complémentaires de l'éditeur

Lorsque vous créez un module complémentaire de l'éditeur, les niveaux d'accès requis sont déterminés par le service et les méthodes Google Apps Script utilisés par le code du module complémentaire. Par exemple, un module complémentaire Google Sheets peut avoir besoin du niveau d'accès https://www.googleapis.com/auth/spreadsheets.readonly pour lire des informations provenant de différentes feuilles.

Apps Script détermine automatiquement les niveaux d'accès requis par les services que vous utilisez lorsque vous ajoutez du code à votre projet de script. Pour les modules complémentaires de l'éditeur, vous pouvez souvent vous contenter de cette collecte automatique de niveaux d'accès au lieu de déterminer vous-même les niveaux d'accès et de les définir explicitement.

Si vous ne définissez pas explicitement vos niveaux d'accès et que votre module complémentaire de l'éditeur ne lit ou n'écrit que dans le fichier de l'éditeur ouvert, ajoutez le commentaire suivant à l'un des fichiers de votre projet de script :

/**
 * @OnlyCurrentDoc
 */

Ce commentaire indique à Apps Script de limiter les niveaux d'accès du fichier de l'éditeur qu'il définit sur currentonly. Par exemple, si vous ajoutez ce commentaire à un fichier de projet de script de module complémentaire Sheets, vous spécifiez que le module complémentaire n'a besoin que de l'autorisation d'opérer sur la feuille ouverte, et non sur les autres feuilles que l'utilisateur peut avoir dans Google Drive. À l'inverse, vous ne devez pas utiliser ce commentaire si votre module complémentaire Sheets doit lire ou écrire des données dans une feuille que l'utilisateur n'a pas ouverte.

Remarque : Le niveau d'accès currentonly n'est disponible que dans les services Apps Script Services. Cela n'inclut pas les services avancés Apps Script ni les appels directs aux API Google Workspace.