Utilitaires Bridge : Appel API

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

• Profils : conservent des informations sur les API système auxquelles vous souhaitez connecter vos flux de travail. 

• Le module Appel API utilise les données de profil et les détails spécifiques que vous fournissez pour effectuer un appel API vers une API système.

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

Conseil sur l’outil de création Bridge

Les profils simplifient les modifications de flux de travail en cas de changement d’informations clés, comme votre jeton d’autorisation ou l’URL de base. Une mise à jour du profil permet de s’assurer que tous les modules l’appelant reçoivent les dernières données pour effectuer l’appel.

Module Make API Call 

C’est le seul module de l’utilitaire et il contient les champs suivants :

Endpoint

Ce champ 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 de vos déclencheurs Bridge. Voici des exemples de configuration pour des données statiques ou dynamiques :

• Valeur d’ID statique — Le format de l’URL pour ce type de données est le suivant : https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Spécifiez 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 le suivant : https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Cependant, au lieu d’ajouter l’ID de la feuille, vous devez ajouter la référence de données de la feuille à partir du journal d’exécution. 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.

Méthode

La méthode définit le type d’opérations que vous souhaitez effectuer. Définissez une méthode pour chaque appel API dans le module Appel API. 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 quelque chose. 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.

En-têtes

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 (permissions). Par exemple, dans les appels Smartsheet, vous disposeriez d’un en-tête clé nommé Authorization dont la valeur serait définie sur Bearer [Entrez votre jeton API].

Le profil peut configurer les en-têtes requis pour chaque appel à un système. Dans votre flux de travail, le module Make API Call vous permet de configurer des en-têtes supplémentaires pour des actions spécifiques. 

Paramètres de formulaire 

Les paramètres de formulaire sont également connus sous le nom de paramètres de requête ou d'arguments. Les paramètres de formulaire sont des éléments supplémentaires que vous pouvez définir dans la demande. Vous les définissez dans le module Make API Call.

Un scénario d'exemple serait d'appliquer la pagination avec des appels Smartsheet pour inclure certains éléments dans la réponse. Par exemple, vous ne souhaitez obtenir que la première page d’un rapport de 20 000 lignes.

Corps de la requête HTTP

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

L'envoi de paramètres de formulaire remplace les données du corps.

Dans un appel API Sort Sheet, un corps ressemblerait à ceci : {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. Le corps dans cet exemple pourrait utiliser l'un de ces types de valeur :

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

Un corps peut ne pas être nécessaire selon le type de demande que vous effectuez. Par exemple, vous n'avez pas besoin de corps pour les appels GET.

Résultat

Si l'API qui répond renvoie un objet JSON, il est enregistré dans le journal d'exécution. Cela vous permet de référencer les données renvoyées plus tard dans le flux de travail.

Ce dont vous avez besoin pour commencer

• Une feuille 
  • L'ID de la feuille
  • Une colonne qui, lorsqu'elle est modifiée dans vos lignes, déclenche votre flux de travail Bridge sur
• Bridge
  • Intégration de Smartsheet
  • Déclencheur de flux de travail Bridge : Smartsheet - When Column Values are Changed
  • Module Bridge : Utilitaires > Appeler l'API > Faire un appel API
• Une clé API Smartsheet.

Pour créer ce flux de travail dans Bridge, authentifiez l'intégration Smartsheet pour votre espace de travail 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 facilite la navigation dans le processus de création.

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

Tirez 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

1. Sélectionnez le module Déclencheur.
2. Dans la section Intégrations, sélectionnez la page Intégrations.

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

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

4. Développez la ligne Déclencheurs.
5. Pour créer un nouveau déclencheur, sélectionnez Ajouter aux Déclencheurs.
6. Remplissez les champs suivants :
   • Nom du déclencheur : Créez une étiquette personnalisée pour votre déclencheur.
   • ID de la feuille : Collez l'ID de votre feuille (celle que vous souhaitez trier).
   • Type d'événement : Sélectionnez Quand les valeurs de colonne sont modifiées. 
   • Nom ou ID de la colonne : Tapez le nom de la colonne Smartsheet à laquelle vous souhaitez répondre. Par exemple, si vous allez trier les lignes de la feuille chaque fois que la priorité change, tapez le nom de votre colonne de priorité.
   • Sélectionner un flux de travail : Sélectionnez le nouveau flux de travail que vous venez de créer dans la liste déroulante.
7. Sélectionnez Enregistrer.
8. Copiez l'ID de la colonne dans les informations sur le déclencheur. Une fois que vous avez enregistré le déclencheur de flux de travail, l'ID de la colonne devient disponible dans les informations sur le déclencheur.
9. Collez-le dans le Bloc-notes ou un logiciel de traitement de texte. Vous avez besoin de l’ID de la colonne lors d’une étape ultérieure. 
10. Retournez à votre flux de travail.

Obtenir les détails de l’appel API

Ce flux de travail change la valeur dans la colonne de priorité de votre déclencheur de feuille. Une fois que ce flux de travail détecte le ou les déclencheurs, il effectue les actions nécessaires sur cette feuille. Nous utilisons 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 devez effectuer 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. Accédez à l’onglet Integrations.
2. Sélectionnez l’utilitaire Call API.
3. Développez la section Profiles dans l’onglet Profiles.

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.  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, comme des jetons d’API.
   • Par exemple, dans les appels Smartsheet, vous disposez généralement d’un en-tête clé nommé Authorization, dont la valeur est définie sur Bearer [Enter your API token].
8. Sous Headers, ajoutez les en-têtes qui doivent être inclus dans tous les appels d’API que vous effectuez avec ce profil.
   • Dans cet exemple, nous avons utilisé Content-Type comme en-tête avec une valeur définie sur application/json.
9. Sélectionnez Enregistrer.
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 reste 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 vous permet d’inclure les détails spécifiques et les actions que vous devez effectuer avec cet appel d’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, donc nous devons 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 votre profil API à utiliser 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. Enregistrez 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 lignes triées sont dans l’ordre croissant ou décroissant (selon ce que vous avez défini dans le corps de l’appel API) des valeurs telles qu’elles apparaissent 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

• Configurez un déclenchement à partir d’une feuille ou d’une colonne différente de celle que vous souhaitez trier. Cela nécessite de modifier les détails de l’appel API pour s’adapter à la feuille et à 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 0, déplacez la ligne hors de la feuille et si la priorité est 1, triez la feuille).
• Utilisez un déclencheur Schedule. Lorsque vous utilisez ce déclencheur, vous n’avez pas besoin de répondre aux changements car il trie 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 (Passer un appel d’API) 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.
• Le module Make API Call réussit s’il reçoit une réponse de l’API cible, y compris s’il reçoit une erreur. Cela est utile dans les étapes ultérieures pour déterminer les chemins dans votre flux de travail pour des réponses inattendues de l’API (par exemple, si l’appel API renvoie une erreur, vous pouvez envoyer une mise à jour à une ligne indiquant qu’il y a eu un problème). Si vous préférez que le flux de travail s’arrête si l’API renvoie une erreur, vous pouvez cocher la case sous la section Additional Settings du module.