Documentation › Appeler une API

Appeler une API depuis une étape

Une étape Task peut appeler un service externe (REST, SOAP ou GraphQL) : la personne qui fait la tâche clique sur un bouton, le service répond, et les valeurs de la réponse vont dans des variables du process.

Le principe

1. Le concepteur ouvre l’étape Task dans l’éditeur et définit l’appel dans l’onglet API call : où appeler, avec quoi, comment s’identifier, ce qu’on attend en retour et quelles valeurs garder.
2. La définition est enregistrée avec le process. Rien n’est appelé à la publication.
3. Dans une instance de process, la personne qui fait la tâche voit un panneau API call et clique sur Call the API.
4. La réponse s’affiche, et les valeurs gardées sont écrites dans les résultats (Outcomes) de la tâche, donc dans les variables du process.

Définir l’appel (onglet API call)

Dans le formulaire de l’étape Task, ouvrez l’onglet API call puis cliquez sur Add an API call. Le bouton Remove the API call retire l’appel de l’étape, et le lien Documentation ouvre cette page. Devant chaque champ, le bouton (i) explique ce qu’il faut saisir, avec un exemple, et renvoie à la section correspondante de cette page.

La requête

• Kind of call : REST (une requête HTTP simple), SOAP (un message XML envoyé à un service web) ou GraphQL (une requête à une adresse unique).
• Method (REST) : GET lit, POST crée, PUT remplace, PATCH modifie, DELETE supprime, HEAD et OPTIONS. SOAP et GraphQL utilisent toujours POST.
• Address (URL) : l’adresse complète, qui commence par http:// ou https://.
• Time to wait for an answer (seconds) : de 1 à 120, 30 par défaut.

Les paramètres de chemin : /{id}/{nom}

Écrivez entre accolades les parties de l’adresse qui changent, par exemple https://www.site.com/{id}/{nom}. Dans Path parameters, le bouton Add the parameters of the address crée une ligne par partie ; donnez à chacune sa valeur, écrite ici ou prise dans une variable (bouton lien). La valeur est encodée pour vous : les espaces et les barres obliques ne cassent pas l’adresse.

• Chaque partie entre accolades doit avoir sa ligne, et chaque ligne doit servir dans l’adresse : sinon la publication est refusée avec un message qui le dit.
• Ne les confondez pas avec une variable du process, qui s’écrit ${NomDeLaVariable} (voir Utiliser les variables).

Paramètres de requête et en-têtes

Query parameters (ajoutés à l’adresse : ?page=2&size=10) et Headers sont des lignes « nom / valeur ». Décochez Send pour garder une ligne sans l’envoyer. Content-Type est déduit du type de corps : ne l’écrivez que pour en utiliser un autre.

Le corps

• REST (Body) : aucun, JSON, texte, XML, formulaire (URL encodé) ou formulaire (multipart). Dans un texte, ${Variable} est remplacé par la valeur, protégée selon le type : {"client": "${Client}", "quantite": ${Quantite}} (une variable qui contient un nombre s’écrit sans guillemets).
• SOAP (SOAP message) : la version (1.1 ou 1.2, celle du WSDL du service), l’action (SOAPAction, par exemple http://tempuri.org/GetPrice) et le message : toute l’enveloppe, ou seulement le contenu de son Body (l’enveloppe est alors ajoutée).
• GraphQL (GraphQL document) : la requête, par exemple query GetUser($id: ID!) { user(id: $id) { name } }, ses variables en JSON ({"id": "${IdUtilisateur}"}) et le nom de l’opération si le document en contient plusieurs.

L’autorisation

Authorization : les secrets sont masqués à la saisie et peuvent venir d’une variable.

• Basic : nom d’utilisateur et mot de passe.
• Bearer token : un jeton, envoyé après le mot Bearer (ou le préfixe que vous donnez).
• API key : le nom de la clé (par exemple X-Api-Key), sa valeur, et où l’envoyer (dans un en-tête ou dans les paramètres de requête).
• OAuth 2.0 : l’appel obtient d’abord un jeton auprès du service de jetons (Address of the token service, souvent terminée par /token) avec l’identifiant et le secret du client (Client id, Client secret) et, au choix, les Scope demandés ou un nom d’utilisateur et un mot de passe. Cochez l’envoi dans le corps si le service ne veut pas d’en-tête.
• Digest : le service lance un défi, la réponse hachée est envoyée automatiquement.

L’authentification de l’utilisateur

Quand un service demande à la personne de se connecter, cochez This call logs the user in (section User authentication). Dessinez cet appel, ou ces appels (un par étape), selon le type d’autorisation du service : jeton, session, etc.

• Dans l’instance de process, la personne qui fait la tâche voit un nom d’utilisateur, un mot de passe et le bouton Log in à la place de Call the API.
• Écrivez ${Login.Username} et ${Login.Password} dans l’adresse, les en-têtes, le corps ou l’autorisation (par exemple l’utilisateur et le mot de passe d’une autorisation Basic).
• Extrayez le jeton (JsonPath) ou la session (en-tête Set-Cookie) dans des variables : les appels suivants les utilisent (jeton Bearer, en-tête Cookie).
• Le nom d’utilisateur et le mot de passe ne sont jamais enregistrés, et la réponse de la connexion n’est pas affichée : seules les valeurs gardées dans les variables le sont.

La réponse attendue

• Response type : ce qu’est le corps de la réponse (JSON, XML ou texte). Choisissez-le pour être averti quand le service répond autre chose. Il décide aussi des façons de lire une valeur : un chemin JSON pour du JSON, un XPath pour du XML ; Any (not checked) ne vérifie rien.
• Status codes : les codes qui signifient un succès, par exemple 200-299,404. Toute autre réponse fait échouer l’appel.
• Example of a response : un aide-mémoire pour vous, non vérifié.

Un appel échoue aussi quand le service répond par une erreur SOAP (Fault) ou par des errors GraphQL, même avec un statut 200.

Les valeurs à extraire de la réponse

Values to extract from the response : chaque ligne lit une valeur dans la réponse et la met dans une variable du process. Un résultat (Outcomes) est ajouté à l’étape pour chaque variable.

• Read from : JSON path, XPath, Response header, Status code ou Whole body. Les choix s’adaptent au type de la réponse.
• Path or name :
  • Chemin JSON : $.data.id, $.items[0].name (premier élément), $.items[-1] (dernier), $.items[*].id (chaque élément), $..id (n’importe où), $['a b'] (nom avec une espace).
  • XPath : //GetPriceResult, //Item[1]/@id, count(//Item). Les espaces de noms sont ignorés.
  • En-tête : son nom, par exemple ETag.
• Variable : la variable qui reçoit la valeur. Un nombre, une date (2030-03-15), un oui/non (true, yes, 1), une adresse email ou le nom d’une option (variable liste) doivent convenir au type de la variable.
• Required : si la valeur est absente ou ne convient pas, l’appel échoue (sinon la valeur est ignorée).

Utiliser les variables du process

• Pour une valeur d’une ligne ou d’un secret, cliquez sur le bouton en forme de lien : la valeur est alors prise dans une variable au moment de l’appel (variable de portée Process ou Global).
• Dans une adresse ou un texte (corps, message SOAP, requête GraphQL), écrivez ${NomDeLaVariable}, ou utilisez Insert a variable in the text. La valeur est protégée selon l’endroit où elle va (JSON, XML, adresse).
• Une variable sans valeur au moment de l’appel l’arrête : rien n’est envoyé et le message nomme les variables manquantes.
• Un appel peut utiliser ce qu’un appel précédent a gardé : par exemple un jeton obtenu par une première tâche et utilisé comme jeton Bearer par la suivante.

Faire l’appel dans une instance de process

Sur la page d’une tâche de type Task qui a un appel, le panneau API call résume l’appel (type, méthode, adresse, authentification, statuts attendus) et la liste des Extracted values. Cliquez sur Call the API :

• Le cadre Response montre Succeeded ou Failed, le statut, la durée, le corps (JSON mis en forme) et les en-têtes.
• Values from the response indique, pour chaque valeur, Applied ou Not applied (avec la raison). Les résultats de la tâche et les variables sont mis à jour.
• Si l’appel échoue (service injoignable, statut inattendu, erreur SOAP « fault », erreurs GraphQL, valeur obligatoire introuvable, valeur qui ne convient pas au type de la variable), aucune variable n’est modifiée.
• Vous pouvez refaire l’appel : les valeurs sont remplacées.

Sécurité et limites

• Les secrets saisis dans la définition sont enregistrés avec le process et ne sont jamais renvoyés aux personnes qui font la tâche.
• L’appel est fait par le serveur de ProcNest : les adresses d’un réseau privé (localhost, 10.x, 192.168.x, services de métadonnées du cloud…) sont refusées, sauf réglage de l’administrateur.
• Le corps de la réponse est coupé au-delà d’environ 1 Mo ; on ne peut alors plus y lire de valeur de façon fiable.

Astuces

• Testez votre service avec un outil comme Postman avant de le définir ici : les champs sont les mêmes.
• Choisissez un format de réponse (JSON ou XML) pour être averti si le service répond autre chose.
• Une valeur de type liste (simple list, multi-choice list) doit porter le nom d’une option de la variable.