Aller au contenu

Étape Requête REST

L’étape Requête REST appelle une API REST comme une étape d’un workflow. C’est une étape unique, dans le style de Postman, pour toute la boucle « construire → envoyer → inspecter » : choisissez un point de terminaison (saisi à la main ou importé depuis une collection Postman, une spécification OpenAPI/Swagger ou une capture HAR), définissez les en-têtes, les paramètres de requête et un corps, envoyez une requête de test pour voir la réponse en direct, puis enregistrez l’étape.

Vous choisissez la destination de la réponse. Par défaut, elle est analysée dans une table. L’étape peut aussi capturer la réponse dans des variables de workflow afin qu’une étape ultérieure puisse se brancher selon le code de statut ou lire une valeur dans le corps.

Si vous fermez ou rechargez le navigateur avant d’enregistrer, l’éditeur conserve un brouillon local dans ce navigateur. Rouvrez la même étape et choisissez Restaurer à l’invite pour récupérer les paramètres de requête non enregistrés.

Vous voudrez généralement une connexion de type REST, qui contient l’URL de base et l’authentification du service. L’étape peut aussi appeler directement une URL complète sans connexion. Consultez Connexions REST.

  1. Ouvrez le workflow et ajoutez une étape à l’endroit voulu.
  2. Choisissez Requête REST (unifiée) comme type d’étape (sous les étapes REST). L’éditeur s’ouvre avec un onglet Requête, un onglet Réponse et un onglet Sélection des données de la table.

Dans l’onglet Requête :

Choisissez comment vous fournirez le point de terminaison, puis PlaidCloud renseigne la requête à votre place :

  • Manual : saisissez vous-même la méthode et l’URL.
  • À partir de la définition d’API de la connexion : utilisez la définition OpenAPI/Swagger stockée sur la connexion que vous avez choisie, afin de ne pas la répéter à chaque étape. Consultez Réutiliser la définition d’API d’une connexion ci-dessous.
  • Collection Postman (fichier) / Collection Postman (URL) : importez depuis une collection Postman.
  • OpenAPI / Swagger (URL) / OpenAPI / Swagger (fichier) : importez depuis une spécification d’API.
  • Archive HAR (fichier) : importez une requête capturée depuis le journal réseau de votre navigateur.

Pour une source importée, choisissez Charger le catalogue pour lister les points de terminaison disponibles, puis choisissez-en un sous Point de terminaison. L’étape renseigne sa méthode, son URL, ses en-têtes, ses paramètres de requête et son corps, en utilisant l’exemple ou la valeur par défaut de chaque paramètre ; un paramètre facultatif qui n’a ni l’un ni l’autre démarre désactivé. Si la requête contient déjà quelque chose que vous avez saisi, l’étape demande confirmation avant de le remplacer. Appuyez sur Ctrl+Z (Cmd+Z sur Mac) lorsque vous ne saisissez pas dans un champ, ou choisissez Annuler le remplacement, pour rétablir la requête précédente.

Un grand catalogue se réduit facilement : saisissez dans Filtrer par méthode, chemin ou nom… pour ne lister que les points de terminaison correspondants. Le catalogue indique le nombre de points de terminaison qu’il contient (12 sur 340 lorsqu’il est filtré) et le moment de son chargement, et l’étape signale quand une définition très volumineuse a été tronquée à sa limite d’aperçu.

Coller une collection ou une spécification au lieu de choisir un fichier

Section intitulée « Coller une collection ou une spécification au lieu de choisir un fichier »

Les trois sources basées sur un fichier (collection Postman, OpenAPI/Swagger et archive HAR) proposent chacune un bouton Coller… à côté du sélecteur de fichier. Utilisez-le lorsque vous avez le contenu sous la main mais ne l’avez pas enregistré dans Document : collez le JSON et choisissez Utiliser celui-ci. Le catalogue se charge immédiatement ; inutile de cliquer ensuite sur Charger le catalogue.

Le contenu collé est utilisé à la place du sélecteur de fichier et dure tant que l’étape reste ouverte : il n’est pas enregistré avec l’étape, donc collez-le de nouveau si vous rouvrez l’étape et voulez recharger le catalogue à partir de celui-ci. Si vous choisissez un fichier pour cette même source, le fichier l’emporte et le contenu collé est abandonné ; l’étape vous le signale.

Vous pouvez aussi déposer un fichier .json sur le sélecteur de source. L’étape contrôle le contenu par rapport à la source choisie et vous indique ce qui ne va pas, par exemple une collection Postman collée là où une spécification OpenAPI est attendue ou un fichier qui n’est pas du JSON, et chaque source comporte un lien How do I get a …? qui explique comment exporter une collection Postman, une spécification OpenAPI ou un fichier HAR.

Réutiliser la définition d’API d’une connexion

Section intitulée « Réutiliser la définition d’API d’une connexion »

Les connecteurs conçus pour un service précis connaissent déjà leurs points de terminaison. Les connexions REST génériques et MuleSoft non : elles peuvent pointer vers n’importe quelle API, et vous permettent donc de rattacher la définition de l’API à la connexion elle-même.

Définissez-la une fois sur la connexion (consultez Connexion REST générique), puis, dans toute étape qui utilise cette connexion :

  1. Choisissez la connexion sous Connexion.
  2. Définissez Source du point de terminaison sur À partir de la définition d’API de la connexion.
  3. Choisissez Charger le catalogue et sélectionnez votre point de terminaison.

Toutes les étapes qui partagent cette connexion proposent la même liste de points de terminaison, et la mise à jour de la définition sur la connexion les met toutes à jour.

Sous le sélecteur de Connexion, une ligne de résumé indique ce que l’étape utilisera : le type d’authentification, l’hôte et le nombre d’en-têtes par défaut que la connexion envoie avec chaque requête. Choisissez le bouton d’actualisation à côté du sélecteur après avoir modifié la connexion pour recharger son authentification, son hôte et ses en-têtes par défaut sans rouvrir l’étape. Lorsque la connexion définit des environnements, le sélecteur Environnement choisit celui sur lequel l’étape s’exécute.

  • Connexion : la connexion REST avec laquelle s’authentifier. Laissez-la vide pour appeler directement une URL complète. Utilisez le raccourci de modification à côté du sélecteur pour afficher ou modifier la connexion sélectionnée sans quitter l’éditeur de requête.
  • Méthode : GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS.
  • Point de terminaison : le chemin (lorsqu’une connexion est définie) ou une URL complète.
  • En-têtes et Paramètres de requête sont des tableaux modifiables de lignes nom/valeur, chacune avec un bouton Sur et une description. Ajoutez des lignes avec Ajouter et supprimez-les avec Supprimer.
  • Corps contient la charge utile de la requête (JSON, formulaire ou brute) dans un éditeur de code.

Formater le JSON indente le corps, et Valider le JSON le contrôle et signale la ligne et la colonne de toute erreur. Les deux lisent chaque variable {{…}} comme une valeur, de sorte que vos variables restent exactement telles que vous les avez écrites. Référence des variables… répertorie toutes les variables utilisables dans la requête, et Insérer {{…}} place une variable au niveau du curseur.

Pendant la modification, l’étape signale les problèmes sous la requête :

  • Un nom d’en-tête ou de paramètre de requête qui apparaît deux fois, où une valeur serait perdue.
  • Un nom d’en-tête qui semble mal saisi, avec une suggestion Did you mean…, comme Authorisation pour Authorization.
  • Un secret, comme une valeur Authorization ou X-API-Key, saisi en clair. Conservez-le dans une variable de projet et écrivez {{project_var.NAME}} pour que le secret ne soit pas stocké dans l’étape.
  • Un corps JSON sans en-tête Content-Type: application/json, que certains serveurs refusent avec un HTTP 415.
  • Une URL dont le schéma est mal saisi, avec une double barre oblique dans le chemin, une barre oblique finale ou des espaces parasites.

N’importe où dans le point de terminaison, les en-têtes, les valeurs de requête ou le corps, vous pouvez injecter une variable à l’exécution en plaçant son nom entre doubles accolades : {{name}}. Vous pouvez aussi écrire {{var.name}} pour une variable d’exécution de workflow ou {{project_var.name}} pour une variable de projet ; le préfixe est facultatif et les deux résolvent le même nom.

L’éditeur met en évidence les jetons {{...}} détectés dans le point de terminaison, les tableaux d’en-têtes et de requête, et l’éditeur de corps, afin que les substitutions soient faciles à repérer avant de tester ou d’enregistrer.

Seules les doubles accolades sont substituées : une simple { ou } dans un corps JSON reste exactement telle qu’écrite, vous pouvez donc mêler librement des variables au JSON, par exemple {"id": "{{var.order_id}}", "qty": 1}. Un nom de variable inconnu fait échouer l’étape, de sorte qu’une faute de frappe apparaît immédiatement.

Lorsque le workflow est démarré par un capteur ou un webhook, quatre variables de déclenchement sont aussi disponibles : {{trigger_sensor_id}}, {{trigger_sensor_type}}, {{trigger_fired_at}} et {{trigger_payload_json}} (la charge utile entrante sous forme de chaîne JSON ; analysez-la dans une étape ultérieure pour atteindre les champs imbriqués). Lors d’une exécution manuelle ou planifiée, elles se résolvent en chaîne vide.

  • Envoyer une requête de test envoie la requête avec vos paramètres actuels et affiche la réponse en direct, directement dans le formulaire, afin que vous puissiez confirmer que l’appel fonctionne avant d’enregistrer. Appuyez sur Ctrl+Entrée (Cmd+Entrée sur Mac) pour envoyer depuis n’importe où dans le formulaire. Une ligne d’état indique le statut HTTP et le temps de réponse, et un chronomètre s’incrémente pendant que la requête est en cours. (Cela envoie une seule requête ; la pagination ne s’exécute que lorsque l’étape s’exécute.)
  • Tester la pagination suit la pagination configurée et indique combien d’enregistrements reviennent sur l’ensemble des pages (jusqu’à un plafond d’aperçu), afin que vous puissiez confirmer que le mode de pagination et ses paramètres/chemins s’enchaînent correctement avant une exécution complète. Seul le nombre de pages nécessaire pour atteindre le plafond est envoyé.
  • Copier en curl copie dans le presse-papiers une commande curl équivalente à des fins de partage ou de débogage (secrets masqués).
  • Importer depuis curl fait l’inverse : collez une commande curl (par exemple, « Copy as cURL » d’un navigateur) et sa méthode, son URL, ses en-têtes et son corps remplacent la requête actuelle. L’authentification de base (-u) devient un en-tête Authorization ; les options non prises en charge sont signalées plutôt qu’ignorées silencieusement. Utilisez Annuler le remplacement pour restaurer les valeurs précédentes.

La réponse s’ouvre dans une visionneuse avec les vues Formaté et Compact. Les cinq derniers résultats de test sont conservés tant que l’étape est ouverte, et vous pouvez en choisir un pour l’afficher de nouveau ou le réexécuter. Lorsque la réponse contient une liste d’enregistrements, Suggérer définit Chemin des éléments sur la première liste trouvée.

Le groupe Aperçu de la requête affiche la requête exactement telle qu’une exécution l’enverrait, avec les variables résolues et les secrets masqués, sans rien envoyer. Choisissez Actualiser l’aperçu après vos modifications.

Si vous modifiez les champs de la requête sortante et enregistrez avant une Envoyer une requête de test réussie, PlaidCloud demande Enregistrer sans test réussi ? et vous choisissez Enregistrer quand même ou revenez en arrière. En mode d’éventail, utilisez Tester la ligne 1 pour tester la première ligne pilote avant d’enregistrer.

Dans l’onglet Réponse, définissez la Destination de la réponse :

La réponse est analysée dans la Table cible, obligatoire dans ce mode. Choisissez une table existante ou créez-en une depuis le sélecteur ; les vues ne sont pas proposées. Le groupe Pagination et analyse contrôle la manière de procéder :

  • Format de ligne : Objet (par défaut) lorsque chaque enregistrement est un objet JSON, ou Tableau lorsque chaque enregistrement est une liste de valeurs. Tableau n’est pas disponible avec Une requête par ligne de table. Chemin des éléments indique où se trouvent les enregistrements dans la réponse.

  • Mode de pagination : Aucune pagination (par défaut), Pagination par décalage, Pagination par numéro de page, Pagination par URL de page suivante, Pagination par curseur ou Pagination par en-tête Link (RFC 5988). Paramètres du mode et Chemins du mode indiquent quels paramètres et quels champs de réponse pilotent la pagination, et ils ne sont disponibles que lorsqu’un mode de pagination est choisi. Choisir un mode renseigne les deux avec ses valeurs par défaut, que vous pouvez modifier.

    Mode Paramètres du mode par défaut Chemins du mode par défaut Fonctionnement de la pagination
    Décalage {"offset": "offset", "limit": "limit"} {"has_more": ["has_more"]} Envoie les paramètres de requête de décalage et de limite, et continue de lire tant que has_more de la réponse est vrai.
    Numéro de page {"offset": "page"} {"has_more": ["has_more"]} Envoie le numéro de page dans le paramètre page, et n’envoie aucune limite.
    URL de page suivante {} {"next": ["next"]} Demande l’URL trouvée au chemin next de chaque réponse. Une URL relative est lue par rapport à la page dont elle provient.
    Curseur {"cursor": "after"} {"has_more": ["has_more"], "cursor": ["next_cursor"]} Envoie le curseur de la réponse précédente dans le paramètre after. Ajoutez "send_as": "header" ou "send_as": "body_field" à Paramètres du mode pour l’envoyer plutôt comme en-tête de requête ou comme champ du corps. Pour lire le curseur dans un en-tête de réponse, comme l’en-tête x-ms-continuation qu’envoie Azure Cosmos DB, placez "token_header": "x-ms-continuation" dans Chemins du mode à la place de has_more et cursor ; la dernière page est celle sans l’en-tête.
    En-tête Link {"rel": "next"} {} Suit la relation de l’en-tête de réponse Link nommée par rel.

    Décalage et Numéro de page acceptent d’autres clés dans Paramètres du mode : start est le premier décalage ou numéro de page (0 par défaut), stop_on_empty s’arrête à la première page sans enregistrement au chemin des éléments, de sorte que la réponse n’a pas besoin de champ has_more, et send_limit indique si le paramètre limit est envoyé (vrai par défaut pour Décalage, faux pour Numéro de page).

  • Extraire le JSON brut au lieu d’analyser les lignes : stocke la charge utile brute plutôt que de l’analyser en colonnes.

  • Nouvelles tentatives (0 à 100) et Délai d’expiration (s) (1 à 600) : comportement de la requête en cas d’échec et durée pendant laquelle elle peut s’exécuter. Une exécution attend jusqu’au délai d’expiration que vous définissez ; Envoyer une requête de test, Tester la ligne 1 et Tester la pagination attendent au plus 300 s. Les nouvelles tentatives couvrent les échecs de connexion, les erreurs serveur (5xx) et la limitation de débit (HTTP 429) pour les méthodes idempotentes (GET, HEAD, OPTIONS, DELETE). Une requête POST, PUT ou PATCH n’est retentée qu’après une réponse de limitation de débit (HTTP 429), qui vous indique que le serveur n’a rien fait de la requête, et jamais après une erreur serveur ; ainsi, un corps de requête non idempotent n’est jamais envoyé deux fois alors que le serveur a pu agir dessus ; lorsque l’API renvoie un en-tête Retry-After, l’étape attend l’intervalle demandé (plafonné à 2 minutes) avant de réessayer.

L’onglet Sélection des données de la table associe les champs de la réponse aux colonnes de la table cible. Inspecter la source → Populate renseigne le mappage à partir d’une réponse en direct : il envoie la requête de l’étape via sa connexion, comme le ferait une exécution. Il nécessite une connexion et demande confirmation d’abord lorsque la méthode est autre que GET, HEAD ou OPTIONS. Résumer et Distinct ne sont pas proposés ici, car l’étape écrit la réponse analysée directement dans la table cible.

Définissez Destination sur Variables du workflow et indiquez un Préfixe de variable (un nom simple comme my_call). L’étape envoie une requête et écrit quatre variables de workflow :

Variable Contenu
{prefix}_status Code de statut HTTP (par exemple, 200).
{prefix}_body Corps de la réponse sous forme de chaîne (les réponses JSON sont stockées sous forme de texte JSON).
{prefix}_headers En-têtes de la réponse sous forme de texte JSON.
{prefix}_elapsed_ms Durée de la requête, en millisecondes.

Référencez-les en aval comme n’importe quelle variable de workflow, par exemple {my_call_status}. C’est la brique de base des schémas « envoyer une requête, puis se brancher selon le résultat ».

Par défaut, l’étape envoie une requête. Pour appeler une API une fois par ligne d’une table (par exemple, rechercher chaque identifiant client d’une table, ou envoyer chaque ligne en POST comme enregistrement), définissez Envoyer (dans l’onglet Requête) sur Une requête par ligne de table. Cela révèle les champs de la table pilote :

  • Table d’inducteurs : choisissez la table dont les lignes pilotent les requêtes. Sélectionnez-la parmi les tables du workflow avec le sélecteur, ou saisissez un nom de table. Les colonnes de chaque ligne sont disponibles sous forme de jetons {{row.column}}.
  • Filtre d’inducteur (facultatif) : une clause SQL WHERE qui limite les lignes utilisées.
  • Colonnes clés (facultatif) : colonnes pilotes, séparées par des virgules, à reporter sur chaque ligne de sortie, afin que les résultats se rejoignent avec la table pilote.
  • Limite de lignes et Simultanéité : le nombre maximal de lignes à traiter et le nombre de requêtes exécutées en même temps.
  • Req/s max. (facultatif) : plafonne la vitesse de démarrage des requêtes sur tous les workers afin qu’une rafale ne déclenche pas la limite de débit de l’API (0 = aucune limite). La valeur peut être une fraction : 0,5 démarre une requête toutes les deux secondes. Une valeur supérieure à 1000 s’exécute comme 1000 avec un avertissement. Ce paramètre est indépendant de Simultanéité : la simultanéité borne le nombre de requêtes exécutées en même temps, tandis que Req/s max. règle la fréquence de démarrage d’une nouvelle requête.
  • Add Idempotency-Key header (facultatif) : pour une requête POST, PUT ou PATCH unique (sans pagination) par ligne, envoie un en-tête Idempotency-Key stable dérivé de chaque ligne, afin que la réexécution de l’étape ne crée pas d’enregistrements en double sur une API compatible avec l’idempotence (la même ligne envoie toujours la même clé, donc l’API dédoublonne la répétition). Il est ignoré, avec un avertissement, pour GET/HEAD/DELETE ou lorsqu’un mode de pagination est activé. Une requête qui définit déjà son propre Idempotency-Key le conserve.
  • Réponse : la manière dont chaque réponse devient des lignes. Enregistrements analysés (par défaut) écrit chaque enregistrement de réponse sous forme de ligne. Texte (une ligne par requête) écrit une ligne par requête avec les colonnes DownloadData et DownloadHeaders ; une requête en échec est abandonnée. Texte brut, erreurs en lignes écrit aussi une ligne par requête, mais conserve le corps exactement tel que le serveur l’a envoyé, ajoute une colonne DownloadStatus et conserve une erreur HTTP ou de transport sous forme de ligne avec son corps d’erreur et son statut. Les identifiants sont masqués dans le corps, les en-têtes et le texte d’erreur de chaque ligne brute, et une redirection vers une autre origine n’est pas suivie pour une requête qui transporte des identifiants. La pagination ne s’applique pas aux modes texte. Dans Texte (une ligne par requête), Keep error response (keep_error_response) écrit dans la ligne le corps d’une réponse HTTP 400 ou supérieure comme pour un succès, au lieu de faire échouer la ligne, et Ajouter DownloadStatus, DownloadReason et DownloadUrl à la sortie (response_meta) ajoute les colonnes DownloadStatus, DownloadReason et DownloadUrl contenant le statut, la raison et l’URL finale de la réponse. Les deux sont désactivées par défaut. Le formulaire de l’étape propose l’option Ajouter DownloadStatus, DownloadReason et DownloadUrl à la sortie ; définissez keep_error_response avec un assistant IA ou l’API REST.
  • Continue on error : lorsqu’elle est activée, une ligne qui échoue est enregistrée et l’étape se termine avec un avertissement au lieu de s’interrompre au premier échec. Le journal d’exécution nomme les premières lignes en échec (par leurs colonnes clés) et l’erreur rencontrée par chacune, afin que vous sachiez quelles lignes ont échoué et pourquoi.

Utilisez des jetons {{row.column}} n’importe où dans le point de terminaison, la requête, les en-têtes ou le corps pour substituer les valeurs de cette ligne, par exemple GET /customers/{{row.customer_id}}. Une valeur dans un paramètre de requête est encodée une seule fois en URL, de sorte que le serveur reçoit A 1 et a/b tels que saisis. Les versions antérieures l’encodaient deux fois, et le serveur recevait A%201 et a%2Fb. Si une étape POST, PUT ou PATCH a Add Idempotency-Key header activé et une valeur de ligne qui nécessite un encodage dans sa requête, sa clé change une fois après la mise à niveau, car la requête a changé. Une réexécution à cheval sur la mise à niveau peut envoyer une requête répétée pour chacune de ces lignes. Les valeurs composées uniquement de lettres, de chiffres et de -._~ sont inchangées. Les enregistrements de réponse de chaque ligne sont analysés dans la table cible (avec les éventuelles colonnes clés en préfixe) ; avec Dump raw JSON activé, vous obtenez à la place une ligne par requête.

Le menu Insérer {{row.column}} répertorie les colonnes de la table pilote sélectionnée, ce qui vous permet de déposer un jeton de type {{row.customer_id}} dans le point de terminaison ou le corps (selon le dernier champ modifié) au lieu de saisir les noms de colonnes à la main. Pendant la modification, le formulaire répertorie aussi les jetons {{row.column}} que vous avez utilisés et met en rouge ceux qui ne sont pas une colonne de la table pilote, de sorte que les fautes de frappe sont détectées avant l’exécution de l’étape.

Tester la ligne 1 lit la première ligne pilote (en respectant le filtre d’inducteur), substitue ses valeurs dans le point de terminaison, la requête, les en-têtes et le corps, et envoie cette seule requête, ce qui vous permet de confirmer que l’éventail est correctement câblé avant de l’exécuter sur toutes les lignes. La réponse s’affiche en ligne comme pour Envoyer une requête de test, avec les valeurs de la ligne pilote utilisées. Preview Row 1 résout de même les valeurs {{row.column}} de la première ligne pilote et affiche la requête résolue sans l’envoyer.

L’étape Requête REST s’exécute comme n’importe quelle autre, dans le cadre d’une exécution complète ou seule (consultez Exécuter une seule étape d’un workflow). En mode table, elle écrit la réponse analysée (ou brute) dans la table cible ; en mode variable, elle définit les quatre variables que les étapes ultérieures peuvent lire.