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 agissent en leur nom. Lorsqu'un utilisateur exécute un module complémentaire pour la première fois, l'interface utilisateur des modules complémentaires affiche 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. Par exemple, un module complémentaire peut demander à lire l'e-mail d'un utilisateur ou à 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", qui est écrit dans votre fichier manifeste en tant que https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Pendant le flux d'autorisation, un module complémentaire avec ce champ d'application 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

Vous pouvez afficher les champs d'application actuellement requis par votre projet de script en procédant comme suit:

  1. Ouvrez le projet de script.
  2. À gauche, cliquez sur Vue d'ensemble .
  3. Affichez 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 seulement 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 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 d'un projet de script complémentaire https://mail.google.com. Lorsqu'un utilisateur autorise un projet de script avec ce champ d'application, l'accès complet au compte Gmail de l'utilisateur lui est accordé. Pour les modules complémentaires publiés, vous devez remplacer ce champ d'application par un ensemble plus limité qui ne couvre plus les besoins des modules complémentaires.

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. Recherchez le champ de niveau supérieur 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 utilisés par votre projet, remplacez le contenu de ce tableau par les champs d'application que vous souhaitez utiliser. Voici quelques exemples d'un module complémentaire Google Workspace qui étend Gmail:

    {
  ...
  "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 une validation du client OAuth par votre module complémentaire avant sa publication. Pour en savoir plus, consultez les guides suivants :

Champs d'application restreints

Certains champs d'application sont limités et soumis à des règles supplémentaires qui contribuent à la protection des 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 exigences supplémentaires pour des champs d'application d'API spécifiques avant la publication.

Champs d'application de l'agenda

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

Champ d'application
Accéder aux métadonnées d'événement https://www.googleapis.com/auth/calendar.addons.execute

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

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énement générées par l'utilisateur. Permet au module complémentaire d'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 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é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 manifeste addOns.calendar.eventAccess est défini sur WRITE ou READ_WRITE.

Champs d'application Drive

Vous trouverez ci-dessous des champs d'application fréquemment utilisés 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é 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 et au titre de l'élément, au type MIME, à l'URL de l'icône et au fait que le module complémentaire soit autorisé ou non à 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. Toutefois, cela n'autorise pas l'utilisation d'actions similaires avec le service Drive de base. L'autorisation 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 à votre fichier manifeste de module complémentaire, ainsi qu'à tous les autres éléments 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 qui sont indiqués comme obligatoires doivent être ajoutés à votre fichier manifeste de 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 plus restreint de champs d'application, permettant ainsi les interactions dont votre module complémentaire a besoin et plus encore.

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 de rédaction. 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 (comme son objet ou ses destinataires). N'autorise 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 des déclencheurs d'action de rédaction. 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 "Rédiger" d'accéder aux listes de destinataires (à:, cc: et bcc:) 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 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 des messages ouverts. Permet également d'accéder 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 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 requis 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 éditeur

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

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 à chaque fichier https://www.googleapis.com/auth/drive.file

Requis pour que le module complémentaire utilise onFileScopeGrantedTrigger et qu'il accède à l'API 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. Toutefois, cela n'autorise pas l'utilisation d'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 autoriser Apps Script à détecter ces champs d'application et à mettre à jour le fichier manifeste automatiquement. Lorsque vous modifiez la liste des 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:

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'effectuer des requêtes UrlFetch. Cela est également nécessaire 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.