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 aux utilisateurs les autorisations demandées par le script. Par exemple, un script peut demander l'autorisation de lire des e-mails ou de créer des événements d'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 portées requises. Vous pouvez afficher les niveaux d'accès utilisés par un script à tout moment. Vous pouvez également définir des niveaux d'accès de manière explicite dans votre fichier manifeste à l'aide de chaînes d'URL. Les applications publiées, telles que les modules complémentaires, doivent utiliser les niveaux d'accès les plus restreints possible.

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

Certains incluent d'autres. Par exemple, l'accès autorisé à https://www.googleapis.com/auth/spreadsheets permet d'accéder aux feuilles de calcul en lecture et en écriture.

Pour certaines surfaces, comme l'IDE Apps Script, les utilisateurs voient l'écran de consentement OAuth détaillé. Cet écran permet aux utilisateurs de sélectionner des autorisations spécifiques à accorder au lieu de toutes les accorder en même temps. Concevez votre script pour gérer les autorisations OAuth précises.

Afficher les champs d'application

Pour afficher les champs d'application requis par votre projet de script :

1. Ouvrez le projet de script.
2. Sur la gauche, cliquez sur Vue d'ensemble info_outline.
3. Affichez les habilitations sous Habilitations OAuth du projet.

Définir des niveaux d'accès explicites

Apps Script détermine automatiquement les niveaux d'accès requis en analysant le code pour les appels de fonction. Bien que cela soit suffisant pour la plupart des scripts, vous devez exercer un contrôle plus direct pour les modules complémentaires publiés, les applications Web, les applications Chat et les appels à l'API Chat.

Apps Script attribue parfois automatiquement des niveaux d'accès permissifs. Cela peut signifier que votre script demande aux utilisateurs plus d'accès que nécessaire. Pour les scripts publiés, remplacez les niveaux d'accès généraux par un ensemble limité qui couvre les besoins du script.

Vous pouvez définir explicitement les champs d'application utilisés par votre projet de script en modifiant son fichier manifeste. Le champ oauthScopes du fichier manifeste est un tableau de champs d'application utilisés par le projet. Pour définir les niveaux d'accès de votre projet :

1. Ouvrez le projet de script.
2. Sur la gauche, cliquez sur Paramètres du projet settings.
3. Cochez la case Afficher le fichier manifeste "appsscript.json" dans l'éditeur.
4. À gauche, cliquez sur Montage code.
5. Sur la 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. Remplacez le contenu du tableau oauthScopes par les champs d'application que vous souhaitez que le projet utilise. Exemple :

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

8. En haut de l'écran, cliquez sur Enregistrer save.

Gérer les autorisations OAuth précises

L'écran de consentement OAuth détaillé a d'abord été déployé dans l'IDE Apps Script pour les utilisateurs exécutant un script directement. L'écran de consentement est déployé progressivement sur d'autres surfaces, telles que les macros, les 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 utilisateurs peuvent ainsi contrôler précisément les données de compte qu'ils partagent avec chaque script. Par exemple, si un script demande des autorisations pour les services de messagerie et d'agenda, les utilisateurs peuvent choisir d'accorder l'autorisation pour Agenda, mais pas pour Gmail.

Les sections suivantes décrivent comment gérer les autorisations OAuth précises.

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

Si un flux d'exécution nécessite des habilitations spécifiques, vous pouvez demander aux utilisateurs de les accorder. Votre script peut vérifier les autorisations et les demander automatiquement si elles manquent.

Les méthodes suivantes de la classe ScriptApp valident les autorisations et affichent l'invite d'autorisation :

• requireScopes(authMode, oAuthScopes) : utilisez cette méthode pour les flux qui reposent sur des niveaux d'accès spécifiques.
• requireAllScopes(authMode) : utilisez cette méthode si un flux d'exécution repose sur tous les niveaux d'accès du projet.

Exemple

L'exemple suivant montre comment appeler requireScopes() et requireAllScopes(). Le script utilise des niveaux d'accès 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("dana@example.com", "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("dana@example.com", "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 récupérer l'état des autorisations des utilisateurs et concevoir des expériences personnalisées. Par exemple, vous pouvez désactiver les fonctionnalités qui nécessitent des autorisations manquantes ou afficher une boîte de dialogue expliquant l'exigence. Les méthodes suivantes récupèrent un objet contenant les informations d'autorisation de l'utilisateur, y compris les champs d'application que l'utilisateur a autorisés et une URL permettant de demander les champs d'application manquants :

• getAuthorizationInfo(authMode, oAuthScopes) : vérifie l'état des autorisations pour des champs d'application spécifiques.
• getAuthorizationInfo(authMode) : vérifie l'état des autorisations pour tous les niveaux d'accès au projet.

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

Exemple

L'exemple suivant montre comment utiliser getAuthorizationInfo() pour ignorer les fonctionnalités pour lesquelles les utilisateurs n'ont pas accordé les niveaux d'accès requis. Cela permet au reste du flux d'exécution de se poursuivre sans demander l'autorisation pour les niveaux d'accès 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("dana@example.com", "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 s'exécutent automatiquement, et il est possible que les utilisateurs ne soient pas présents pour fournir des 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 publiez une application qui utilise des autorisations restreintes, elle doit respecter toutes les spécifications.

Consultez la liste complète des champs d'application restreints avant de publier. Les applications conformes doivent respecter les exigences supplémentaires pour les champs d'application d'API spécifiques.

Si possible, évitez d'utiliser des niveaux d'accès restreints pour simplifier le processus d'examen. Vous pouvez utiliser librement les portées restreintes pour les applications non publiques.