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éTypeDescription
AuthModeAuthModeÉnumération qui identifie les catégories de services autorisés qu'Apps Script peut exécuter via une fonction déclenchée.
AuthorizationStatusAuthorizationStatusÉnumération indiquant l'état d'autorisation d'un script.
EventTypeEventTypeÉnumération indiquant le type d'événement déclenché.
InstallationSourceInstallationSourceÉnumération indiquant comment le script a été installé en tant que module complémentaire pour l'utilisateur.
TriggerSourceTriggerSourceÉnumération indiquant la source de l'événement qui déclenche le déclencheur.
WeekDayWeekdayÉnumération représentant les jours de la semaine.

Méthodes

MéthodeType renvoyéBrève description
deleteTrigger(trigger)voidSupprime le déclencheur donné afin qu'il ne s'exécute plus.
getAuthorizationInfo(authMode)AuthorizationInfoRécupère un objet utilisé pour déterminer si l'utilisateur doit autoriser ce script à utiliser un ou plusieurs services, et pour fournir l'URL d'une boîte de dialogue d'autorisation.
getIdentityToken()StringRécupère un jeton d'identité OpenIDConnect pour l'utilisateur effectif, si le champ d'application openid a été accordé.
getInstallationSource()InstallationSourceRenvoie 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()StringRé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()StringRécupère l'ID unique du projet de script.
getService()ServiceRé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()voidAnnule l'autorisation dont dispose l'utilisateur effectif pour exécuter le script en cours.
newStateToken()StateTokenBuilderCrée un constructeur pour un jeton d'état pouvant être utilisé dans une API de rappel (comme un flux OAuth).
newTrigger(functionName)TriggerBuilderLance le processus de création d'un déclencheur installable qui, lorsqu'il est déclenché, appelle une fonction donnée.

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

NomTypeDescription
triggerTriggerDé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 utilisé pour déterminer si l'utilisateur doit autoriser ce script à utiliser un ou plusieurs services, et pour fournir l'URL d'une boîte de dialogue d'autorisation. Si le script est publié en tant que composant complémentaire qui utilise des déclencheurs installables, ces informations peuvent être utilisées pour contrôler l'accès aux sections de code pour lesquelles l'utilisateur ne dispose pas de l'autorisation nécessaire. Le module complémentaire peut également demander à l'utilisateur d'ouvrir l'URL de la boîte de dialogue d'autorisation pour résoudre le problème. 

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

Paramètres

NomTypeDescription
authModeAuthModeMode 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

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 (quelques minutes minimum). 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 requises en plus 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

NomTypeDescription
documentDocumentFichier 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

NomTypeDescription
formFormFichier 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

NomTypeDescription
spreadsheetSpreadsheetFichier 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

NomTypeDescription
functionNameStringFonction à 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

Méthodes obsolètes