Appeler une API depuis une automatisation

Utilise une étape HTTP quand une automatisation a besoin d’une API externe qui n’a pas son propre connector. http.get lit, et http.send écrit avec POST, PUT, PATCH ou DELETE. Un envoi modifie des données hors de Tale, une exécution en direct demande donc d’abord une approbation, comme pour toute écriture. Une exécution de test n’envoie jamais rien : elle répond avec un mock.

Lire depuis une API

nodes:
  - id: orders
    type: http.get
    credential: Shop API
    input:
      url: /orders
      query: { status: open }

L’étape renvoie { status, ok, headers, body }. body contient le JSON analysé ou le texte, et null pour une réponse vide. headers garde content-type, etag, last-modified, location, link, retry-after et les en-têtes x-ratelimit-, et écarte les autres. Un statut hors de 200–299 fait échouer l’étape, sauf si okStatuses le cite ; ok vaut alors false, et une étape suivante décide quoi faire de la réponse.

Envoyer à une API

http.send prend les mêmes entrées et trois de plus : method (POST, PUT, PATCH ou DELETE, obligatoire), body et contentType. Une valeur JSON dans body est envoyée en JSON. Une chaîne est envoyée telle quelle, avec contentType, ou text/plain sans.

nodes:
  - id: create_order
    type: http.send
    credential: Shop API
    input:
      url: /orders
      method: POST
      body:
        item: '{{ input.item }}'
        quantity: 2

Se connecter avec des identifiants

Dans Paramètres › Connectors, ajoute des identifiants à HTTP. Choisis comment ils se connectent : avec un jeton Bearer, une clé d’API envoyée dans un en-tête, ou un nom d’utilisateur et un mot de passe. Saisis leur URL de base, comme https://api.example.com/v2 ; pour une clé d’API, En-tête de la clé d’API nomme l’en-tête, X-Api-Key par défaut. Donne un nom aux identifiants, et indique-le dans le champ credential de l’étape.

Une étape avec des identifiants reste sous l’URL de base. Un chemin est placé dessous, une adresse complète doit commencer par elle, et une redirection ne peut pas la quitter. Seuls les identifiants signent la requête. Là où une réponse renverrait une de leurs valeurs, Tale la remplace par [redacted], si bien qu’elle n’atteint jamais l’enregistrement d’une exécution.

Une étape sans identifiants n’en porte aucun, jamais ceux de l’organisation par défaut, et n’appelle que des adresses https:// publiques.

Ce que Tale refuse

• Une adresse de réseau privé ou une adresse de métadonnées d’un cloud, avec ou sans identifiants.
• Une adresse http:// simple. L’éditeur la signale avant l’enregistrement.
• Un nom d’utilisateur ou un mot de passe écrit dans l’adresse, ou des identifiants dans un de ses paramètres de requête : l’éditeur refuse l’enregistrement. Enregistre plutôt les identifiants dans Paramètres › Connectors.
• Un en-tête Authorization ou Cookie défini par l’étape. L’éditeur le refuse aussi.
• Une réponse de plus de 1 Mo.

Les étapes HTTP d’une organisation font au plus 120 appels par minute sur tout le déploiement, et 10 à la fois sur un serveur. Un appel au-delà du budget de la minute échoue ; un appel au-delà du nombre simultané attend une place libre aussi longtemps que son timeoutMs le permet.

Quand une étape échoue

La page de l’exécution dit pourquoi une étape HTTP a échoué et comment corriger le problème. Les journaux d’exécution expliquent comment lire l’échec.