Champs d'application

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, la qui 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 faire. Par exemple, un module complémentaire peut demander l'autorisation de lire le message d'e-mail 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 des 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 par l'humain 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 parcours 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 champs d'application

Vous pouvez voir les niveaux d'accès actuellement requis par votre projet de script en effectuant la suivantes:

  1. Ouvrez le projet de script.
  2. Sur la gauche, cliquez sur Vue d'ensemble.
  3. Consultez les habilitations sous "Champs d'application 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 champs d'application explicites

Apps Script détermine automatiquement les portées dont un script a besoin en analysant son code à la recherche d'appels de fonction qui en ont besoin. Pour la plupart des scripts, il s'agit et cela vous fait gagner du temps, mais pour les modules complémentaires déjà publiés, vous devez un contrôle plus direct sur les champs d'application.

Par exemple, Apps Script peut attribuer par défaut la portée https://mail.google.com très permissive à un projet de script de module complémentaire. Lorsqu'un utilisateur autorise un projet de script avec cette portée, le projet bénéficie d'un accès complet au compte Gmail de l'utilisateur. Pour les modules complémentaires publiés, vous devez remplacer cette portée par un ensemble plus limité qui couvre les besoins des modules complémentaires et pas plus.

Vous pouvez définir explicitement les portées 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 champs d'application de votre projet, procédez comme suit :

  1. Affichez les champs d'application que votre module complémentaire utilise actuellement. Déterminez les modifications à apporter, par exemple en utilisant un champ d'application plus restreint.
  2. Ouvrez le fichier manifeste du 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 portées utilisées par votre projet, remplacez le contenu de ce tableau par les portées 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 champs d'application OAuth sensibles peut nécessiter une validation du client OAuth avant que vous puissiez publier votre module complémentaire. 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 vous aident à protéger les données utilisateur. Si vous avez l'intention de publier un module complémentaire Gmail ou des éditeurs qui utilise un ou plusieurs niveaux d'accès restreints, le module complémentaire doit respecter tous les des restrictions avant de pouvoir la publier.

Consultez la liste complète des champs d'application limités avant de tenter de publier. Si votre module complémentaire en utilise un, vous devez respecter les exigences supplémentaires pour les champs d'application d'API spécifiques avant de le publier.

Champs d'application de l'agenda

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

Portée
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 des événements Agenda. Autorise pour accéder aux métadonnées de l'événement.

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. Permet au module complémentaire d'accéder aux données d'événement générées par l'utilisateur. Ces données sont n'est disponible que si <ph type="x-smartling-placeholder"></ph> Champ 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 sont n'est disponible que si <ph type="x-smartling-placeholder"></ph> Champ manifeste addOns.calendar.eventAccess est défini sur WRITE ou READ_WRITE.

Champs d'application Drive

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

Portée
Lire les métadonnées des éléments 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'identifiant de l'élément, le titre, le type MIME, l'URL de l'icône et 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é d'Apps Script. Cela ne permet pas d'effectuer des actions similaires à l'aide de la propriété service Drive de base, . L'autorisation de fichiers est accordée par fichier et est est révoqué lorsque l'utilisateur annule l'autorisation de l'application.

Consultez le Exemple de demande d'accès aux fichiers sélectionnés.

Habilitations 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 explicitement ces champs d'application à votre fichier manifeste de module complémentaire, ainsi que tous les autres requis par le code de votre module complémentaire.

Vous trouverez ci-dessous les champs d'application couramment utilisés pour les modules complémentaires Google Workspace qui étendent Gmail. Ceux marqués comme 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 très large https://mail.google.com de votre module complémentaire par un ensemble plus restreint de champs d'application qui autorisent les interactions dont votre module complémentaire a besoin et pas plus.

Portée
Créer des brouillons https://www.googleapis.com/auth/gmail.addons.current.action.compose

Obligatoire si le module complémentaire utilise déclencheurs d'action de rédaction. Permet au module complémentaire de créer temporairement des brouillons de messages et réponses. Pour en savoir plus, consultez Composer des messages d'envoi différé. Cette portée est également souvent utilisée 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 l'action Compose déclencheurs. Pour les actions de composition, cette portée est requise si un déclencheur de composition a besoin d'accéder aux métadonnées. En pratique, cette portée 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 comme lorsqu'un élément de menu supplé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. Accorde également l'accès au contenu des autres messages ouverts thread. Nécessite un jeton d'accès.

lire tous les contenus et métadonnées des messages ; https://www.googleapis.com/auth/gmail.readonly

Lire 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 un fil de discussion complet.

Jetons d'accès

Pour protéger les données utilisateur, les portées 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 méthode fonction GmailApp.setCurrentMessageAccessToken(accessToken) en utilisant un jeton d'accès comme argument. Vous devez obtenir un jeton d'accès 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();
}

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 Docs Apps Script. 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 Sheets Apps Script. 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 utilise onFileScopeGrantedTrigger et si le module complémentaire 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é d'Apps Script. Toutefois, cela n'autorise pas l'utilisation d'actions similaires à l'aide du service Drive de base. L'autorisation de fichier est accordée au cas par cas et révoquée lorsque l'utilisateur désautorise 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 pas tous les champs d'application, sauf si vous les remplacez par une alternative plus appropriée, comme un champ d'application plus restreint.

Pour référence, voici une liste des champs d'application Apps Script couramment utilisés 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 de créer UrlFetch requêtes. 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. Voir <ph type="x-smartling-placeholder"></ph> Accès aux paramètres régionaux et au fuseau horaire de l'utilisateur pour en savoir plus.

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 d'un service tiers. Permet au projet de voir un lien dans une application Google Workspace lorsque l'utilisateur interagit avec celui-ci. Pour en savoir plus, consultez Prévisualiser des 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 au formulaire de création de ressources et d'insérer un lien vers la ressource dans une application Google Workspace. Pour en savoir plus, voir Créez des ressources tierces à partir du menu @.