Étape Requête REST

Description

L’étape Requête REST appelle une API REST comme une étape d’un workflow. C’est une étape unique, de type 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, lancez 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 sur le code d’état ou lire une valeur du 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 lorsque cela vous est proposé pour récupérer les paramètres de requête non enregistrés.

Avant de commencer

Vous aurez généralement besoin d’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. Voir Connexions REST.

Ajouter une étape Requête REST

Ouvrez le workflow et ajoutez une étape à l’endroit voulu.
Choisissez Requête REST (unifiée) comme type d’étape (parmi 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.

Construire la requête

Dans l’onglet Requête :

Source du point de terminaison

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

Manuel : 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 choisie, pour ne pas la répéter à chaque étape. Voir Réutiliser la définition d’API d’une connexion plus bas.
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’en a aucun 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 catalogue volumineux est facile à restreindre : 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 pendant le filtrage) et la date 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

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, il n’est donc pas nécessaire 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, collez-le donc de nouveau si vous rouvrez l’étape et souhaitez 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 lorsque cela se produit.

Vous pouvez aussi déposer un fichier .json sur le sélecteur de source. L’étape vérifie 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 ; chaque source dispose d’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

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

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

Choisissez la connexion sous Connexion.
Définissez Source du point de terminaison sur À partir de la définition d’API de la connexion.
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.

Résumé de la connexion et environnement

Sous le sélecteur 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, méthode et point de terminaison

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, paramètres de requête et corps

En-têtes et Paramètres de requête sont des tables modifiables de lignes nom/valeur, chacune avec un commutateur 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 brut) dans un éditeur de code.

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

Pendant que vous modifiez, 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, ce qui ferait perdre une valeur.
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 avec un schéma mal saisi, une double barre oblique dans le chemin, une barre oblique finale ou des espaces parasites.

Substitution de variables

Partout 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 tables d’en-têtes et de requête, et l’éditeur de corps, pour que les substitutions soient faciles à repérer avant de tester ou d’enregistrer.

Seules les doubles accolades sont substituées : un { ou un } isolé dans un corps JSON reste exactement tel qu’écrit, 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, afin qu’une faute de frappe apparaisse immédiatement.

Lorsque le workflow est démarré par un capteur ou un webhook, quatre variables de déclenchement sont également 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 accéder aux champs imbriqués). Lors d’une exécution manuelle ou planifiée, elles se résolvent en chaîne vide.

Tester la requête

Envoyer une requête de test lance 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 affiche l’état HTTP et le temps de réponse, et un minuteur s’incrémente pendant que la requête est en cours. (Cela n’envoie qu’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), pour 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 lancé.
Copier en curl copie dans le presse-papiers une commande curl équivalente, pour le partage ou le débogage (les secrets sont 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 relancer. 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’éclatement, utilisez Tester la ligne 1 pour tester la première ligne d’inducteur avant d’enregistrer.

Acheminer la réponse

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

Table (par défaut)

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 champs de réponse pilotent la pagination ; ils ne sont disponibles que lorsqu’un mode de pagination est choisi. Le choix d’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 offset et limit, et continue la lecture tant que `has_more` vaut vrai dans la réponse.
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 qui n’a pas 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 besoin d’aucun 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 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). Un POST, PUT ou PATCH n’est retenté qu’après une réponse de limitation de débit (HTTP 429), qui indique que le serveur n’a rien fait de la requête, et jamais après une erreur serveur, de sorte qu’un corps de requête non idempotent n’est jamais envoyé deux fois alors que le serveur a peut-être déjà agi ; 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 au préalable lorsque la méthode n’est ni GET, ni HEAD, ni 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.

Variables du workflow

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

Variable	Contenu
`{prefix}_status`	Code d’état 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 « lancer une requête, puis se brancher sur le résultat ».

Envoyer une requête par ligne de table

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 un 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 d’inducteurs :

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 de l’inducteur, séparées par des virgules, à reporter sur chaque ligne de sortie, afin que les résultats se rejoignent avec l’inducteur.
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 pour qu’une rafale ne déclenche pas la limite de débit de l’API (0 = aucune limite). La valeur peut être fractionnaire : 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, de sorte que la réexécution de l’étape ne crée pas d’enregistrements en double sur une API qui gère l’idempotence (la même ligne envoie toujours la même clé, et l’API déduplique donc 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 façon dont chaque réponse devient des lignes. Enregistrements analysés (par défaut) écrit chaque enregistrement de réponse comme une 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 également 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 état. 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 l’état, le motif et l’URL finale de la réponse. Les deux sont désactivés 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 : lorsque cette option est activée, une ligne en échec est consigné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 pour l’URL ; le serveur reçoit donc 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 nécessitant 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 ajoutées en tête) ; avec Extraire le JSON brut activé, vous obtenez à la place une ligne par requête.

Le menu Insérer {{row.column}} liste les colonnes de la table d’inducteurs sélectionnée, afin que vous puissiez placer un jeton du type {{row.customer_id}} dans le point de terminaison ou le corps (le champ que vous avez modifié en dernier) au lieu de saisir les noms de colonnes à la main. Pendant que vous modifiez, le formulaire liste aussi les jetons {{row.column}} que vous avez utilisés et met en rouge ceux qui ne correspondent pas à une colonne de la table d’inducteurs, pour que les fautes de frappe soient détectées avant l’exécution de l’étape.

Tester la ligne 1 lit la première ligne de l’inducteur (en tenant compte du filtre d’inducteur), substitue ses valeurs dans le point de terminaison, la requête, les en-têtes et le corps, puis lance cette unique requête, afin que vous puissiez confirmer que l’éclatement est correctement câblé avant de l’exécuter sur chaque ligne. La réponse s’affiche directement, comme pour Envoyer une requête de test, accompagnée des valeurs de la ligne d’inducteur utilisées. Preview Row 1 résout de même les valeurs {{row.column}} de la première ligne d’inducteur et affiche la requête résolue sans la lancer.

Exécuter l’étape

L’étape Requête REST s’exécute comme n’importe quelle autre, dans le cadre d’une exécution complète ou seule (voir 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 suivantes pourront lire.

Étapes suivantes

Référence de l’étape Requête REST : liste concise des champs
Gérer les variables de workflow : lire et définir des variables d’une étape à l’autre
Connexions REST : configurer des connexions d’API authentifiées