Cette page a été traduite par l'API Cloud Translation.

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 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 habilitations OAuth.

Vous déclarez les champs d'application 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 champ d'application. 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.

Afficher les portées

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

Ouvrez le projet de script.
Sur la gauche, cliquez sur Vue d'ensemble .
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 à la recherche d'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 autorisations de votre projet, procédez comme suit :

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 étroit.
Ouvrez le fichier manifeste de votre module complémentaire.
Recherchez le champ de premier niveau intitulé oauthScopes. Si elle n'est pas présente, vous pouvez l'ajouter.
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"
  ],
  ...
}
```
Enregistrez les modifications apportées au fichier manifeste.

Validation OAuth

L'utilisation de certains périmètres OAuth sensibles peut nécessiter que votre module complémentaire soit soumis à la validation du client OAuth avant de pouvoir être publié. Pour en savoir plus, consultez les guides suivants :

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 niveaux d'accès spécifiques aux API 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 leur description et leur sensibilité ou leur restriction.

Choisir des niveaux d'accès pour les modules complémentaires Google Workspace

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

Champs d'application de l'éditeur

Vous trouverez ci-dessous les niveaux d'accès fréquemment utilisés pour les modules complémentaires Google Workspace qui étendent Docs, Sheets et Slides.

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.

Champ d'application
Accès actuel aux fichiers Docs	`https://www.googleapis.com/auth/documents.currentonly` Obligatoire si le module complémentaire accède à l'API Apps Script Docs. Accorde un accès temporaire au contenu du document ouvert.
Accès aux fichiers Sheets actuels	`https://www.googleapis.com/auth/spreadsheets.currentonly` Obligatoire si le module complémentaire accède à l'API Apps Script Sheets. Accorde un accès temporaire au contenu de la feuille de calcul ouverte.
Accès au fichier Slides actuel	`https://www.googleapis.com/auth/presentations.currentonly` Obligatoire si le module complémentaire accède à l'API Apps Script Slides. Accorde un accès temporaire au contenu de la présentation ouverte.
Accès par fichier	`https://www.googleapis.com/auth/drive.file` Obligatoire pour que le module complémentaire utilise `onFileScopeGrantedTrigger` et si le module complémentaire accède aux API Docs, Sheets, Slides ou Drive. Accorde un accès par fichier aux fichiers créés ou ouverts par l'application, à l'aide du service Drive avancé Apps Script. Toutefois, cela n'autorise pas l'utilisation d'actions similaires avec le service Drive de base. L'autorisation d'accès aux fichiers est accordée fichier par fichier et est révoquée lorsque l'utilisateur supprime l'autorisation accordée à l'application.

Gmail

Certains 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. Vous devez ajouter explicitement ces champs d'application au fichier manifeste de votre module complémentaire, ainsi que tous les autres dont le code de votre module complémentaire a besoin.

Vous trouverez ci-dessous les niveaux d'accès fréquemment utilisés pour les modules complémentaires Google Workspace qui étendent Gmail. Ceux marqués comme obligatoires doivent être ajoutés au fichier manifeste de votre module complémentaire Google Workspace si celui-ci étend Gmail.

Veillez également à remplacer le champ d'application https://mail.google.com très large de votre module complémentaire par un ensemble de champs d'application plus restreint qui autorisent les interactions dont votre module complémentaire a besoin, et rien de plus.

Champ d'application
Créer des suggestions	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Obligatoire si le module complémentaire utilise des déclencheurs d'action de rédaction. Permet au module complémentaire de créer temporairement des brouillons de messages et des réponses. Pour en savoir plus, consultez Composer des brouillons de messages. Ce champ d'application est également souvent utilisé avec les actions de composition. Nécessite un jeton d'accès.
Lire les métadonnées des messages ouverts	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Accorde un accès temporaire aux métadonnées du message ouvert (comme l'objet ou les destinataires). Ne permet pas de lire le contenu des messages et nécessite un jeton d'accès. Obligatoire si le module complémentaire utilise des métadonnées dans les déclencheurs d'actions de composition. Pour les actions de composition, ce champ d'application est requis si un déclencheur de composition a besoin d'accéder aux métadonnées. En pratique, ce champ d'application permet à un déclencheur de composition d'accéder aux listes de destinataires (à, cc et cci) d'un brouillon d'e-mail de réponse.
Lire le contenu des messages ouverts	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Accorde l'accès au contenu du message ouvert lors d'une interaction de l'utilisateur, par exemple lorsqu'un élément de menu de module complémentaire est sélectionné. Nécessite un jeton d'accès.
Lire le contenu d'un fil de discussion ouvert	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` Accorde un accès temporaire aux métadonnées et au contenu du message ouvert. Accorde également l'accès au contenu des autres messages du fil de discussion ouvert. Nécessite un jeton d'accès.
lire le contenu et les métadonnées de n'importe quel message ;	`https://www.googleapis.com/auth/gmail.readonly` lire les métadonnées et le contenu des e-mails, y compris les messages ouverts ; Obligatoire si vous devez lire des informations sur d'autres messages, par exemple lorsque vous effectuez une requête de recherche ou lisez un fil de discussion complet. Avertissement : Il s'agit d'un champ d'application restreint très large. N'utilisez cette option qu'en cas d'absolue nécessité.

Niveaux d'accès Google Agenda

Vous trouverez ci-dessous les niveaux d'accès fréquemment utilisés pour les modules complémentaires Google Workspace qui étendent Google Agenda.

Champ d'application
Accéder aux métadonnées d'un événement	`https://www.googleapis.com/auth/calendar.addons.execute` Obligatoire si le module complémentaire accède aux métadonnées des événements d'agenda. Permet au module complémentaire d'accéder aux métadonnées des événements.
Lire les données d'événements générées par les utilisateurs	`https://www.googleapis.com/auth/calendar.addons.current.event.read` Obligatoire si le module complémentaire doit lire les données d'événements générées par l'utilisateur. Permet au module complémentaire d'accéder aux données d'événements générées par les utilisateurs. Ces données ne sont disponibles que si le champ de fichier manifeste `addOns.calendar.eventAccess` est défini sur `READ` ou `READ_WRITE`.
Écrire des données d'événements générés par les utilisateurs	`https://www.googleapis.com/auth/calendar.addons.current.event.write` Obligatoire si le module complémentaire doit écrire des données d'événement générées par l'utilisateur. Permet au module complémentaire de modifier les données d'événements générées par les utilisateurs. Ces données ne sont disponibles que si le champ de fichier manifeste `addOns.calendar.eventAccess` est défini sur `WRITE` ou `READ_WRITE`.

Champs d'application Google Chat

Pour appeler l'API Chat, vous devez vous authentifier en tant qu'utilisateur Google Chat ou en tant qu'application 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 des applications.

Pour en savoir plus sur les habilitations Chat et les types d'authentification, 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 compatibles :

Méthode	L'authentification par l'application est prise en charge.	Champs d'application des autorisations acceptés
Envoyer un message		Avec l'authentification des utilisateurs : `chat.messages.create` `chat.messages` `chat.import` Avec l'authentification de l'application : `chat.bot`
Créer un espace		Avec l'authentification des utilisateurs : `chat.spaces.create` `chat.spaces` `chat.import` Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) : `chat.app.spaces.create` `chat.app.spaces`
Créer un espace et y ajouter des membres	—	Avec l'authentification des utilisateurs : `chat.spaces.create` `chat.spaces`
Ajouter un utilisateur à un espace		Avec l'authentification des utilisateurs : `chat.memberships` `chat.memberships.app` `chat.import` Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) : `chat.app.memberships`
Lister les activités ou les événements d'un espace Chat	—	Avec l'authentification des utilisateurs, vous devez utiliser un champ d'application pour chaque type d'événement inclus dans la requête : Pour les événements concernant les messages : `chat.messages` `chat.messages.readonly` Pour les événements concernant les réactions : `chat.messages.reactions` `chat.messages.reactions.readonly` `chat.messages` `chat.messages.readonly` Pour les événements concernant les abonnements : `chat.memberships` `chat.memberships.readonly` Pour les événements concernant l'espace : `chat.spaces` `chat.spaces.readonly`

Champs d'application Google Drive

Vous trouverez ci-dessous les portées fréquemment utilisées pour les modules complémentaires Google Workspace qui étendent Google Drive.

Champ d'application

Lire les métadonnées de l'élément sélectionné

Champ d'application
Lire les métadonnées de l'élément sélectionné	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` Obligatoire si le module complémentaire implémente une interface contextuelle déclenchée lorsque l'utilisateur sélectionne des éléments dans Drive. Permet au module complémentaire de lire des métadonnées limitées sur les éléments qu'un utilisateur a sélectionnés dans Google Drive. Les métadonnées sont limitées à l'ID, au titre, au type MIME et à l'URL de l'icône de l'élément, ainsi qu'à l'indication de savoir si le module complémentaire est autorisé à accéder à l'élément.
Accès par fichier	`https://www.googleapis.com/auth/drive.file` Recommandé si le module complémentaire doit accéder à des fichiers Drive individuels. Accorde un accès par fichier aux fichiers créés ou ouverts par l'application, à l'aide du service Drive avancé Apps Script. Toutefois, cela n'autorise pas l'utilisation d'actions similaires avec le service Drive de base. L'autorisation d'accès aux fichiers est accordée fichier par fichier et est révoquée lorsque l'utilisateur désautorise l'application. Consultez l'exemple Demander l'accès aux fichiers sélectionnés.

https://www.googleapis.com/auth/drive.addons.metadata.readonly

Obligatoire si le module complémentaire implémente une interface contextuelle déclenchée lorsque l'utilisateur sélectionne des éléments dans Drive. Permet au module complémentaire de lire des métadonnées limitées sur les éléments qu'un utilisateur a sélectionnés dans Google Drive. Les métadonnées sont limitées à l'ID, au titre, au type MIME et à l'URL de l'icône de l'élément, ainsi qu'à l'indication de savoir si le module complémentaire est autorisé à accéder à l'élément.

Accès par fichier

https://www.googleapis.com/auth/drive.file

Recommandé si le module complémentaire doit accéder à des fichiers Drive individuels. Accorde un accès par fichier aux fichiers créés ou ouverts par l'application, à l'aide du service Drive avancé Apps Script. Toutefois, cela n'autorise pas l'utilisation d'actions similaires avec le service Drive de base. L'autorisation d'accès aux fichiers est accordée fichier par fichier et est révoquée lorsque l'utilisateur désautorise l'application.

Consultez l'exemple Demander l'accès aux fichiers sélectionnés.

Jetons d'accès

Pour protéger les données utilisateur, les autorisations Gmail utilisées dans les modules complémentaires Google Workspace n'accordent qu'un accès temporaire aux données utilisateur. Pour activer l'accès temporaire, vous devez appeler la fonction GmailApp.setCurrentMessageAccessToken(accessToken) en utilisant un jeton d'accès comme argument. Vous devez obtenir un jeton d'accès à partir d'un 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 champs d'application supplémentaires s'il utilise d'autres services Google Workspace ou Apps Script. Dans la plupart des cas, vous pouvez laisser Apps Script détecter ces niveaux d'accès et mettre à 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 appropriée, telle qu'une portée plus étroite.

Le tableau suivant présente une liste des autorisations souvent utilisées par les modules complémentaires Google Workspace :

Champ d'application
Lire l'adresse e-mail de l'utilisateur	`https://www.googleapis.com/auth/userinfo.email` Autorise le projet à lire l'adresse e-mail de l'utilisateur actuel.
Autoriser les appels à des services externes	`https://www.googleapis.com/auth/script.external_request` Permet au projet d'effectuer des requêtes `UrlFetch`. Cette étape est également obligatoire si le projet utilise la bibliothèque OAuth2 pour Apps Script.
Lire les paramètres régionaux et le fuseau horaire de l'utilisateur	`https://www.googleapis.com/auth/script.locale` Permet au projet de connaître les paramètres régionaux et le fuseau horaire de l'utilisateur actuel. Pour en savoir plus, consultez Accéder aux paramètres régionaux et au fuseau horaire de l'utilisateur.
Créer des déclencheurs	`https://www.googleapis.com/auth/script.scriptapp` Permet au projet de créer des déclencheurs.
Prévisualiser les liens tiers	`https://www.googleapis.com/auth/workspace.linkpreview` Obligatoire si le module complémentaire affiche un aperçu des liens provenant d'un service tiers. Permet au projet de voir un lien dans une application Google Workspace pendant que l'utilisateur interagit avec celui-ci. Pour en savoir plus, consultez Aperçu des liens avec les chips intelligents.
Créer des ressources tierces	`https://www.googleapis.com/auth/workspace.linkcreate` Obligatoire si le module complémentaire crée des ressources dans un service tiers. Permet au projet de lire les informations que les utilisateurs envoient dans le formulaire de création de ressources et d'insérer un lien vers la ressource dans une application Google Workspace. Pour en savoir plus, consultez Créer des ressources tierces à partir du menu @.