跳到正文
DEV Community· Flux Intelligent·· 15 小時前AI 評分58

n8n 教學:使用 HTTP Request 節點呼叫任意 API(認證、分頁與錯誤處理)

Tutoriel n8n : appeler n'importe quelle API avec le nœud HTTP Request (authentification, pagination et erreurs)

AI 導讀

這篇 n8n 教學示範如何用 HTTP Request 節點呼叫沒有專用節點的 API,並處理認證、分頁和錯誤。文章建議把 API 金鑰存入 credentials,為分頁設定停止條件及最大請求次數,並以重試和錯誤輸出處理失敗。亦可把 API 提供給 AI 智能體作工具使用,但付款、刪除或向客戶發送內容等不可逆操作須先經人工確認。

正文

Tôt ou tard, un workflow n8n doit parler à un service qui n'a pas de nœud dédié : un logiciel de facturation local, l'API d'un transporteur, un ERP maison… La bonne nouvelle, c'est que le nœud HTTP Request couvre presque tous ces cas. Ce tutoriel montre comment l'utiliser proprement : partir de la documentation de l'API, gérer l'authentification sans exposer de clé, récupérer toutes les pages de résultats et réagir correctement aux erreurs. Les libellés exacts peuvent varier selon votre version de n8n ; la logique reste la même.

1. Partir de la documentation (ou d'une commande cURL)

Avant d'ouvrir n8n, notez quatre informations dans la documentation de l'API :

  • l'URL de l'endpoint et la méthode (GET, POST, PATCH…) ;
  • le mode d'authentification (clé dans un en-tête, Bearer token, OAuth2, Basic) ;
  • le format attendu et renvoyé (presque toujours du JSON) ;
  • la façon dont la pagination et les limites de débit fonctionnent.

Astuce : si la documentation fournit un exemple cURL, utilisez l'option Import cURL du nœud HTTP Request. n8n remplit la méthode, l'URL, les en-têtes et le corps à votre place. Retirez ensuite la clé API collée en clair et remplacez-la par un credential (étape suivante).

2. L'authentification sans clé en clair

Ne mettez jamais une clé API directement dans un en-tête ou dans le corps de la requête : elle se retrouverait dans l'export du workflow et dans les captures d'écran. Dans le nœud, choisissez plutôt :

  • Authentication → Predefined Credential Type si n8n connaît déjà le service : vous réutilisez le credential du nœud officiel ;
  • Generic Credential Type sinon, avec le bon type : Header Auth (par exemple Authorization: Bearer ... ou X-API-Key), Basic Auth, Query Auth ou OAuth2.

Le credential est stocké chiffré par n8n et partagé entre les nœuds qui en ont besoin. Si la clé change, vous la modifiez à un seul endroit.

3. Construire la requête

Une requête GET simple pour lister des commandes ressemble à ceci :

  • Method : GET
  • URL : https://api.exemple.com/v1/orders
  • Send Query Parameters : status = paid, updated_since = {{ $now.minus({ days: 1 }).toISO() }}

Pour un POST, activez Send Body, choisissez JSON et construisez le corps à partir des données entrantes :

{
  "client_id": "{{ $json.client_id }}",
  "montant": {{ $json.montant }},
  "reference": "{{ $json.reference }}"
}

Testez d'abord sur un seul élément (épinglez des données d'exemple) avant de lancer le nœud sur une liste entière : chaque élément entrant déclenche une requête.

4. Récupérer toutes les pages

La plupart des API ne renvoient qu'une page à la fois (20, 50 ou 100 résultats). Le nœud HTTP Request propose une option Pagination qui évite de construire une boucle à la main. Trois cas fréquents :

Numéro de page (?page=1, ?page=2…) : mode Update a Parameter in Each Request, paramètre page avec la valeur {{ $pageCount + 1 }}.

Curseur (la réponse contient next_cursor) : même mode, paramètre cursor avec la valeur {{ $response.body.next_cursor }}.

URL suivante (la réponse contient next avec l'URL complète) : mode Response Contains Next URL, avec {{ $response.body.next }}.

Dans tous les cas, définissez une condition d'arrêt claire, par exemple « la réponse est vide » ou {{ !$response.body.next_cursor }}, et un nombre maximum de requêtes. Sans garde-fou, une API mal documentée peut vous faire tourner en boucle. Pensez aussi à l'intervalle entre les requêtes si l'API limite le débit.

5. Gérer les erreurs au lieu de les subir

Par défaut, une réponse 4xx ou 5xx arrête le workflow. C'est rarement ce qu'on veut en production. Quelques réglages utiles :

  • Retry On Fail (dans les paramètres du nœud) : 2 ou 3 tentatives avec une pause, pour les erreurs passagères (5xx, coupure réseau) ;
  • On Error → Continue (using error output) : le nœud gagne une seconde sortie pour les éléments en échec, que vous pouvez journaliser ou envoyer à un humain ;
  • l'option Include Response Headers and Status (dans Response) pour lire le code HTTP et réagir avec un nœud Switch : 404 → « élément introuvable », 401 → « credential expiré, prévenir l'équipe », 429 → « attendre et réessayer ».

Règle simple : une erreur ne doit jamais disparaître en silence. Soit elle est réessayée, soit elle arrive chez quelqu'un qui peut agir.

6. Nettoyer la réponse avant la suite

Les API renvoient souvent bien plus de champs que nécessaire. Juste après le HTTP Request, ajoutez un Split Out si les résultats sont dans un tableau (par exemple data), puis un Edit Fields (Set) pour ne garder que les champs utiles avec des noms clairs. Les nœuds suivants (et un éventuel agent IA) travailleront sur des données propres, plus faciles à lire et moins coûteuses à envoyer à un LLM.

7. Bonus : donner l'API à un agent IA

Une fois la requête au point, vous pouvez l'exposer à un agent IA avec le nœud outil HTTP Request Tool, ou en la plaçant dans un sous-workflow appelé comme outil. Gardez les mêmes réflexes : description précise de ce que fait l'outil, paramètres limités à ce qui est nécessaire, et aucune action irréversible (paiement, suppression, envoi à un client) sans validation humaine.

En résumé

  • partez de la documentation, et de l'Import cURL quand il existe ;
  • les clés vont dans des credentials, jamais en clair ;
  • la pagination intégrée remplace la plupart des boucles, avec une condition d'arrêt et un maximum ;
  • Retry On Fail et la sortie d'erreur évitent les échecs silencieux ;
  • nettoyez la réponse avant de la passer à la suite ou à un agent.

Chez Flux Intelligent, à Casablanca, connecter les outils qu'une PME utilise déjà, même sans intégration officielle, fait partie de presque tous nos projets d'automatisation et d'agents IA. Si vous avez une API à brancher et ne savez pas par où commencer, vous pouvez demander un devis.

來源:DEV Community · dev.to