Prérequis

Avant de commencer, assurez-vous d’être connecté à la plateforme Ferronext.

Pour accéder à l’interface de déploiement d’une source de données :

1. Rendez-vous dans la section Sources de données depuis le menu de navigation latéral.
2. Sélectionnez la source pour laquelle vous souhaitez créer un déploiement.
3. Deux accès sont possibles :
   • Cliquez sur l’onglet Déploiements, puis sur le bouton + pour créer un nouveau déploiement.
   • Cliquez sur le bouton ⋯, puis sélectionnez Configurer un déploiement dans le menu déroulant.
4. Dans la section Connectivité, sélectionnez le protocole API REST.

Configuration d'un déploiement API REST

Démonstration vidéo

La vidéo ci-dessus vous montre rapidement les étapes de configuration. Vous retrouverez ci-dessous une explication plus détaillée, illustrée par des captures d’écran.

Interface de configuration

Le formulaire de configuration d'un déploiement API REST comporte plusieurs sections à renseigner.

Une API REST (Representational State Transfer) est un moyen standardisé d’échanger des données entre systèmes informatiques via HTTP. Elle permet à une application telle que Ferronext de consommer des données depuis un service externe de façon simple et flexible.

• Les données sont accessibles via une URL.
• Les requêtes se font avec des méthodes standards comme GET (lecture) ou POST (envoi de données).
• Les réponses sont généralement fournies au format JSON, mais peuvent aussi être d’autres formats.

Exemple : une API REST peut fournir en temps réel les positions des trains, l’état des capteurs d’infrastructure, ou encore les horaires planifiés.

Connectivité

1. Protocole : Sélectionnez API REST.
2. Type de connexion : Choix possible GET ou POST.
   • Si GET → récupération simple de données via l’URL.
   • Si POST → des champs supplémentaires apparaissent :
     • Type : choisir entre JSON ou x-www-form-urlencoded.
       • JSON Ce format est le plus courant dans les API modernes. Vous pouvez rédiger directement un body sous forme de document JSON.
       • x-www-form-urlencoded Ce format encode les données comme si elles venaient d’un formulaire HTML classique. Chaque paire clé = valeur est envoyée dans le corps de la requête. Dans l’interface, vous pouvez utiliser le bouton + Ajouter pour définir vos champs sous forme de paires clé/valeur, comme dans un formulaire web.
3. URL de l’API : Indiquez l’adresse complète du service externe.
4. En-têtes (Headers) : Possibilité d’ajouter un ou plusieurs en-têtes HTTP :
   • Avec + Ajouter → vous définissez le nom et la valeur du header.
   • Avec - → vous supprimez un en-tête.
5. Méthode d’authentification : Plusieurs options sont possibles :
   • Utilisateur / Mot de passe Cette méthode repose sur un couple d’identifiants classiques. Vous devez renseigner :
     • Utilisateur : identifiant de connexion
     • Mot de passe : secret associé à l’utilisateur
   • Clé API Une clé unique est générée par le système et doit être transmise lors de chaque requête. Vous devez renseigner :
     • Clé API : clé secrete.
   • Token Cette méthode repose sur un jeton d’authentification. Vous devez renseigner :
     • Token : un jeton d’authentification Ce mode est recommandé pour des environnements sécurisés, car le jeton peut avoir une durée de vie limitée et être renouvelé automatiquement.
   • Aucune (API publique) Dans ce cas, aucune information d’identification n’est requise. Vous pouvez consommer l’API directement sans fournir de clé ou de jeton. Ce mode est adapté pour des ressources publiques ou de la donnée ouverte, mais doit être utilisé avec prudence afin d’éviter les abus.

Correspondances

La correspondance relie les champs de la réponse de l’API aux variables définies dans votre source Ferronext. C’est une étape critique pour garantir l’intégration correcte des données dans le modèle de votre source.

Vous devez d’abord choisir le type de réponse : JSON ou URL.

JSON

info

Un JSONPath est une notation qui permet de parcourir un document JSON afin d’en extraire certaines valeurs. Exemple : $.trains[0].id permet de récupérer l’identifiant du premier train d’une liste.

1. Sélection des variables dans la source de donnée Choisissez les variables cibles.
2. Association des champs À partir de la réponse de l’API, vous devez écrire les JSONPath correspondant pour relier chaque champ à une variable.

URL

Si la réponse est un fichier externe, vous devez choisir le type parmi : CSV, XLSX, XML, JSON, ou Texte.

La plateforme analysera automatiquement le fichier et proposera une correspondance des champs avec les variables de la source.

Paramètres de déploiement

Les paramètres définissent quand et comment le module extrait la donnée.

1. Type de déclenchement

• Unique : le déploiement s'exécute une seule fois (ex. extraction historique ponctuelle). Utilisation : backfill ponctuel, récupération d’un dump. Vous devez préciser la date/heure d’exécution.

• Régulier : le déploiement s'exécute périodiquement selon une fréquence. Choix du rythme (exemples disponibles) : 1 minute, 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 heure, 6 heures, 1 jour.

info

Pour des extraits fréquents, privilégiez des requêtes incrémentales (uniquement les nouvelles lignes après la dernière date traitée).

2. Début du déploiement (date de démarrage)

• Date/heure à laquelle la première exécution aura lieu.
• Pour un déclenchement régulier, c’est la première exécution de la série.

3. Description

• Texte libre pour documenter l’objectif du déploiement. Exemple : Récupération des relevés de température - ligne A.

Résumé

Avant d’enregistrer le déploiement, la page propose un récapitulatif de toutes les informations :

• Paramètres de connectivité.
• Correspondances champs → variables.
• Filtres appliqués.
• Paramètres de déclenchement (type, rythme, date de début).