Champs d'application

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 processus, l'invite indique à l'utilisateur ce que l'application souhaite faire avec l'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 en tant que scopes 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 du champ d'application lisible par un humain. Par exemple, votre module complémentaire Google Workspace peut utiliser le champ d'application "Lire le message actuel", qui est écrit dans votre fichier manifeste sous la forme https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Lors du flux d'autorisation, un module complémentaire avec ce champ d'application demande à l'utilisateur d'autoriser le module complémentaire à consulter ses e-mails lorsque le module complémentaire est en cours d'exécution.

Les niveaux d'accès utilisés par Apps Script pour ses différents services chevauchent 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 Calendar. Vous pouvez rechercher les niveaux d'accès requis par les méthodes de service Apps Script spécifiques 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 info_outline.
3. Affichez les habilitations sous "Project OAuth Scopes" (Habilitations 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 niveaux d'accès explicites

Apps Script détermine automatiquement les autorisations dont un script a besoin en analysant son code pour identifier 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 champ d'application très permissif https://mail.google.com. Lorsqu'un utilisateur autorise un projet de script avec ce champ d'application, le projet obtient 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 du module complémentaire, et rien de plus.

Vous pouvez définir explicitement les autorisations utilisées par votre projet de script en modifiant son fichier manifeste. 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 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 champ d'application plus étroit.
2. Ouvrez le fichier manifeste de votre module complémentaire.
3. Recherchez le champ de premier niveau 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 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 Google Workspace qui étend Gmail, vous pouvez avoir les éléments suivants :

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      ...
    }
   

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 passe par la validation du client OAuth avant de pouvoir être publié. 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 permettent de protéger les données utilisateur. Si vous prévoyez de publier un module complémentaire Gmail ou de l'é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 restreints avant de tenter de publier. Si votre module complémentaire en utilise, vous devez respecter les exigences supplémentaires pour les champs d'application d'API spécifiques avant de le publier.

L'extension Google Workspace Developer Tools pour Visual Studio Code fournit des informations de diagnostic pour tous les champs d'application, y compris la description du champ d'application et indique s'il est sensible ou limité.

Choisir des habilitations pour les modules complémentaires Google Workspace

Les sections suivantes fournissent des niveaux d'accès couramment utilisés pour les modules complémentaires Google Workspace.

Niveaux d'accès de l'éditeur

Les niveaux d'accès suivants, fréquemment utilisés pour les modules complémentaires Google Workspace, étendent Google Docs, Google Sheets et Google Slides.

Gmail

Des niveaux d'accès ont été créés spécifiquement pour les modules complémentaires Google Workspace afin de protéger les données Gmail des utilisateurs. Ajoutez explicitement ces champs d'application au fichier manifeste de votre module complémentaire, ainsi que tous les autres champs d'application requis.

Le tableau suivant répertorie les niveaux d'accès fréquemment utilisés pour les modules complémentaires Google Workspace qui étendent Gmail. Si votre module complémentaire étend Gmail, vous devez ajouter tous les champs d'application marqués Required (Obligatoire) au fichier manifeste de votre module complémentaire Google Workspace.

Remplacez le champ d'application étendu https://mail.google.com par un ensemble de champs d'application plus restreint qui autorisent les interactions dont votre module complémentaire a besoin.

Niveaux d'accès Google Agenda

Le tableau suivant répertorie les portées fréquemment utilisées pour les modules complémentaires Google Workspace qui étendent Google Agenda.

Champs d'application Google Chat

Pour appeler l'API Google Chat, authentifiez-vous en tant qu'utilisateur Google Chat ou en tant qu'application Google Chat. Chaque type d'authentification nécessite des habilitations différentes, et toutes les méthodes de l'API Chat ne sont pas compatibles avec l'authentification d'application.

Pour en savoir plus sur les types d'authentification et les habilitations Chat, consultez la présentation de l'authentification et de l'autorisation de l'API Chat.

Le tableau suivant présente les méthodes et les niveaux d'accès de l'API Chat fréquemment utilisés, en fonction des types d'authentification acceptés :

Champs d'application Google Drive

Le tableau suivant liste les portées fréquemment utilisées pour les modules complémentaires Google Workspace qui étendent Google Drive.

Jetons d'accès

Pour protéger les données utilisateur, les niveaux d'accès Gmail utilisés dans les modules complémentaires Google Workspace accordent un accès temporaire aux données utilisateur. Pour activer l'accès temporaire, appelez GmailApp.setCurrentMessageAccessToken à l'aide d'un jeton d'accès provenant d'un objet d'événement d'action.

Le jeton d'accès qui permet les champs d'application Gmail n'est pas le même que celui renvoyé par ScriptApp.getOAuthToken. Utilisez le jeton fourni dans l'objet d'événement d'action.

L'exemple suivant montre comment définir un jeton d'accès pour autoriser l'accès aux métadonnées d'un message. La seule portée nécessaire pour cet exemple est https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Autres niveaux d'accès Google Workspace

Votre module complémentaire peut nécessiter des autorisations supplémentaires s'il utilise d'autres services Google Workspace ou Apps Script. Dans la plupart des cas, Apps Script détecte ces autorisations et met à jour le fichier manifeste automatiquement. Lorsque vous modifiez la liste des portées de votre fichier manifeste, ne supprimez aucune portée, sauf si vous la remplacez par une alternative plus étroite.

Le tableau suivant présente les niveaux d'accès souvent utilisés par les modules complémentaires Google Workspace :