Champs d'application des autorisations

Les utilisateurs doivent autoriser les projets de script qui accèdent à leurs données ou agissent en leur nom. Lorsqu'un utilisateur exécute un script nécessitant une autorisation pour la première fois, l'interface utilisateur affiche une invite pour démarrer le flux d'autorisation.

Au cours de ce processus, l'UI indique à l'utilisateur ce que le script souhaite faire. Par exemple, un script peut demander l'autorisation de lire les e-mails de l'utilisateur ou de créer des événements dans son agenda. Le projet de script définit ces autorisations individuelles en tant que habilitations OAuth.

Pour la plupart des scripts, Apps Script détecte automatiquement les autorisations dont vous avez besoin. Vous pouvez afficher les autorisations utilisées par un script à tout moment. Vous pouvez également définir explicitement des portées dans votre manifeste à l'aide de chaînes d'URL. Il est parfois nécessaire de définir explicitement les niveaux d'accès pour certaines applications, comme les modules complémentaires, car les applications publiées doivent toujours utiliser les niveaux d'accès les plus restreints possible.

Pendant le flux d'autorisation, Apps Script présente à l'utilisateur des descriptions lisibles des champs d'application requis. Par exemple, si votre script a besoin d'un accès en lecture seule à vos feuilles de calcul, le fichier manifeste peut avoir le champ d'application https://www.googleapis.com/auth/spreadsheets.readonly. Lors du flux d'autorisation, un script avec cette portée demande à l'utilisateur d'autoriser cette application à "Afficher vos feuilles de calcul Google".

Certains scopes incluent d'autres scopes. Par exemple, lorsqu'il est autorisé, le champ d'application https://www.googleapis.com/auth/spreadsheets permet d'accéder en lecture et en écriture aux feuilles de calcul.

Pour certaines surfaces sur lesquelles les scripts s'exécutent, comme l'exécution d'un script directement depuis l'IDE Apps Script, les utilisateurs voient s'afficher l'écran de consentement OAuth détaillé. Cela permet aux utilisateurs de sélectionner des autorisations spécifiques à accorder au lieu de toutes les accorder en même temps. Il est important de concevoir votre script pour gérer les autorisations OAuth précises.

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. Sur la gauche, cliquez sur Vue d'ensemble .
3. Affichez les habilitations sous Project OAuth Scopes (Habilitations OAuth du projet).

Définir des niveaux d'accès explicites

Apps Script détermine automatiquement les niveaux d'accès 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, les applications Web, les applications Google Chat et les appels à l'API Google Chat publiés, vous devez exercer un contrôle plus direct des habilitations.

Apps Script attribue parfois automatiquement des champs d'application très permissifs aux projets. Cela peut signifier que votre script demande à l'utilisateur plus d'informations que nécessaire, ce qui est une mauvaise pratique. Pour les scripts publiés, vous devez remplacer les portées larges par un ensemble plus limité qui couvre les besoins du script et rien de plus.

Avertissement : Utilisez toujours l'ensemble de niveaux d'accès le moins permissif possible. Pour protéger les informations des utilisateurs, les modules complémentaires et autres applications publiées ne doivent jamais demander plus d'autorisations de portée que nécessaire.

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 projet. Pour définir les niveaux d'accès de votre projet, procédez comme suit :

1. Ouvrez le projet de script.
2. Sur la gauche, cliquez sur Paramètres du projet .
3. Cochez la case Afficher le fichier manifeste "appsscript.json" dans l'éditeur.
4. À gauche, cliquez sur Montage .
5. À gauche, cliquez sur le fichier appsscript.json.
6. Recherchez le champ de premier niveau intitulé oauthScopes. Si elle n'est pas présente, vous pouvez l'ajouter.
7. 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. Exemple :

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. En haut, cliquez sur (Enregistrer).

Gérer les autorisations OAuth précises

Remarque : L'écran de consentement OAuth granulaire a d'abord été déployé dans l'IDE Apps Script pour les utilisateurs exécutant un script directement depuis Apps Script. L'écran de consentement sera progressivement déployé sur les autres surfaces, telles que les macros, les exécutions de déclencheurs et les modules complémentaires. Pour en savoir plus, consultez Le consentement OAuth pour les exécutions dans l'IDE Google Apps Script devient granulaire.

L'écran de consentement OAuth détaillé permet aux utilisateurs d'indiquer les habilitations OAuth individuelles qu'ils souhaitent autoriser. Les autorisations OAuth détaillées permettent aux utilisateurs de contrôler plus précisément les données de compte qu'ils choisissent de partager avec chaque script. Par exemple, imaginez que vous développiez un script qui demande l'autorisation pour les deux niveaux d'accès (e-mail et agenda). Vos utilisateurs peuvent souhaiter utiliser votre script uniquement pour ses fonctionnalités avec Google Agenda, mais pas avec Gmail. Grâce aux autorisations OAuth précises, les utilisateurs peuvent choisir de n'accorder que l'autorisation Agenda, mais pas Gmail.

Les sections suivantes décrivent les principales méthodes de gestion des autorisations OAuth précises.

Exiger automatiquement l'autorisation pour les champs d'application nécessaires

Si un flux d'exécution a besoin d'autorisations pour des périmètres afin de fonctionner, vous pouvez demander aux utilisateurs d'accorder ces autorisations avant de pouvoir l'utiliser. Votre script peut vérifier si l'utilisateur a déjà accordé l'autorisation et, si ce n'est pas le cas, la lui demander automatiquement.

Les méthodes suivantes de la classe ScriptApp vous permettent de valider l'autorisation pour les niveaux d'accès requis et d'afficher automatiquement l'invite d'autorisation pour demander les autorisations manquantes :

• requireScopes(authMode, oAuthScopes) : utilisez cette méthode pour les flux d'exécution qui s'appuient sur une ou plusieurs habilitations, mais pas sur toutes celles utilisées par votre script.
• requireAllScopes(authMode) : utilisez cette méthode si un flux d'exécution repose sur tous les niveaux d'accès utilisés par votre script.

Exemple

L'exemple suivant montre comment appeler les méthodes requireScopes(authMode, oAuthScopes) et requireAllScopes(authMode). Le script utilise des portées pour Gmail, Sheets et Agenda. La fonction sendEmail() ne nécessite que les niveaux d'accès pour Gmail et Sheets, tandis que la fonction createEventSendEmail() nécessite tous les niveaux d'accès utilisés par le script.

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

Créer une expérience personnalisée pour les champs d'application manquants

Vous pouvez obtenir les détails des autorisations de l'utilisateur qui exécute votre script et concevoir une expérience personnalisée en fonction de l'état de ses autorisations. Par exemple, vous pouvez décider de désactiver des fonctionnalités spécifiques de votre script qui nécessitent des autorisations que l'utilisateur n'a pas accordées, ou d'afficher une boîte de dialogue personnalisée expliquant les autorisations manquantes. Les méthodes suivantes permettent d'obtenir un objet contenant les informations d'autorisation de l'utilisateur, y compris les autorisations accordées par l'utilisateur et une URL permettant de demander les autorisations manquantes :

• getAuthorizationInfo(authMode, oAuthScopes) : utilisez cette méthode pour vérifier l'état des autorisations pour des niveaux d'accès spécifiques.
• getAuthorizationInfo(authMode) : utilisez cette méthode pour vérifier l'état des autorisations pour tous les niveaux d'accès utilisés par votre script.

Pour obtenir les détails des autorisations à partir de l'objet d'informations d'autorisation, comme la liste des autorisations accordées et une URL permettant de demander les autorisations manquantes, utilisez les méthodes de la classe AuthorizationInfo.

Exemple

L'exemple suivant montre comment appeler la méthode getAuthorizationInfo(authMode, oAuthScopes) pour ignorer des fonctionnalités spécifiques dans un flux d'exécution où les autorisations requises n'ont pas été accordées. Cela permet au reste du flux d'exécution de se poursuivre sans avoir à demander l'autorisation des champs d'application manquants.

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("[e-mail]", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

S'assurer que les exécutions de déclencheurs disposent des autorisations nécessaires

Les fonctions associées aux déclencheurs peuvent s'exécuter automatiquement lors de certains événements, et il est possible que l'utilisateur ne soit pas présent pour fournir d'autres autorisations. Nous vous recommandons d'utiliser requireScopes(authMode, oAuthScopes) avant d'installer un déclencheur. L'utilisateur est alors invité à accorder les autorisations manquantes et ne peut pas installer le déclencheur sans les accorder.

Exemple

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}


function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

Validation OAuth

Certains champs d'application OAuth sont sensibles, car ils permettent d'accéder aux données utilisateur Google. Si votre projet de script utilise des champs d'application qui permettent d'accéder aux données utilisateur, il doit passer par la validation du client OAuth avant de pouvoir être publié publiquement en tant qu'application Web ou module complémentaire. Pour en savoir plus, consultez les guides suivants :

• Validation du client OAuth pour Apps Script
• Applications non validées
• Questions fréquentes sur la validation OAuth
• Règlement relatif aux données utilisateur dans les services d'API Google

Niveaux d'accès restreints

En plus des niveaux d'accès sensibles, certains niveaux d'accès sont classés comme restreints et soumis à des règles supplémentaires qui permettent de protéger les données utilisateur. Si vous prévoyez de publier une application Web ou un module complémentaire qui utilise un ou plusieurs champs d'application restreints, l'application doit respecter toutes les restrictions spécifiées avant de pouvoir être publiée.

Consultez la liste complète des champs d'application restreints avant de tenter de publier. Si votre application en utilise, vous devez respecter les Exigences supplémentaires pour les champs d'application d'API spécifiques avant de la publier.

Remarque : Évitez d'utiliser des niveaux d'accès restreints dans votre application si vous le pouvez. Il est plus facile de passer l'examen pour une publication publique si vous ne les utilisez pas. Vous pouvez utiliser librement les portées restreintes pour les applications et les scripts non publics.