Lunettes

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les utilisateurs doivent autoriser les modules complémentaires et les autres applications qui accèdent à leurs données ou qui agissent en leur nom. Lorsqu'un utilisateur exécute un module complémentaire pour la première fois, l'interface utilisateur affiche une invite d'autorisation pour lancer le flux d'autorisation.

Au cours de ce processus, l'invite indique à l'utilisateur ce que l'application souhaite obtenir. 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 Google Workspace peut utiliser le champ d'application "Lire le message actuel", qui est écrit dans votre fichier manifeste en tant que https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Au cours du flux d'autorisation, un module complémentaire ayant le champ d'application demandé demande à l'utilisateur d'autoriser: Afficher vos e-mails lorsque le module complémentaire est en cours d'exécution.

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. À gauche, cliquez sur Vue d'ensemble .
  3. Afficher les champs d'application sous "Project OAuth Scopes."

Vous pouvez également afficher les niveaux d'accès actuels du projet de script dans le fichier manifeste du projet, sous le champ oauthScopes, mais seulement si vous avez défini ces champs d'application 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 les appels de fonction qui les requièrent. Pour la plupart des scripts, cela est suffisant et vous fait gagner du temps. Toutefois, 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 donner à un projet de script complémentaire le champ d'application très permissif https://mail.google.com par défaut. Lorsqu'un utilisateur autorise un projet de script ayant 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 du module complémentaire et ne doit plus suffire.

Vous pouvez définir explicitement les champs d'application utilisés par votre projet de script en modifiant son fichier manifest. Le champ 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 de votre module complémentaire.
  3. Repérez le champ de premier niveau intitulé oauthScopes. Si ce n'est pas le cas, vous pouvez l'ajouter.
  4. Le champ oauthScopes spécifie un tableau de chaînes. Pour définir les champs d'application utilisés par votre projet, remplacez le contenu de ce tableau par les champs d'application que vous souhaitez utiliser. 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 effectue une validation du client OAuth avant de pouvoir être publié. 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 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, 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 d'essayer de publier. Si votre module complémentaire en utilise un, vous devez respecter les Conditions supplémentaires pour des champs d'application d'API spécifiques avant la publication.

Champs d'application Agenda

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.

Portée
Métadonnées d'événement d'accès https://www.googleapis.com/auth/calendar.addons.execute

Obligatoire si le module complémentaire accède aux métadonnées d'événement Agenda. Autorise le module complémentaire à accéder aux métadonnées d'événements.

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

Écrire les 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énements 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 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.

Portée
Lire les métadonnées d'élément sélectionnées 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 les métadonnées limitées concernant les éléments sélectionnés par un utilisateur dans Google Drive. Les métadonnées sont limitées à l'ID, au titre, au type MIME et à l'URL de l'élément de l'élément, et peuvent indiquer si le module complémentaire est autorisé à accéder à l'élément.

Accès à chaque fichier https://www.googleapis.com/auth/drive.file

Recommandé si le module complémentaire doit accéder à des fichiers Drive individuels. Accorde l'accès par fichier aux fichiers créés ou ouverts par l'application, à l'aide du service Drive avancé d'Apps Script. Cette opération ne permet toutefois pas d'utiliser des actions similaires avec le service Drive de base. L'autorisation de fichier 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 aux fichiers sélectionnés.

Champs d'application des modules complémentaires Gmail

Plusieurs 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 de votre module complémentaire, en plus de tous ceux requis par votre code de 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 votre module complémentaire étend Gmail.

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

Portée
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 de composition. 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. Ce champ d'application est également souvent utilisé avec les actions de rédaction. 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 (l'objet ou les destinataires, par exemple). Ne permet pas la lecture du 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'action de composition. Pour les actions Compose, ce champ d'application est requis si un déclencheur Compose a besoin d'accéder aux métadonnées. En pratique, ce champ d'application permet à un déclencheur de rédaction d'accéder aux listes de destinataires (à:, cc: et bcc:) 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

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

Lire le contenu des fils de discussion ouverts https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Accorde un accès temporaire aux métadonnées et au contenu des messages ouverts. Permet également d'accéder au contenu d'autres messages du fil de discussion ouvert. Nécessite un jeton d'accès.

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 pour effectuer une requête de recherche ou lire un fil de discussion complet.

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

Portée
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.

Accès à chaque fichier https://www.googleapis.com/auth/drive.file

Obligatoire pour que le module complémentaire utilise onFileScopeGrantedTrigger et s'il accède aux API REST Docs, Sheets, Slides ou Drive. Accorde l'accès par fichier aux fichiers créés ou ouverts par l'application, à l'aide du service Drive avancé d'Apps Script. Cette opération ne permet toutefois pas d'utiliser des actions similaires avec le service Drive de base. L'autorisation de fichier 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 de champs d'application du 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.

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

Portée
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'effectuer des requêtes UrlFetch. Cela est également nécessaire si le projet utilise la bibliothèque OAuth2 for 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 d'apprendre les paramètres régionaux et le fuseau horaire actuels de l'utilisateur. 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.