Class ScriptApp

ScriptApplication

Accéder et manipuler la publication et les déclencheurs de script. Cette classe permet aux utilisateurs de créer des déclencheurs de script et de contrôler la publication du script en tant que service.

Propriétés

Propriété	Type	Description
AuthMode	AuthMode	Énumération qui identifie les catégories de services autorisés qu'Apps Script peut exécuter via une fonction déclenchée.
AuthorizationStatus	AuthorizationStatus	Énumération indiquant l'état d'autorisation d'un script.
EventType	EventType	Énumération indiquant le type d'événement déclenché.
InstallationSource	InstallationSource	Énumération indiquant comment le script a été installé en tant que module complémentaire pour l'utilisateur.
TriggerSource	TriggerSource	Énumération indiquant la source de l'événement qui déclenche le déclencheur.
WeekDay	Weekday	Énumération représentant les jours de la semaine.

Méthodes

Méthode	Type renvoyé	Brève description
deleteTrigger(trigger)	void	Supprime le déclencheur donné afin qu'il ne s'exécute plus.
getAuthorizationInfo(authMode)	AuthorizationInfo	Récupère un objet qui vérifie si l'utilisateur a accordé l'autorisation pour toutes les exigences du script.
getAuthorizationInfo(authMode, oAuthScopes)	AuthorizationInfo	Récupère un objet qui vérifie si l'utilisateur a accordé l'autorisation pour les champs d'application demandés.
getIdentityToken()	String	Récupère un jeton d'identité OpenIDConnect pour l'utilisateur effectif, si le champ d'application openid a été accordé.
getInstallationSource()	InstallationSource	Renvoie une valeur d'énumération indiquant comment le script a été installé en tant qu'add-on pour l'utilisateur actuel (par exemple, si l'utilisateur l'a installé personnellement via le Chrome Web Store ou si un administrateur de domaine l'a installé pour tous les utilisateurs).
getOAuthToken()	String	Récupère le jeton d'accès OAuth 2.0 de l'utilisateur effectif.
getProjectTriggers()	Trigger[]	Récupère tous les déclencheurs installables associés au projet et à l'utilisateur actuels.
getScriptId()	String	Récupère l'ID unique du projet de script.
getService()	Service	Récupère un objet utilisé pour contrôler la publication du script en tant qu'application Web.
getUserTriggers(document)	Trigger[]	Récupère tous les déclencheurs installables appartenant à cet utilisateur dans le document donné, pour ce script ou ce module complémentaire uniquement.
getUserTriggers(form)	Trigger[]	Récupère tous les déclencheurs installables appartenant à cet utilisateur dans le formulaire donné, pour ce script ou ce module complémentaire uniquement.
getUserTriggers(spreadsheet)	Trigger[]	Récupère tous les déclencheurs installables appartenant à cet utilisateur dans la feuille de calcul donnée, pour ce script ou ce module complémentaire uniquement.
invalidateAuth()	void	Annule l'autorisation dont dispose l'utilisateur effectif pour exécuter le script actuel.
newStateToken()	StateTokenBuilder	Crée un constructeur pour un jeton d'état pouvant être utilisé dans une API de rappel (comme un flux OAuth).
newTrigger(functionName)	TriggerBuilder	Lance le processus de création d'un déclencheur installable qui, lorsqu'il est déclenché, appelle une fonction donnée.
requireAllScopes(authMode)	void	Vérifie si l'utilisateur a donné son autorisation pour tous les champs d'application demandés par le script.
requireScopes(authMode, oAuthScopes)	void	Vérifie si l'utilisateur a accordé son consentement pour les portées demandées.

Méthodes obsolètes

Méthode	Type renvoyé	Brève description
getProjectKey()	String	Récupère la clé de projet du script en cours.
getScriptTriggers()	Trigger[]	Récupère tous les déclencheurs installables associés au projet et à l'utilisateur actuels.

Documentation détaillée

deleteTrigger(trigger)

Supprime le déclencheur donné afin qu'il ne s'exécute plus.

// Deletes all triggers in the current project.
const triggers = ScriptApp.getProjectTriggers();
for (let i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

Paramètres

Nom	Type	Description
trigger	Trigger	Déclencheur à supprimer.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des champs d'application suivants:

• https://www.googleapis.com/auth/script.scriptapp

---

getAuthorizationInfo(authMode)

Récupère un objet qui vérifie si l'utilisateur a accordé l'autorisation pour toutes les exigences du script. L'objet fournit également une URL d'autorisation permettant aux utilisateurs d'accorder ces autorisations, au cas où l'une des exigences du script ne serait pas autorisée.

Certaines exécutions de script peuvent commencer sans le consentement de l'utilisateur pour tous les champs d'application requis utilisés par le script. Les informations de cet objet vous permettent de contrôler l'accès aux sections de code qui nécessitent certains champs d'application et de demander l'autorisation de ces champs d'application pour les exécutions ultérieures.

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

Paramètres

Nom	Type	Description
authMode	AuthMode	Mode d'autorisation pour lequel des informations d'autorisation sont demandées. Dans la quasi-totalité des cas, la valeur de authMode doit être ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL), car aucun autre mode d'autorisation n'exige que les utilisateurs accordent une autorisation.

Renvois

AuthorizationInfo : objet pouvant fournir des informations sur l'état d'autorisation de l'utilisateur.

---

getAuthorizationInfo(authMode, oAuthScopes)

Récupère un objet qui vérifie si l'utilisateur a accordé l'autorisation pour les champs d'application demandés. L'objet fournit également une URL d'autorisation permettant aux utilisateurs d'accorder ces autorisations, au cas où l'un des champs d'application demandés ne serait pas autorisé.

Certaines exécutions de script peuvent commencer sans le consentement de l'utilisateur pour tous les champs d'application requis utilisés par le script. Les informations de cet objet vous permettent de contrôler l'accès aux sections de code qui nécessitent certains champs d'application et de demander l'autorisation de ces champs d'application pour les exécutions ultérieures. Les champs d'application non valides ou non requis par le script génèrent une erreur.

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

Paramètres

Nom	Type	Description
authMode	AuthMode	Mode d'autorisation pour lequel des informations d'autorisation sont demandées. Dans la quasi-totalité des cas, la valeur de authMode doit être ScriptApp.AuthMode.FULL, car aucun autre mode d'autorisation n'exige que les utilisateurs accordent une autorisation.
oAuthScopes	String[]	Champ d'application OAuth pour lequel des informations d'autorisation sont demandées.

Renvois

AuthorizationInfo : objet qui fournit des informations sur l'état d'autorisation de l'utilisateur et une URL d'autorisation au cas où certains consentements seraient manquants.

---

getIdentityToken()

Récupère un jeton d'identité OpenIDConnect pour l'utilisateur effectif, si le champ d'application openid a été accordé. Ce champ d'application n'est pas inclus par défaut. Vous devez l'ajouter en tant que champ d'application explicite dans le fichier manifeste pour le demander. Incluez les champs d'application https://www.googleapis.com/auth/userinfo.email ou https://www.googleapis.com/auth/userinfo.profile pour renvoyer des informations utilisateur supplémentaires dans le jeton.

Le jeton d'identification renvoyé est un jeton Web JSON (JWT) encodé et doit être décodé pour en extraire des informations. Les exemples suivants montrent comment décoder le jeton et extraire l'ID de profil Google de l'utilisateur effectif.

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);

Consultez la documentation sur OpenID Connect pour obtenir la liste complète des champs (revendications) renvoyés.

Renvois

String : jeton d'identité, s'il est disponible. Sinon, null.

---

getInstallationSource()

Renvoie une valeur d'énumération indiquant comment le script a été installé en tant qu'add-on pour l'utilisateur actuel (par exemple, si l'utilisateur l'a installé personnellement via le Chrome Web Store ou si un administrateur de domaine l'a installé pour tous les utilisateurs).

Renvois

InstallationSource : source de l'installation.

---

getOAuthToken()

Récupère le jeton d'accès OAuth 2.0 de l'utilisateur effectif. Si les habilitations OAuth du script sont suffisantes pour autoriser une autre API Google qui nécessite normalement son propre flux OAuth (comme Google Picker), les scripts peuvent contourner la deuxième invite d'autorisation en transmettant ce jeton à la place. Le jeton expire au bout d'un certain temps (au moins quelques minutes). Les scripts doivent gérer les échecs d'autorisation et appeler cette méthode pour obtenir un nouveau jeton si nécessaire.

Le jeton renvoyé par cette méthode n'inclut que les portées dont le script a actuellement besoin. Les portées qui étaient auparavant autorisées, mais qui ne sont plus utilisées par le script, ne sont pas incluses dans le jeton renvoyé. Si des habilitations OAuth supplémentaires sont nécessaires au-delà de celles requises par le script lui-même, elles peuvent être spécifiées dans le fichier manifeste du script.

Renvois

String : représentation sous forme de chaîne du jeton OAuth 2.0.

---

getProjectTriggers()

Récupère tous les déclencheurs installables associés au projet et à l'utilisateur actuels.

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

Renvois

Trigger[] : tableau des déclencheurs de l'utilisateur actuel associés à ce projet.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des champs d'application suivants:

• https://www.googleapis.com/auth/script.scriptapp

---

getScriptId()

Récupère l'ID unique du projet de script. Il s'agit de la méthode privilégiée pour obtenir l'identifiant unique du projet de script par rapport à getProjectKey(). Cet ID peut être utilisé partout où la clé de projet était précédemment fournie.

Renvois

String : ID du projet de script.

---

getService()

Récupère un objet utilisé pour contrôler la publication du script en tant qu'application Web.

// Get the URL of the published web app.
const url = ScriptApp.getService().getUrl();

Renvois

Service : objet utilisé pour observer et contrôler la publication du script en tant qu'application Web.

---

getUserTriggers(document)

Récupère tous les déclencheurs installables appartenant à cet utilisateur dans le document donné, pour ce script ou ce module complémentaire uniquement. Cette méthode ne permet pas de voir les déclencheurs associés à d'autres scripts.

const doc = DocumentApp.getActiveDocument();
const triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

Paramètres

Nom	Type	Description
document	Document	Fichier Google Docs pouvant contenir des déclencheurs installables.

Renvois

Trigger[] : tableau de déclencheurs appartenant à cet utilisateur dans le document donné.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des champs d'application suivants:

• https://www.googleapis.com/auth/script.scriptapp

---

getUserTriggers(form)

Récupère tous les déclencheurs installables appartenant à cet utilisateur dans le formulaire donné, pour ce script ou ce module complémentaire uniquement. Cette méthode ne permet pas de voir les déclencheurs associés à d'autres scripts.

const form = FormApp.getActiveForm();
const triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

Paramètres

Nom	Type	Description
form	Form	Fichier Google Forms pouvant contenir des déclencheurs installables.

Renvois

Trigger[] : tableau de déclencheurs appartenant à cet utilisateur dans le formulaire donné.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des champs d'application suivants:

• https://www.googleapis.com/auth/script.scriptapp

---

getUserTriggers(spreadsheet)

Récupère tous les déclencheurs installables appartenant à cet utilisateur dans la feuille de calcul donnée, pour ce script ou ce module complémentaire uniquement. Cette méthode ne permet pas de voir les déclencheurs associés à d'autres scripts.

const ss = SpreadsheetApp.getActiveSpreadsheet();
const triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

Paramètres

Nom	Type	Description
spreadsheet	Spreadsheet	Fichier Google Sheets pouvant contenir des déclencheurs installables.

Renvois

Trigger[] : tableau de déclencheurs appartenant à cet utilisateur dans la feuille de calcul donnée.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des champs d'application suivants:

• https://www.googleapis.com/auth/script.scriptapp

---

invalidateAuth()

Annule l'autorisation dont dispose l'utilisateur effectif pour exécuter le script en cours. Permet d'invalider toutes les autorisations du script actuel. Cela est particulièrement utile pour les fonctions taguées comme autorisation ponctuelle. Étant donné que les fonctions d'autorisation unique ne peuvent être appelées que lors de la première exécution après que le script a acquis l'autorisation, si vous souhaitez effectuer une action par la suite, vous devez révoquer toute autorisation dont le script disposait afin que l'utilisateur puisse à nouveau voir la boîte de dialogue d'autorisation.

ScriptApp.invalidateAuth();

Génère

Error : en cas d'échec de l'invalidation

---

newStateToken()

Crée un constructeur pour un jeton d'état pouvant être utilisé dans une API de rappel (comme un flux OAuth).

// Generate a callback URL, given the name of a callback function. The script
// does not need to be published as a web app; the /usercallback URL suffix
// replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the
  // /edit at the end.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const stateToken = ScriptApp.newStateToken()
                         .withMethod(callbackFunction)
                         .withTimeout(120)
                         .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

Dans la plupart des flux OAuth2, le jeton state est transmis directement au point de terminaison d'autorisation (et non dans l'URL de rappel), puis le point de terminaison d'autorisation le transmet dans l'URL de rappel.

Exemple :

• Le script redirige l'utilisateur vers l'URL d'autorisation OAuth2: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
• L'utilisateur clique sur "Autoriser", et la page d'autorisation OAuth2 le redirige vers https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants .
• La redirection ci-dessus (retour à http://script.google.com/...) entraîne la requête du navigateur vers /usercallback, qui appelle la méthode spécifiée par StateTokenBuilder.withMethod(method).

Renvois

StateTokenBuilder : objet utilisé pour poursuivre le processus de création de jetons d'état.

---

newTrigger(functionName)

Lance le processus de création d'un déclencheur installable qui, lorsqu'il est déclenché, appelle une fonction donnée.

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

Paramètres

Nom	Type	Description
functionName	String	Fonction à appeler lorsque le déclencheur est activé. Vous pouvez utiliser les fonctions des bibliothèques incluses, telles que Library.libFunction1.

Renvois

TriggerBuilder : objet utilisé pour poursuivre le processus de création de déclencheur.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des champs d'application suivants:

• https://www.googleapis.com/auth/script.scriptapp

---

requireAllScopes(authMode)

Vérifie si l'utilisateur a donné son autorisation pour tous les champs d'application demandés par le script. Utilisez cette méthode si un flux d'exécution repose sur tous les champs d'application qu'un script demande. Si des consentements sont manquants, cette méthode met fin à l'exécution en cours et affiche une invite d'autorisation pour demander les consentements manquants.

Cette méthode ne fonctionne que lorsque les utilisateurs exécutent le script à partir d'une surface compatible avec le consentement précis, par exemple depuis l'IDE Apps Script. Lorsque le script est exécuté avec des autorisations manquantes à partir d'une surface non prise en charge, telle qu'un module complémentaire Google Workspace, il affiche une invite d'autorisation au début de l'exécution pour demander tous les champs d'application.

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

Paramètres

Nom	Type	Description
authMode	AuthMode	Mode d'autorisation pour lequel les portées de script doivent être évaluées. Dans la quasi-totalité des cas, la valeur de authMode doit être ScriptApp.AuthMode.FULL, car aucun autre mode d'autorisation ne nécessite que les utilisateurs accordent une autorisation.

---

requireScopes(authMode, oAuthScopes)

Vérifie si l'utilisateur a accordé son consentement pour les champs d'application demandés. Utilisez cette méthode si un flux d'exécution repose sur un ou plusieurs services. Si l'une des autorisations spécifiées est manquante, cette méthode met fin à l'exécution en cours et affiche une invite d'autorisation pour demander les autorisations manquantes. Les champs d'application non valides ou non requis par le script génèrent une erreur.

Cette méthode ne fonctionne que lorsque les utilisateurs exécutent le script à partir d'une surface compatible avec le consentement précis, par exemple depuis l'IDE Apps Script. Lorsque le script est exécuté avec des autorisations manquantes provenant d'une surface non prise en charge, telle qu'un module complémentaire Google Workspace, il affiche une invite d'autorisation au début de l'exécution pour demander tous les champs d'application.

ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);

Paramètres

Nom	Type	Description
authMode	AuthMode	Mode d'autorisation pour lequel les champs d'application demandés doivent être évalués. Dans la quasi-totalité des cas, la valeur de authMode doit être ScriptApp.AuthMode.FULL, car aucun autre mode d'autorisation ne nécessite que les utilisateurs accordent une autorisation.
oAuthScopes	String[]	Champs d'application OAuth requis pour effectuer le flux d'exécution donné.

Méthodes obsolètes

getProjectKey()

Obsolète.Utilisez plutôt getScriptId().

Récupère la clé de projet du script en cours. La clé de projet est un identifiant unique pour les scripts et permet de composer l'URL de rappel utilisée avec newStateToken().

Lorsqu'il est appelé dans une bibliothèque, il renvoie la clé de projet du script le plus externe en cours d'exécution.

Renvois

String : clé de projet du script en cours.

---

getScriptTriggers()

Obsolète. Cette fonction est obsolète et ne doit pas être utilisée dans les nouveaux scripts.

Récupère tous les déclencheurs installables associés au projet et à l'utilisateur actuels.

Logger.log(
    `Current script has ${ScriptApp.getScriptTriggers().length} triggers.`,
);

Renvois

Trigger[] : tableau des déclencheurs de l'utilisateur actuel associés à ce projet.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des champs d'application suivants:

• https://www.googleapis.com/auth/script.scriptapp