Tâche Apps Script

La tâche Apps Script vous permet d'exécuter Google Apps Script à partir de votre intégration. Google Apps Script est une plate-forme de développement d'applications qui permet de créer rapidement et facilement des applications d'entreprise. Pour en savoir plus, consultez la section Google Apps Script. Cette tâche est utile lorsque vous souhaitez exécuter des scripts personnalisés ou réutiliser des scripts existants dans votre intégration.

Avant de commencer

Avant d'utiliser la tâche Apps Script, procédez comme suit :

Activer l'API AppsScript
Créer un ID client OAuth 2.0
Configurer un profil d'authentification
Assurez-vous que VPC Service Controls n'est PAS configuré pour Apigee Integration dans votre projet Google Cloud.
Avertissement : La fonction Cloud ne fonctionne pas ou cesse de fonctionner si VPC Service Controls est configuré pour Apigee Integration dans votre projet Google Cloud.

Activer l'API AppsScript

Pour utiliser cette tâche, vous devez activer l'API AppsScript dans votre projet Google Cloud et votre compte utilisateur AppsScript. Pour en savoir plus sur l'activation de l'API AppsScript dans votre projet Google Cloud, consultez la page Activer une API dans un projet Google Cloud standard. Pour activer l'API dans votre compte utilisateur, cliquez sur Paramètres et définissez Google Apps Script API sur On.

Créer un ID client OAuth 2.0

Si vous disposez d'un ID client OAuth 2.0, vous pouvez ignorer cette étape et passer à la section Configurer un profil d'authentification.

Pour en savoir plus sur la création d'un ID client OAuth, consultez la page Créer un ID client OAuth.

Configurer un profil d'authentification

Apigee Integration utilise le profil d'authentification pour se connecter à Google Cloud afin de déployer et d'exécuter le projet Apps Script. Pour configurer un profil d'authentification, procédez comme suit :

Ajouter la tâche Apps Script

Dans l'interface utilisateur Apigee, sélectionnez votre organisation Apigee.
Cliquez sur Développer > Intégrations.
Sélectionnez une intégration existante ou créez-en une en cliquant sur Créer une intégration.
Si vous créez une intégration :
1. Saisissez un nom et une description dans la boîte de dialogue Créer une intégration.
2. Dans la liste des régions compatibles, sélectionnez une région pour l'intégration.
3. Cliquez sur Créer.
La page de conception d'intégration s'affiche.
Dans la barre de navigation de la page de conception d'intégration, cliquez sur +Ajouter une tâche ou un déclencheur > Tâches pour afficher la liste des tâches disponibles.
Cliquez sur l'élément Apps Script et placez-le dans l'éditeur d'intégration.

Créer un profil d'authentification

Cliquez sur l'élément Apps Script dans le concepteur pour afficher le volet de configuration des tâches Apps Script.
Dans le volet de configuration de la tâche Apps Script, cliquez sur le bouton + Nouveau profil d'authentification.
Dans la boîte de dialogue Profil d'authentification, saisissez un nom et une description pour le profil, puis définissez les propriétés suivantes :
- Type d'authentification : sélectionnez le code d'autorisation OAuth 2.0.
- Point de terminaison d'authentification : saisissez https://accounts.google.com/o/oauth2/auth.
- Point de terminaison de jeton : saisissez https://oauth2.googleapis.com/token
- ID client : saisissez l'ID client.
  L'ID client est disponible dans le tableau de bord de votre projet Google Cloud, sous Identifiants > ID clients OAuth 2.0.
- Code secret : saisissez le code secret du client.
  Le code secret du client est disponible dans le tableau de bord de votre projet Google Cloud, sous Identifiants > ID client OAuth 2.0.
- Champ(s) d'application : saisissez les informations suivantes :
  https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email
  
  Remarque : Les champs d'application multiples peuvent être séparés par un seul espace (" ").
Cliquez sur Générer un jeton d'accès et enregistrer.
Vous êtes redirigé vers un écran d'autorisation. Connectez-vous et accordez les autorisations indiquées à l'écran pour générer votre jeton d'accès. Si la génération du jeton d'accès réussit, votre profil d'authentification est enregistré et vous pouvez continuer à modifier votre intégration.

Configurer la tâche Apps Script

Pour configurer un projet Apps Script dans la tâche Apps Script, procédez comme suit :

Dans le volet de configuration de la tâche, cliquez sur Configurer un projet Apps Script.
La boîte de dialogue Configuration d'Apps Script s'affiche.
Vous pouvez choisir d'associer votre projet à un projet Apps Script existant ou créer un nouveau projet Apps Script.
La configuration d'un projet Apps Script associe le projet Apps Script à votre intégration dans Apigee Integration.
Cliquez sur "Enregistrer".
Cliquez sur Ouvrir un projet Apps Script.
Dans l'éditeur Apps Script, les fichiers suivants s'affichent :
- Run.gs : contient le code exécutable. Écrivez votre script dans la fonction run. Cette fonction est appelée lors de l'exécution de la tâche Apps Script. Dans votre script, vous pouvez utiliser les variables définies au niveau de l'intégration. Pour en savoir plus sur l'utilisation des variables d'intégration, consultez la section Utiliser des variables d'intégration.
- Main.gs : contient le code d'initialisation permettant d'exécuter Apps Script à partir de votre intégration. Ne modifiez pas ce fichier.
- Test.gs : contient le code exécutable pour exécuter des tests. Vous pouvez écrire votre script dans la fonction testRun pour tester le script.
Assurez-vous de déployer le projet au format Applications Web. Pour en savoir plus sur les différents modes de déploiement, consultez la section Créer et gérer des déploiements.

Accéder aux variables d'intégration

La tâche Apps Script utilise la bibliothèque AppsScriptTask, qui vous permet d'utiliser des variables d'intégration dans votre script. La bibliothèque AppsScriptTask est automatiquement importée et peut être utilisée dans la fonction run.

Pour accéder à une variable d'intégration dans Apps Script, vous devez transmettre la variable sous forme de paramètres de tâche à la tâche Apps Script. Les paramètres de tâche sont des paires clé/valeur où Key est le nom de la variable dans votre tâche AppsScript et Value est le nom de la variable d'intégration correspondante. Vous pouvez ajouter un ou plusieurs paramètres de tâche dans la section Paramètres de tâche du volet de configuration de la tâche.

Par exemple, si vous avez une variable d'intégration nomméeProduit que vous souhaitez utiliser dans Apps Script, vous pouvez définir Key en tant que ProductKey et la valeur en tant que Product. Dans Apps Script, vous pouvez ensuite utiliser AppsScriptTask.getTaskParameter('ProductKey') pour lire la variable Product.

La bibliothèque AppsScriptTask fournit les méthodes suivantes pour accéder aux variables d'intégration :

Nom de la fonction Description Utilisation

Nom de la fonction	Description	Utilisation
`setIntegrationVariable`	Définit la valeur fournie sur la variable.	Syntaxe : `setIntegrationVariable(value,value)` Exemple : // Write to an Integer variable AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');
`getTaskParameter`	Récupère la valeur d'une variable.	Syntaxe : `getTaskParameter(value)` Exemple : // Read an integration variable AppsScriptTask.getTaskParameter('EmployeeIDKey');

`setIntegrationVariable`

Définit la valeur fournie sur la variable.

Syntaxe : setIntegrationVariable(value,value)

Exemple :

// Write to an Integer variable
AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');

`getTaskParameter`

Récupère la valeur d'une variable.

Syntaxe : getTaskParameter(value)

Exemple :

// Read an integration variable
AppsScriptTask.getTaskParameter('EmployeeIDKey');

Pour afficher toutes les fonctions disponibles dans la bibliothèque AppsScriptTask, passez la souris sur l'élément de menu AppsScriptTask dans votre éditeur Apps Script, puis cliquez sur Plus AppsScriptTask.

Tester votre Apps Script

Avant de publier votre intégration, vous pouvez tester votre script à l'aide de la fonction testRun disponible dans le fichier testRun. Écrivez votre code de test dans la fonction testRun à l'aide de la bibliothèque testRun. Cette bibliothèque vous permet d'exécuter des scénarios de test basés sur l'assertion. Elle est automatiquement importée et peut être utilisée dans la fonction testRun.

Pour afficher toutes les fonctions disponibles dans la bibliothèque AppsScriptTaskTest, passez la souris sur l'élément de menu AppsScriptTaskTest dans votre éditeur Apps Script, puis cliquez sur Plus AppsScriptTaskTest.

L'exemple suivant illustre l'utilisation des fonctions de la bibliothèque AppsScriptTaskTest.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

L'exemple suivant montre comment accéder aux variables JSON et aux variables de tableau dans la méthode testRun :

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);


  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

Après avoir exécuté les scénarios de test, vous pouvez afficher les assertions dans le journal d'exécution. Pour afficher les journaux, cliquez sur Journal d'exécution dans le menu.

Bonnes pratiques

Nous vous déconseillons d'utiliser la tâche Apps Script si vous avez besoin d'une latence inférieure à 1 à 2 secondes pour la tâche de votre intégration.

De plus, nous vous recommandons de coder votre logique dans une seule tâche Apps Script plutôt que de mettre en chaîne plusieurs tâches Apps Script, afin de réduire les goulots d'étranglement affectant les performances.

Pour en savoir plus sur les limites d'utilisation qui s'appliquent à la tâche Apps Script, consultez la section Limites d'utilisation.

Remarques

Lorsque vous incluez la tâche Apps Script dans votre conception d'intégration, tenez compte des limitations suivantes du système :

Nombre maximal de déploiements actifs pour un AppsScript : 50
Requêtes par seconde (RPS) pour les exécutables de l'API : 5 000/min
Requêtes par seconde (RPS) pour les déploiements d'applications Web : 5 000/min
Latence pour les exécutables de l'API : 1,5 s
Latence pour Webapp : 2,5 s
Taille maximale cumulée de toutes les variables d'intégration dans un AppsScript : 15 Mo

Stratégie de traitement des erreurs

Une stratégie de traitement des erreurs d'une tâche spécifie l'action à effectuer si celle-ci échoue en raison d'une erreur temporaire. Pour en savoir plus sur l'utilisation et les différents types de stratégies de traitement des erreurs, consultez la page Stratégies de traitement des erreurs.