Consultez la liste des connecteurs compatibles avec Application Integration.

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

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

Application 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

  1. Dans la console Google Cloud, accédez à la page Application Integration.

    Accéder à Application Integration

  2. Dans le menu de navigation, cliquez sur Intégrations.

    La page Intégrations s'affiche, listant toutes les intégrations disponibles dans le projet Google Cloud.

  3. Sélectionnez une intégration existante ou cliquez sur Créer une intégration pour en créer une.

    Si vous créez une intégration :

    1. Saisissez un nom et une description dans le volet Create Integration (Créer une intégration).
    2. Sélectionnez une région pour l'intégration.
    3. Sélectionnez un compte de service pour l'intégration. Vous pouvez modifier ou mettre à jour les détails du compte de service d'une intégration à tout moment à partir du volet Integration summary (Résumé de l'intégration) dans la barre d'outils de l'intégration.
    4. Cliquez sur Créer.

    Cela entraîne son ouverture dans l'éditeur d'intégrations.

  4. Dans la barre de navigation de l'éditeur d'intégrations, cliquez sur Tâches pour afficher la liste des tâches et des connecteurs disponibles.
  5. Cliquez sur l'élément Apps Script et placez-le dans l'éditeur d'intégration.

Créer un profil d'authentification

  1. Cliquez sur l'élément Apps Script dans le concepteur pour afficher le volet de configuration des tâches Apps Script.
  2. Dans le volet de configuration de la tâche Apps Script, cliquez sur le bouton + Nouveau profil d'authentification.
  3. 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 (" ").

  4. 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 :

  1. 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.

  2. 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 Application Integration.

  3. Cliquez sur Enregistrer.
  4. 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

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 > Ouvrir dans un nouvel onglet.

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 Test.gs. Écrivez votre code de test dans la fonction testRun à l'aide de la bibliothèque AppsScriptTaskTest. 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 > Ouvrir dans un nouvel onglet.

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.

Exclusions du Contrat de niveau de service

La tâche Apps Script est une dépendance liée au produit Google Apps Script. Cette dépendance étant externe à Application Integration, toutes les exécutions de active intégrations échouent en raison d'une défaillance dans la tâche Apps Script, sont exclus Application Integration Conditions d'utilisation du contrat de niveau de service

Quotas et limites

Pour plus d'informations sur les quotas et les limites, consultez la section Quotas et limites.

Étape suivante