Lunettes

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 lui 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 obtenir. Par exemple, un module complémentaire peut avoir besoin de 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 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 Google Workspace peut utiliser le champ d'application "Lire le message actuel", écrit dans votre fichier manifeste sous la forme https://www.googleapis.com/auth/gmail.addons.current.message.readonly. 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 vos e-mails lorsque le module complémentaire est en cours d'exécution.

Afficher les niveaux d'accès

Pour afficher 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 Présentation .
  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 pour rechercher les 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 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 se voit accorder 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 pas plus.

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. Consultez 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 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 champs d'application de votre projet, remplacez le contenu de ce tableau par les champs d'application de votre choix. Par exemple, pour un module complémentaire Google Workspace qui étend Gmail, vous pouvez disposer des é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 champs d'application 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 :

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 avez l'intention de publier un module complémentaire Gmail ou un module complémentaire d'éditeur 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 les champs d'application d'API spécifiques avant la publication.

Champs d'application des agendas

Vous trouverez ci-dessous les champs d'application fréquemment utilisés pour les modules complémentaires Google Workspace, qui étendent les fonctionnalités de Google Agenda.

Définition du champ d'application
Accéder aux métadonnées d'événements 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énement 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énement générées par l'utilisateur. Autorise le module complémentaire à accéder aux données d'événement générées par l'utilisateur. Ces données ne sont disponibles que si le champ du fichier manifeste addOns.calendar.eventAccess est défini sur READ ou READ_WRITE.

Écrire des données d'événement générées par l'utilisateur 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énement générées par l'utilisateur. Ces données ne sont disponibles que si le champ du fichier manifeste addOns.calendar.eventAccess est défini sur WRITE ou READ_WRITE.

Champs d'application Drive

Vous trouverez ci-dessous les champs d'application fréquemment utilisés pour les modules complémentaires Google Workspace qui étendent Google Drive.

Définition du 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 met en œuvre 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 sélectionnés par un utilisateur dans Google Drive. Les métadonnées sont limitées à l'ID de l'élément, au titre, au type MIME et à l'URL de l'icône. Elles déterminent également 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 ne permet pas d'effectuer des actions similaires avec le service Drive de base. L'autorisation d'accès aux fichiers est accordée pour chaque fichier et est révoquée lorsque l'utilisateur annule l'autorisation de l'application.

Consultez l' exemple de demande d'accès à un fichier pour les fichiers sélectionnés.

Champs d'application des modules complémentaires Gmail

Certains champs d'application 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 ces champs d'application explicitement au fichier manifeste du module complémentaire, avec tous les autres niveaux requis par le code du module complémentaire.

Vous trouverez ci-dessous les champs d'application fréquemment utilisés pour les modules complémentaires Google Workspace qui étendent Gmail. Ceux portant la mention Obligatoire 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 plus restreint de champs d'application qui permettent les interactions dont votre module complémentaire a besoin, et rien d'autre.

Définition du champ d'application
Créer des brouillons https://www.googleapis.com/auth/gmail.addons.current.action.compose

Obligatoire si le module complémentaire utilise des déclencheurs d'action Compose. Permet au module complémentaire de créer temporairement des brouillons de messages et de réponses. Pour en savoir plus, consultez Rédiger des brouillons de messages. Ce champ d'application est également souvent utilisé avec les actions de rédaction. Jeton d'accès requis.

Lire les métadonnées du message ouvert https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Accorde un accès temporaire aux métadonnées du message ouvert (telles que l'objet ou les destinataires). Ne permet pas de lire le contenu du message et nécessite un jeton d'accès.

Obligatoire si le module complémentaire utilise des métadonnées dans les déclencheurs d'action 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 Compose de déclencher l'accès aux listes de destinataires (à, Cc et Cci) d'un brouillon d'e-mail de réponse.

Lire le contenu du message ouvert https://www.googleapis.com/auth/gmail.addons.current.message.action

Accorde l'accès au contenu du message ouvert lors d'une interaction utilisateur, par exemple lorsqu'un élément de menu complémentaire est sélectionné. Nécessite un jeton d'accès.

Lire le contenu du 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. Permet également d'accéder au contenu des autres messages du thread ouvert. Jeton d'accès requis.

Lire le contenu et les métadonnées des messages https://www.googleapis.com/auth/gmail.readonly

Lisez les métadonnées et le contenu des e-mails, y compris le message ouvert. Obligatoire si vous devez lire des informations sur d'autres messages, par exemple lorsque vous effectuez une requête de recherche ou lisez l'intégralité d'un fil de discussion.

Jetons d'accès

Pour protéger les données utilisateur, les champs d'application Gmail utilisés dans les modules complémentaires Google Workspace n'accordent qu'un accès temporaire à ces données. Pour activer l'accès temporaire, vous devez appeler la fonction GmailApp.setCurrentMessageAccessToken(accessToken) à l'aide d'un jeton d'accès comme argument. Vous devez obtenir un jeton d'accès à partir d'un objet d'événement d'action.

Vous trouverez ci-dessous un exemple de définition d'un jeton d'accès pour autoriser l'accès aux métadonnées d'un message. Le seul champ d'application 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();
}

Champs d'application de l'éditeur

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

Définition du 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 actuel aux fichiers Sheets 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 actuel aux fichiers Slides 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 puisse utiliser onFileScopeGrantedTrigger et s'il accède à l'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 ne permet pas d'effectuer des actions similaires avec le service Drive de base. L'autorisation d'accès aux fichiers est accordée pour chaque fichier et est révoquée lorsque l'utilisateur annule l'autorisation de l'application.

Autres champs d'application

Votre module complémentaire peut nécessiter des champs d'application supplémentaires s'il utilise d'autres services Apps Script. Dans la plupart des cas, vous pouvez laisser Apps Script détecter ces champs d'application et mettre à jour le fichier manifeste automatiquement. Lorsque vous modifiez la liste des champs d'application de votre fichier manifeste, ne supprimez aucun champ d'application, sauf si vous les remplacez par une alternative plus appropriée, telle qu'un champ d'application plus restreint.

Pour référence, voici une liste des champs d'application Apps Script souvent utilisés conjointement avec les modules complémentaires Google Workspace:

Définition du champ d'application
Lire l'adresse e-mail de l'utilisateur https://www.googleapis.com/auth/userinfo.email

Permet au projet de lire l'adresse e-mail de l'utilisateur actuel.

Autoriser les appels vers des services externes https://www.googleapis.com/auth/script.external_request

Permet au projet d'envoyer des requêtes UrlFetch. Cette étape est également obligatoire si le projet utilise la bibliothèque OAuth2 pour Apps Script.

Consulter les paramètres régionaux et le fuseau horaire de l'utilisateur https://www.googleapis.com/auth/script.locale

Permet au projet d'apprendre 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 aux fuseaux horaires des utilisateurs.

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 les liens d'un service tiers. Permet au projet d'afficher un lien dans une application Google Workspace lorsque l'utilisateur interagit avec elle. Pour en savoir plus, consultez Prévisualiser les liens avec des 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 @.