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

Les utilisateurs doivent autoriser les modules complémentaires et les 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 présente une invite d'autorisation pour lancer 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 d'e-mail 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 champs d'application OAuth.

Vous déclarez des champs d'application dans votre manifest à l'aide de chaînes d'URL. Au cours du flux d'autorisation, Apps Script présente à l'utilisateur une description lisible par l'humain du champ d'application. Par exemple, votre module complémentaire peut utiliser le champ d'application "Lire le document actuel", qui est écrit dans votre fichier manifeste sous la forme https://www.googleapis.com/auth/documents.currentonly. Au cours du flux d'autorisation, un module complémentaire avec ce champ d'application 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 champ d'application currentonly n'est disponible que dans les services Apps Script. Cela n'inclut pas les services avancés Apps Script ni les appels directs aux API Google Workspace.

Remarque :Les champs d'application utilisés par Apps Script pour ses différents services chevauchent les champs d'application utilisés par l'API associée. Par exemple, le service Agenda d'Apps Script utilise de nombreux champs d'application identiques à ceux de l'API Agenda. Vous pouvez consulter les champs d'application requis par certaines méthodes de service Apps Script dans la documentation de référence d'Apps Script.

Afficher les champs d'application

Pour afficher les champs d'application actuellement requis par votre projet de script, procédez comme suit:

1. Ouvrez le projet de script.
2. Sur la gauche, cliquez sur Vue d'ensemble .
3. Consultez les habilitations sous "Champs d'application OAuth du projet".

Vous pouvez également afficher les portées actuelles du projet de script dans le fichier manifeste du projet, sous le champ oauthScopes, mais uniquement si vous avez défini ces portées explicitement.

Définir des champs d'application explicites

Apps Script détermine automatiquement les portées dont un script a besoin en analysant son code à la recherche d'appels de fonction qui en ont besoin. 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 champs d'application.

Par exemple, Apps Script peut attribuer par défaut la portée https://mail.google.com très permissive à un projet de script de module complémentaire. Lorsqu'un utilisateur autorise un projet de script avec ce champ d'application, 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 cette portée par un ensemble plus limité qui couvre les besoins des modules complémentaires et pas plus.

Avertissement :Utilisez toujours le champ d'application le moins permissif possible. Pour protéger les informations utilisateur, les modules complémentaires et les autres applications publiées ne doivent jamais demander plus d'autorisations de portée qu'elles n'en ont absolument besoin. Les portées requises par votre module complémentaire sont examinées lors du processus d'examen du module complémentaire. Si le module complémentaire utilise des portées trop larges, il ne peut pas être approuvé.

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

1. Affichez les champs d'application que votre module complémentaire utilise actuellement. Déterminez les modifications à apporter, par exemple en utilisant un champ d'application plus restreint.
2. Ouvrez le fichier manifeste de votre module complémentaire.
3. Recherchez le champ de niveau supérieur intitulé oauthScopes. Si elle n'est pas présente, vous pouvez l'ajouter.

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

   {
     ...
     "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 champs d'application OAuth sensibles peut nécessiter une validation du client OAuth avant que vous puissiez publier votre module complémentaire. 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ègles concernant les données utilisateur du service API Google

Champs d'application restreints

Certains champs d'application sont restreints et soumis à des règles supplémentaires qui aident à protéger les données utilisateur. Si vous souhaitez publier un module complémentaire Gmail ou Éditeur qui utilise un ou plusieurs champs d'application restreints, il doit respecter toutes les restrictions spécifiées avant de pouvoir être publié.

Consultez la liste complète des champs d'application limités avant de tenter de publier. Si votre module complémentaire en utilise un, vous devez respecter les exigences supplémentaires pour les champs d'application d'API spécifiques avant de le publier.

Remarque :Évitez d'utiliser des champs d'application limités dans votre module complémentaire si possible. Il est plus facile de passer l'examen du module complémentaire pour sa publication publique si vous ne les utilisez pas. Vous pouvez utiliser librement des champs d'application limités pour les modules complémentaires non publics.

Champs d'application des modules complémentaires de l'éditeur

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

Apps Script détermine automatiquement les portées requises par les services que vous utilisez lorsque vous ajoutez du code à votre projet de script. Pour les modules complémentaires Editor, vous pouvez souvent vous contenter de vous appuyer sur cette collecte automatique des champs d'application au lieu de les déterminer vous-même et de les définir explicitement.

Si vous ne définissez pas explicitement vos champs d'application et que votre module complémentaire Éditeur ne lit ni n'écrit que dans le fichier de l'éditeur ouvert, ajoutez le commentaire suivant à l'un de vos fichiers de projet de script:

  /**
   * @OnlyCurrentDoc
   */

Ce commentaire indique à Apps Script d'affiner les portées de 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 Google Sheets, vous spécifiez que le module complémentaire n'a besoin que de l'autorisation d'exécuter des opérations sur la feuille actuellement ouverte, et non sur les autres feuilles que l'utilisateur pourrait 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 encore ouverte.

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