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

Les utilisateurs doivent autoriser les modules complémentaires et d'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 démarrer le flux d'autorisation.

Au cours de ce flux, l'invite indique à l'utilisateur ce que l'application souhaite obtenir de son autorisation. Par exemple, un module complémentaire peut demander l'autorisation de lire les e-mails 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 comme des champs d'application OAuth.

Vous déclarez les champs d'application dans votre fichier manifeste à l'aide de chaînes d'URL. Au cours du flux d'autorisation, Apps Script présente à l'utilisateur une description lisible du champ d'application. Par exemple, votre module complémentaire peut utiliser le champ d'application "Lire le document actuel", é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 de ce champ d'application demande à l'utilisateur d'autoriser ce module: Afficher et gérer les documents dans lesquels cette application a été installée.

Affichage des niveaux d'accès

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

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

Vous pouvez également afficher les champs d'application actuels du projet de script dans le fichier manifeste du projet, sous le champ oauthScopes, mais uniquement si vous les avez définis explicitement.

Définir des champs d'application explicites

Apps Script détermine automatiquement les champs d'application dont un script a besoin en analysant son code à la recherche d'appels de fonction qui les nécessitent. Pour la plupart des scripts, cela est suffisant 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 le champ d'application très permissif https://mail.google.com à un projet de script de module complémentaire. Lorsqu'un utilisateur autorise un projet de script de ce champ d'application, le projet dispose d'un accès complet au compte Gmail de l'utilisateur. Pour les modules complémentaires publiés, vous devez remplacer ce champ d'application par un ensemble plus limité qui couvre les besoins des modules complémentaires, et aucun autre.

Vous pouvez définir explicitement les champs d'application utilisés par votre projet de script en modifiant son fichier manifest. Le champ du 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 actuellement utilisés par votre module complémentaire. Déterminez les modifications à apporter, par exemple en utilisant un champ d'application plus restreint.
  2. Ouvrez le fichier manifeste du module complémentaire.
  3. Recherchez le champ de premier niveau intitulé oauthScopes. S'il n'est pas présent, vous pouvez l'ajouter.
  4. Le champ oauthScopes spécifie un tableau de chaînes. Pour définir les champs d'application de votre projet, remplacez le contenu de ce tableau par ceux que vous souhaitez qu'il utilise. 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.currentonly"
      ],
      ...
    }
    

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

Validation OAuth

L'utilisation de certains champs d'application OAuth sensibles peut nécessiter la validation du client OAuth avant de pouvoir publier le module complémentaire. Pour en savoir plus, consultez les guides suivants :

Champs d'application restreints

Certains champs d'application sont limités et sont soumis à des règles supplémentaires qui contribuent à protéger les données utilisateur. Si vous avez l'intention de publier un module complémentaire Gmail ou Editor qui utilise un ou plusieurs champs d'application restreints, le module complémentaire doit respecter toutes les restrictions spécifiées pour pouvoir être publié.

Consultez la liste complète des niveaux d'accès restreints avant d'essayer de publier. Si votre module complémentaire utilise l'un d'entre eux, vous devez respecter les Exigences supplémentaires pour des champs d'application d'API spécifiques avant la publication.

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

Lorsque vous créez un module complémentaire de l'éditeur, les champs d'application requis sont déterminés par le service et les méthodes Apps Script que le code du module complémentaire utilise. Par exemple, un module complémentaire Sheets peut avoir besoin du champ d'application https://www.googleapis.com/auth/spreadsheets.readonly pour lire des informations à partir de différentes feuilles de calcul Google Sheets.

Apps Script détermine automatiquement les champs d'application requis par les services que vous utilisez lorsque vous ajoutez du code à votre projet de script. Pour les modules complémentaires des éditeurs, vous pouvez souvent vous appuyer sur cette collecte automatique des champs d'application au lieu de déterminer les champs d'application 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 Editor ne lit ou n'écrit que le fichier d'éditeur ouvert, ajoutez le commentaire suivant à l'un de vos fichiers de projet de script:

  /**
   * @OnlyCurrentDoc
   */

Ce commentaire indique à Apps Script de limiter les champs d'application du fichier d'é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 indiquez que le module complémentaire n'a besoin que d'une autorisation pour fonctionner sur la feuille de calcul 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 le module complémentaire Sheets doit lire ou écrire des données dans une feuille de calcul Sheets que l'utilisateur n'a pas ouverte.