Configurer l’outil Call API

Cette configuration nécessite des connaissances en API et en codage.

L’outil Call API vous permet de gérer les appels API publics de vos flux de travail d’automatisation dans Bridge. Il comporte deux éléments principaux : 

• Profiles : le profil conserve les informations sur les API système auxquelles vous souhaitez connecter vos flux de travail. 

• Module Make API Call : utilise les données de profil et les détails que vous fournissez pour effectuer un appel API vers une API système.

   

Conseil sur l’outil de création Bridge

Les profils permettent également de modifier facilement les flux de travail au cas où des informations clés changeraient, comme votre jeton d’autorisation ou l’URL de base. Une mise à jour du profil permettra de s’assurer que tous les modules l’appelant reçoivent les dernières données pour effectuer l’appel.

Champs d’API Call

Avant de commencer, passons en revue quelques points terminologiques sur l’utilisation des API.

Base URL

Ce champ est contenu dans le profil. Il s’agit de l’URL de l’API qui reste toujours la même. Pour Smartsheet, vous utiliseriez l’URL de base : https://api.smartsheet.com/2.0/

Endpoint

Ce champ est contenu dans le module Make API Call et spécifie l’action que vous souhaitez effectuer (par exemple, trier la feuille). Dans cette valeur, vous pouvez ajouter toutes les références de données dont vous avez besoin à partir de vos déclencheurs Bridge.

Voici des exemples de configuration pour des données statiques ou dynamiques :

• Valeur Static ID : le format de l’URL pour ce type de données est le suivant. https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Vous devez spécifier l’ID de la feuille dans cette URL, de sorte que l’appel API trie toujours cette feuille spécifique. 
• Référence de données Dynamic Run Log : le format de l’URL pour ces données est similaire à celui de la valeur d’ID statique. https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Cependant, au lieu d’ajouter l’ID de la feuille, vous devrez ajouter la référence de données de la feuille à partir de l’élément Run Log du flux de travail Bridge. Cela est utile si votre flux de travail Bridge se déclenche en cas de modifications ou récupère des données provenant de plusieurs feuilles. Lorsque vous utilisez ce type d’URL, l’appel API trie la feuille spécifique référencée dans cette URL.

Method

La méthode définit le type d’opérations que vous essayez d’effectuer. Pour configurer la méthode de chaque appel API, accédez au module Make API Call. La plupart des API décrivent la méthode requise pour un point de terminaison API donné. Par exemple, avec Smartsheet, voici les méthodes que vous utiliserez :

• GET : intégrez des données à votre flux de travail Bridge en « obtenant » une ligne d’une feuille.
• POST : créez un élément. Par exemple, ajoutez une ligne à une feuille.
• PUT : mettez à jour un élément. Par exemple, actualisez une ligne d’une feuille.
• DELETE : supprimez un élément. Par exemple, supprimez une ligne d’une feuille.

Headers

Les en-têtes sont les valeurs dont vous avez besoin pour la demande et les paires clé-valeur. Ils sont généralement utilisés pour gérer les autorisations. Par exemple, dans les appels Smartsheet, vous disposeriez d’un en-tête clé nommé « Authorization », dont la valeur serait définie sur Bearer [Enter your API token].

Les en-têtes requis pour chaque appel vers un système peuvent être configurés dans le profil. Des en-têtes supplémentaires pour des actions spécifiques peuvent être configurés dans le module Make API Call de votre flux de travail. 
 

Form Parameters 

L’élément Form Parameters est également appelé Query Parameters ou Arguments. Il s’agit d’éléments supplémentaires que vous pouvez définir dans la demande. Pour cela, accédez au module Make API Call.

L’application de la pagination avec des appels Smartsheet, de sorte que seul un certain nombre d’éléments sont inclus dans la réponse, en est un exemple. Par exemple, vous ne souhaitez obtenir que la première page d’un rapport de 20 000 lignes.
 

Body

Le corps comporte les détails pertinents de la demande que vous devez envoyer. Il est généralement au format JSON.

L’envoi de Form Parameters remplace les données du corps.

Dans un appel API Sort Sheet, le corps ressemblerait à ce qui suit : {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. Le corps dans l’exemple ci-dessus peut utiliser l’un des types valeur suivants :

• une valeur statique pour une colonne spécifique d’une feuille, ou
• une référence dynamique des données Run Log, où l’ID de la colonne s’affiche. 

Selon votre type de demande, un corps peut ne pas être nécessaire. Par exemple, vous n’aurez pas besoin de corps pour les appels GET.
 

Données renvoyées

Si l’API qui répond renvoie un objet JSON, celui-ci sera enregistré dans le journal d’exécution (Run Log). Son enregistrement vous permet de référencer les données renvoyées dans des parties ultérieures du flux de travail.

Désormais, vous savez quels champs vous rencontrerez lors de la configuration des profils Call API et des modules Make API Call. Lisez la suite pour en savoir plus sur la configuration et l’utilisation de cette fonction d’utilitaire.

Ce dont vous avez besoin pour commencer

• Une feuille 
  • L’ID de la feuille
  • Une colonne sur laquelle vous souhaitez déclencher votre flux de travail Bridge lorsqu’elle est modifiée sur vos lignes.
• Bridge
  • Intégration de Smartsheet
  • Déclencheur de flux de travail Bridge : Smartsheet - When Column Values are Changed
  • Modules de flux de travail Bridge : Make API Call
• Une clé API Smartsheet. Découvrez comment générer une clé API pour Smartsheet. 

Premiers pas

Pour créer ce flux de travail dans Bridge, authentifiez l’intégration Smartsheet pour votre espace de travail Bridge. Lisez les étapes de configuration de l’intégration de Smartsheet pour Bridge. 

Pendant la création de votre flux de travail, gardez votre feuille, la documentation sur l’API Smartsheet et votre flux de travail Bridge ouverts dans trois onglets distincts. Cela facilitera la navigation dans le processus de création.

Étape 1 : Créer le modèle de flux de travail de base

Avant tout, extrayez tous les modules dont vous avez besoin pour le flux de travail. 

1. Créez un nouveau flux de travail dans Bridge. 
2. Dans l’outil de création de flux de travail, utilisez le panneau pour ajouter le module Make API Call.
3. Enregistrez le flux de travail.

Voici ce que vous devez voir dans votre flux de travail lorsque vous avez terminé : 

Brandfolder Image

Configurer le déclencheur de flux de travail

Après avoir créé le modèle de flux de travail de base, commencez à configurer le déclencheur de flux de travail.

1. Sélectionner le module Trigger.
2. Pour ouvrir le panneau Integration dans un nouvel onglet, dans la section Integrations, sélectionnez Integrations Page.

3. Localisez Smartsheet dans la liste des intégrations.
    

   Vous pouvez utiliser l’option Connected sous le logo Bridge pour obtenir une liste des intégrations authentifiées uniquement pour cet espace de travail.

4. Développez la ligne Triggers.
5. Pour créer un nouveau déclencheur, sélectionnez l’icône plus.
6. Remplissez les champs suivants :
   • Trigger Name : créez une étiquette personnalisée pour votre déclencheur.
   • Sheet ID : collez l’ID de votre feuille (celle que vous souhaitez trier).
   • Event Type : sélectionnez When Column Values are Changed. 
   • Column Name or ID : saisissez le nom de la colonne Smartsheet à laquelle vous souhaitez répondre. Par exemple, si vous souhaitez trier les lignes de la feuille à chaque fois que la priorité change, saisissez le nom de votre colonne de priorité.
   • Select Workflow : sélectionnez dans la liste déroulante le nouveau flux de travail que vous venez de créer.
7. Sélectionnez Save.
8. Dans les informations sur l’élément Trigger, copiez l’ID de la colonne.
   • L’ID de la colonne sera disponible dans les informations sur le déclencheur une fois que vous aurez enregistré le déclencheur de flux de travail.
9. Collez-le dans le bloc-notes ou un logiciel de traitement de texte. Vous aurez besoin de l’ID de la colonne lors d’une étape ultérieure. 

10. Retournez à votre flux de travail.
     

    Si vous souhaitez retourner à l’onglet d’origine, actualisez la page pour voir le déclencheur.

Obtenir les détails de l’appel API

Les changements de valeur dans la colonne de priorité de votre feuille se déclenchent dans ce flux de travail. Une fois que ce flux de travail détecte le ou les déclencheurs, il effectue les actions nécessaires sur cette feuille. Nous utiliserons donc les références de données de runtime (Run Log) du déclencheur pour remplir les modules Smartsheet.

Pour ce flux de travail, vous effectuerez un appel API au point de terminaison Smartsheet Sort Sheet. Utilisez la documentation sur l’API Smartsheet pour remplacer l’exemple par cURL.

Étape 2 : Configurer votre premier profil

Les profils permettent d’enregistrer les informations clés sur les API système auxquelles vous souhaitez connecter vos flux de travail. Lorsque vous sélectionnez un profil dans le module Make API Call, certaines des informations nécessaires pour effectuer votre appel API sont déjà configurées. 

1. Connectez-vous à votre compte Bridge.
2. Accédez à l’onglet Integrations.
3. Sélectionnez la fonction utilitaire Call API.

4. Sélectionnez Add to Profiles.

   Brandfolder Image

   
5. Donnez un nom à votre profil. Chaque nom doit être unique.
6. Ajoutez l’URL de base de l’API système à laquelle vous souhaitez vous connecter.
   • Dans cet exemple, l’URL de base pour Smartsheet est : https://api.smartsheet.com/2.0/
7. Dans Secret Headers, ajoutez des en-têtes qui contiennent des jetons ou des informations secrètes (par exemple, des jetons API).
   • Par exemple, dans les appels Smartsheet, vous disposeriez d’un en-tête clé nommé Authorization, dont la valeur serait définie sur Bearer [Enter your API token].
8. Dans Headers, ajoutez les en-têtes qui doivent être inclus dans tous les appels API que vous effectuez avec ce profil.
   • Dans cet exemple, nous avons Content-Type en tant qu’en-tête avec une valeur définie sur application/json.
9. Enregistrez le profil.

10. Retournez à votre flux de travail.

     

Conseil sur l’outil de création Bridge

L’URL de base est la partie de l’URL de l’API système qui restera toujours la même, quelle que soit l’opération que vous essayez d’effectuer dans ce système. Le point de terminaison du module Make API Call permet d’inclure les détails spécifiques et les actions que vous devez effectuer avec cet appel API.

Exemple : Utilisons l’API Smartsheet pour trier une feuille. L’URL de base de notre profil API Smartsheet est https://api.smartsheet.com/2.0 et l’action spécifique que nous effectuons avec le module est de trier une feuille donnée. Par conséquent, nous allons mettre sheets/sheet_id_or_data_reference_here/sort dans le champ Endpoint du module.

Étape 3 : Configurer le module Make API Call dans le flux de travail

1. Dans le module Make API Call, sélectionnez le profil souhaité dans le menu déroulant.
2. Dans le champ Endpoint, incluez la partie du champ d’URL qui n’a pas été ajoutée au champ Base URL dans le profil.
   • Dans cet exemple, nous avons utilisé sheets/sheet_id_or_data_reference_here/sort.
3. Remplissez les champs suivants. Notez que vous ne pouvez pas tous les utiliser :
   • Définissez Method sur POST.
   • Dans le champ HTTP Request Body, le corps devrait ressembler à ce qui suit : {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}
   • Form Parameters (à définir selon si vous l’utilisez ou non pour le flux de travail en question).

4. enregistrer vos modifications.

   Brandfolder Image

   

   
    

Étape 4 : Tester le flux de travail

1. Ouvrez votre feuille. 
2. Modifiez une valeur dans votre colonne de priorité. 
3. Enregistrez la feuille. 

Si votre colonne de priorité est une liste déroulante, les valeurs des lignes triées seront dans l’ordre croissant ou décroissant (selon ce que vous avez défini dans le corps de l’appel API), tel qu’elles s’affichent dans les paramètres de la colonne. 

Paramètres supplémentaires du module

• Le module Make API Call retourne tous les appels API sous forme d’objet JSON. Si vous avez besoin que la réponse soit renvoyée sous forme de chaîne, vous pouvez cocher la case Return raw response sous Additional settings dans le module.
• Si vous devez inclure des en-têtes supplémentaires pour un appel spécifique, copiez-les dans la section HTTP Request Headers.

Autres options pour ce flux de travail

Voici quelques idées pour personnaliser ce flux de travail :

• Configurez un déclenchement à partir d’une feuille ou d’une colonne différente de celle que vous souhaitez trier. Vous devrez alors modifier les détails du module API Call en fonction de la feuille et de la colonne que vous souhaitez trier. 
• Ajoutez une condition à votre tri. Une fois le flux de travail déclenché, utilisez un module de jonction pour évaluer la valeur de votre colonne et effectuer différentes actions en fonction de la modification apportée à la colonne de priorité (par exemple, si la priorité est définie sur 0, déplacez la ligne hors de la feuille ; si la priorité est définie sur 1, triez la feuille).
• Utilisez un déclencheur Schedule. Lorsque vous utiliserez ce déclencheur, vous n’aurez pas besoin de répondre aux modifications, car il triera la feuille une fois par jour, semaine ou mois.

Utiliser les outils Call API dans toutes vos solutions

• Les profils s’appliquent à l’espace de travail. Par conséquent, tous les flux de travail de votre espace peuvent utiliser le même profil dans tous les modules Make API Call utilisés. Lorsque des détails du profil doivent être modifiés en raison d’un changement des autorisations d’un utilisateur ou d’une modification de l’API système, il existe un endroit unique où effectuer ces ajustements et les appliquer aux flux de travail de l’espace qui utilisent ce profil.
• Pour chaque API système supplémentaire à laquelle vous devez vous connecter, vous pouvez configurer un nouveau profil unique en suivant la première partie du guide.