Intégration des données des services web
Dans une publication précédente, nous avons écrit que chaque tâche d'intégration de données et de reporting doit commencer par une compréhension claire des données sources. En utilisant la vue en grille dans XMLSpy, l'éditeur XML et JSON de référence dans l'industrie, nous avons analysé des données JSON relatives aux prévisions météorologiques pour 5 jours, obtenues à partir d'un service web.
En reprenant le scénario que nous avons présenté précédemment, nous utiliserons MapForce, un outil graphique primé Outil de mappage de données pour la conversion et l'intégration de données, quel que soit le format de départ et d'arrivée, pour transformer les prévisions concernant une série de ports majeurs de transport de marchandises en documents Excel bien structurés. Nous souhaitons mettre en évidence les prévisions de vents forts ou de fortes pluies qui pourraient entraîner des retards en perturbant le fonctionnement des grues chargant et déchargeant les conteneurs, ou en ralentissant l'entrée et la sortie des navires dans les ports.
La requête REST pour les prévisions météorologiques accepte les coordonnées de latitude et de longitude afin de renvoyer une prévision pour les 5 prochains jours pour n'importe quel endroit dans le monde. Une seule configuration MapForce peut gérer plusieurs entrées et sorties, nous allons donc commencer le projet d'intégration des données du service web en créant une liste des ports de marchandises et de leurs coordonnées.
Il est très simple de créer cette liste sous forme de nouveau document JSON dans la vue grille de XMLSpy. Il suffit de saisir les données sans se soucier des caractères spécifiques à la syntaxe JSON. Sur l'image ci-dessous, nous avons cliqué sur l'icône en haut à gauche pour afficher la liste sous forme de tableau :
La vue en grille facilite grandement l'examen et la consultation du contenu des fichiers, contrairement à la vue texte, qui affiche tous les caractères de syntaxe nécessaires dans un fichier JSON valide.
Aperçu de la cartographie des données
Le projet d'intégration de données du service web MapForce prendra la liste des ports comme fichier d'entrée, enverra une requête REST pour chaque ensemble de coordonnées, et convertira les données JSON résultantes pour chaque port en une feuille de calcul Excel.
MapForce utilise des fichiers de schéma JSON, conformément aux spécifications de json-schema.org, pour modéliser les structures de données JSON utilisées pour la transformation. MapForce peut générer automatiquement un schéma JSON à partir d'un exemple de données JSON. Cela fonctionnera parfaitement pour le fichier unique port-list.json.
Nous avons également besoin d'un schéma JSON pour structurer les données renvoyées par le service web, ce qui est un peu plus complexe. Nous ne disposons pas d'un seul fichier .json contenant toutes les variations possibles des données obligatoires et facultatives dans la réponse.
Heureusement, XMLSpy peut générer un schéma JSON à partir de plusieurs documents d'exemple regroupés dans un dossier de projet XMLSpy.
En ouvrant le schéma résultant dans la vue JSON Schema, on constate que l'objet "pluie" est facultatif. Cela est dû au fait qu'au moins un des fichiers d'instances de prévisions ne prévoyait aucune pluie pendant toute la période de 5 jours, ce qui explique pourquoi aucun objet "pluie" n'a été inclus dans la réponse.
Nous pouvons utiliser ce schéma pour décrire les données de la réponse REST dans la configuration.
Sur l'image ci-dessous, nous avons commencé à établir la correspondance des données en intégrant le fichier "post-list.json" et un nouveau service web. Nous avons ajouté l'URL REST et nous avons défini les coordonnées de latitude et de longitude comme paramètres d'entrée pour construire la requête. Pour l'instant, le corps de la réponse ne possède pas de structure définie.
Nous pouvons cliquer sur le corps du document pour ouvrir la boîte de dialogue "Structure de la réponse" et y affecter le schéma que nous avons généré dans XMLSpy
Une fois le schéma attribué, tous les éléments du corps du document sont disponibles pour être mappés
Maintenant, nous pouvons ajouter le fichier Excel cible. On nous a fourni une feuille de calcul exemple à utiliser comme modèle, avec quelques styles de cellules et des graphiques, ainsi que des données fictives :
Nous pouvons ajouter cette feuille de calcul à la configuration de l'intégration des données du service web, en la définissant comme la destination, mais nous devons encore identifier les cellules qui recevront les données
En cliquant sur le bouton situé à droite de l'entrée "Lignes 1, n=dyn", la fenêtre "Sélectionner la plage" s'ouvre. La ligne 10 contient les en-têtes de colonnes pour les données, nous voulons donc mapper le tableau principal à partir de la ligne 11 dans les colonnes A à K. Les colonnes ont des types de données différents, qui correspondent principalement à des types texte ou numériques dans la source JSON, et à des types de format dans Excel. La fenêtre "Sélectionner la plage" nous permet de définir précisément les cibles et les types de données :
L'identification des noms de colonnes dans la boîte de dialogue "Sélectionner la plage" permet de les ajouter en tant que libellés dans la correspondance de sortie. Ensuite, nous pouvons définir la logique permettant d'associer chaque prévision à un fichier Excel distinct, comme illustré ci-dessous :
Le nom de fichier, situé tout en haut de la feuille Excel cible, est défini sur
Nous devons également nous assurer que le tableau de données principal de chaque fichier commence à la ligne 11. Pour ce faire, nous avons lié l'objet de niveau supérieur du tableau à la cible aux lignes 10, avec n=dynamique, et nous avons utilisé une fonction de numérotation automatique pour réinitialiser la ligne de départ à chaque fois que le nom du fichier change.
Chaque objet de liste dans la réponse sera associé à une nouvelle ligne dans la feuille de calcul Excel. Nous pouvons maintenant associer les éléments individuels de la réponse aux colonnes de cette ligne. Sur l'image ci-dessous, nous avons associé tous les éléments qui ne nécessitent aucune transformation supplémentaire.
Pour les éléments directement liés, les types de données dans la réponse JSON correspondent directement aux types que nous avons spécifiés pour les colonnes dans la feuille de calcul. La valeur "Temp" dans les données JSON sources est numérique, et la colonne E dans la cible est également numérique. Le type de données pour la description dans la source est une chaîne de caractères, et la colonne B dans la cible est également une chaîne de caractères, et ainsi de suite.
Dans le schéma JSON de la réponse, nous avons constaté que l'objet "rain" (pluie) était facultatif. Si cet objet n'existe pas, nous souhaitons le remplacer par la valeur zéro. Cela peut être facilement réalisé en construisant une expression qui combine les fonctions "exists" (existe) et "if-else" (si-alors) :
Une limitation du format de données JSON est qu'il ne prend en charge que deux types de données : les chaînes de caractères et les nombres. Les types de données tels que les entiers et les dates, ou les formats spéciaux d'Excel comme les pourcentages et les données comptables, ne sont pas définis dans JSON. MapForce intègre des fonctions qui permettent de convertir facilement les données sources vers les types de données souhaités dans la structure de données cible. C'est ainsi que nous pouvons créer le format de date et heure que nous voulons dans la colonne A du tableau Excel.
L'élément "main.dt_text" dans les données JSON représente la date et l'heure sous forme de chaîne de caractères, par exemple : 2020-05-09 06:00:00. MapForce dispose d'une fonction "parse-dateTime" qui prend en entrée la chaîne de caractères et un modèle de format, et qui renvoie une valeur de date et d'heure. Cependant, il y a une complication supplémentaire : la chaîne "dt-txt" est exprimée dans le fuseau horaire GMT, et non dans l'heure locale de la ville pour laquelle la prévision est établie. Le décalage horaire local est indiqué dans l'élément "city.timezone" sous forme de secondes positives ou négatives.
Afin de maintenir la vue principale de cartographie simple, nous avons créé une fonction utilisateur appelée "calc-local-time". Cette fonction prend une chaîne de caractères et un décalage, et calcule l'heure locale. Cette fonction utilisateur est utilisée de la même manière qu'une fonction intégrée :
La dernière étape pour finaliser la correspondance des données de l'intégration du service web consiste à combiner les noms des villes et des pays, puis à les ajouter à la ligne 1, colonne C
Voici une vue d'ensemble complète de la cartographie finale :
Pour obtenir les documents Excel correctement formatés pour chaque ville, nous avons besoin d'un fichier Excel existant, déjà formaté, qui corresponde à chaque nom de fichier cible. Un fichier batch est un moyen rapide de créer les fichiers originaux en copiant de manière répétée le fichier Excel de référence, avec ses styles et ses formules.
Résultats de l'intégration des données des services web
En cliquant sur le bouton "Sortie" situé en bas à gauche de la fenêtre de mappage, le processus de mappage est exécuté et les fichiers de sortie sont générés. Si Excel est installé sur la station de travail, l'aperçu du fichier Excel généré s'affiche dans la fenêtre "Sortie" :
La date, l'heure et les conditions météorologiques actuelles, ainsi que les résumés textuels situés à côté du graphique des précipitations, sont générés par des formules dans la feuille de calcul Excel. Les neuf fichiers de sortie ont été créés et nous pouvons sélectionner et prévisualiser n'importe quel fichier individuellement. Ci-dessous, vous trouverez la liste déroulante de sélection des fichiers et le septième fichier, qui contient les prévisions pour Seattle :
Les fonctionnalités d'Excel sont disponibles dans la fenêtre de prévisualisation. Par exemple, cette feuille de calcul utilise une fonction de défilement en écran divisé, avec une partie supérieure figée. Nous pouvons faire défiler la table de données principale jusqu'en bas pour voir précisément la quantité de précipitations prévue dans la dernière prévision. Notez les numéros de ligne sur le côté gauche :
Si le résultat est satisfaisant, nous pouvons enregistrer un ou tous les fichiers générés :
Données intermédiaires
MapForce est conçu pour optimiser la conversion des données. Nous n'avons jamais eu à enregistrer, gérer ou manipuler explicitement les données JSON intermédiaires provenant de la réponse REST. L'exécution de cette transformation de données pour l'intégration de services web ne sauvegarde pas les données intermédiaires.
Si nous souhaitons ou avons besoin de conserver les données de la réponse JSON en plus des feuilles de calcul Excel finales, MapForce offre plusieurs options. Une possibilité consiste à créer une transformation en chaîne qui enregistre les données de la réponse sous forme de fichier JSON intermédiaire, en utilisant le même schéma que la réponse. Ensuite, nous pourrions mapper ce fichier JSON pour générer la sortie Excel. Une transformation en chaîne vous permet de prévisualiser et d'enregistrer les fichiers intermédiaires ainsi que le résultat final. L'image ci-dessous montre la liste des fichiers de sortie générée par une transformation en chaîne, avec l'un des fichiers JSON affiché en mode texte en arrière-plan :
Intégration automatisée des données des services web
Notre scénario de flux de travail nécessiterait la mise à jour des prévisions quotidiennement. Nous pouvons enregistrer la configuration sous forme de fichier d'exécution pour MapForce Server, afin de permettre un traitement automatisé par MapForce Server, ou bien la déployer directement sur FlowForce Server pour générer de nouvelles prévisions selon un calendrier automatisé. Une tâche FlowForce Server peut combiner des tâches d'intégration de données avec de multiples actions, notamment des actions système comme le déplacement de fichiers ou l'envoi d'e-mails, ou une tâche FlowForce Server peut exécuter des flux de travail complexes qui peuvent transmettre des résultats et des paramètres pour déclencher d'autres tâches.
Regardez une courte démonstration vidéo de MapForce, ou téléchargez une version d'essai gratuite qui comprend des tutoriels, une aide et de nombreux exemples pour vous aider à démarrer votre propre projet d'intégration de données JSON et de services web, ou pour répondre à d'autres besoins de mappage, de conversion et de transformation de données !