Exemple : Écrire les données dans les Protocol Buffers
Cet exemple vous montre comment écrire des données dans les fichiers binaires encodés dans le format Protocol Buffers. Dans cette démonstration, les données de source proviennent d'une base de données SQLite (Nanonull.sqlite) ; néanmoins, vous pouvez utiliser une approche semblable pour extraire des données depuis d'autres formats pris en charge par MapForce, comme XML, EDI, JSON, et autre.
La base de données de démonstration de source stocke des données concernant des personnes, leurs adresses et les produits qu'ils ont commandé depuis un magasin. Les exigences commerciales ont pour objectif d'extraire des informations de commande depuis la base de données et de générer plusieurs fichiers binaires dans le format Protocol Buffers. Un fichier binaire portant l'extension .dat doit être généré pour chaque commande. Le nom de fichier généré doit contenir l’ID unique de la commande, par exemple, Order1.dat, Order2.dat, etc. Aussi, chaque fichier binaire doit inclure l’ID de la commande, le nom de la personne et l’adresse e-mail, la date, et l’information relative à l’envoi. Plus particulièrement, le fichier .proto qui décrit la structure d'une commande ressemble à l'exemple suivant :
syntax="proto3";
package mapforce.demo;
message Order { int32 id = 1; string name = 2; string email = 3; DateType entry_date = 4; // An order can have multiple addresses (shipping, billing) repeated AddressType address = 5; }
message DateType { // Must be from 1 to 9999 int32 year = 1; // Must be from 1 to 12 int32 month = 2; // Must be from 1 to 31, and valid for the year and month int32 day = 3; }
message AddressType { string city = 1; string street = 2; int32 number = 3; bool shipping = 5; bool billing = 4; } |
orders.proto
La base de données Nanonull.sqlite et le fichier de commande orders.proto sont disponibles dans le répertoire suivant : <Documents>\Altova\MapForce2025\MapForceExamples\Tutorial\. Le fichier de design de mappage qui effectue la transformation est appelé GenerateOrders.mfd et est disponible dans le même répertoire. Vous pouvez ouvrir le mappage et l'exécuter directement, ou suivre les étapes ci-dessous pour le créer de zéro.
GenerateOrders.mfd
Comme illustré ci-dessus, le mappage consiste en un composant de source (la base de données SQLite) et un composant cible (le composant binaire). Dans la base de données de source, la table principale pertinente pour ce mappage est orders.
Veuillez noter que la table users est imbriquée sous la table orders, parce que MapForce a détecté automatiquement une relation de clé étrangère entre ces deux tables. De même, les adresses de table sont imbriquées sous les utilisateurs. Toutes les connexions tracées depuis ces tables imbriquées permettent d'assurer que les relations clé sont préservées par le mappage. Pour plus d'informations, voir Gérer des relations de base de données.
Du côté cible, l’item File<dynamic> illustre que le composant binaire est défini pour générer les fichiers d’instance de manière dynamique, basé sur l’information reçue depuis le mappage. Pour qu'un composant de cible génère des fichiers de manière dynamique, cliquer sur la touche 
et choisir Utiliser des noms de fichier dynamiques fournis par le mappage depuis le menu contextuel. Pour plus d'informations concernant les noms de fichier dynamiques, voir Traiter plusieurs fichiers d'entrée ou de sortie dynamiquement.
Dans ce mappage, pour chaque id dans la table de base de données orders, un nouveau fichier sera généré, comme indiqué par la connexion vers l'item File: Item <dynamic>. Le nom de chaque fichier généré est créé avec l'aide de la première fonction concat. Cette fonction réunit le string "Order" avec l'ID unique de la commande provenant de la base de données et portant l'extension ".dat". Pour cette raison, les fichiers générés seront dotés de noms tels Order1.dat, Order2.dat, etc.
La fonction concat est aussi appelée une deuxième fois par le mappage. Cette fois elle retourne le nom de la personne, en concaténant le prénom et le nom de famille, et en insérant un caractère d'espace entre les deux.
Enfin, le composant "GetDate" au centre est une fonction définie par l'utilisateur qui remplit les champs de date dans le fichier binaire. Cette fonction prend comme entrée une date exprimée en tant que string, la parse et retourne l'année, le mois et le jour séparément en tant que valeurs d'entier. Cette conversion est requise pour accommoder le format de date tel qu’il a été défini dans le fichier .proto. Si vous double-cliquez sur la barre de titre de la fonction dans le mappage, vous pouvez consulter ou modifier la définition de cette fonction.
"GetDate" fonction définie par l'utilisateur
Comme illustré ci-dessus, la fonction définie par l'utilisateur "GetDate" parse la valeur d'entrée avec l'aide de la fonction intégrée parse-dateTime. Le masque [Y]-[M]-[D] [H]:[m]:[s] correspond au format de date tel qu’il est stocké dans la base de données, par exemple 2017-10-19 08:09:54. Pour plus d'informations concernant les masques de format, veuillez vous référer à la description de la fonction parse-dateTime. Ensuite, plusieurs fonction built-in diverses sont appelées pour extraire et retourner les parties de date importantes depuis la date parsée.
Créer le mappage
Pour créer le mappage ci-dessus (ou un mappage semblable) à partir de zéro, suivre les étapes suivantes :
1.Insérer la base de données source.
2.Insérer le fichier .proto cible, voir Ajouter des fichiers binaires dans le mappage.
3.Configurer le composant cible pour générer des noms de fichier dynamiquement, lorsque le mappage est exécuté. Pour ce faire, cliquer sur la touche et choisir Utiliser les noms de fichier dynamique fournis par le mappage depuis le menu contextuel. Ensuite, connecter l'item File<dynamic> à une entrée qui fournit le nom de fichier. Dans cet exemple, le nom de fichier est produit avec l'aide de la fonction concat, comme mentionné ci-dessus. Pour plus d'informations à propos des noms de fichier dynamiques, voir Traiter plusieurs fichiers d'entrée et de sortie dynamiquement.
4.En option, ajouter des fonctions built-in MapForce et connecter leurs entrées. Dans cet exemple, la fonction concat est utilisée dans deux occurrences. Pour plus d’informations, voir Ajouter une fonction au mappage. Veuillez noter que, lorsque vous appelez des fonctions built-in comme concat, il est probable que certaines de ces données d'entrée proviendront des constantes de string. Pour plus d'informations concernant l'ajout de ces constantes, voir Ajouter une constante au mappage.
5.En option, ajouter toutes les fonctions définies par l'utilisateur le cas échéant. Celles-ci vous aident à abstraire certains des détails du mappage pour vous concentrer sur l'ensemble du projet. Dans cet exemple, la fonction définie par l'utilisateur "GetDate" convertit un string en parties de date, comme évoqué plus haut, et sa logique de mise en place est dissimulée du mappage principal. Pour plus d’information sur la création de fonctions personnalisées, voir Fonctions définies par l'utilisateur.
Si vous ne connaissez pas encore MapForce, voir le chapitre Tutoriels pour consulter des exemples simples étape par étape.
Exécuter le mappage
Comme souligné dans les exigences commerciales au début de cet exemple, le mappage est censé produire plusieurs fichiers .dat. Pour consulter les fichiers générés, cliquer sur l'onglet Sortie.
Comme illustré ci-dessus, le volet Sortie affiche tous les fichiers générés, et vous pouvez les parcourir en cliquant sur les touches de direction ou en choisissant un item depuis la liste. Pour enregistrer la sortie générée, procéder comme suit :
•Dans le menu Sortie, cliquer sur Enregistrer les fichiers de sortie (
).
•Cliquez sur le bouton de la barre d’outils Enregistrer la sortie générée ().
Lorsque vous prévisualisez les fichiers binaires de sortie générés avec MapForce, leur structure est affichée en tant que JSON puisque ce format est lisible à l’œil par opposition au format binaire. Visualiser la sortie en tant que JSON est fait pour vous aider à tester le mappage. Lorsque vous enregistrez le fichier de sortie, il sera toutefois enregistré en tant que fichier binaire. |
Automatisation avec MapForce Server
Si vous avez mis sous licence MapForce Server, vous pouvez aussi exécuter le mappage dans la ligne de commande, sur un appareil Linux, macOS, ou Windows, comme suit :
1.Compiler le mappage dans un fichier d'exécution de MapForce Server (.mfx) avec la commande de menu Fichier | Compiler sur le fichier d'exécution MapForce Server, voir aussi Compiler des mappages dans les fichiers d'exécution MapForce Server.
2.Copier le fichier .mfx dans l'appareil du serveur.
3.Puisque ce mappage lit des données depuis un fichier SQLite, copier le fichier de base de données Nanonull.sqlite dans le même répertoire que le fichier .mfx sur le serveur. Pour d'autres types de base de données, voir des Mappage de base de données dans plusieurs environnements d'exécution.
4.Exécuter le serveur MapForce avec la commande ci-dessous.
mapforceserver run GenerateOrders.mfx |
Notes :
•mapforceserver est le chemin vers le programme d'exécution de MapForce Server, tel qu'applicable pour votre système d'exploitation.
•Modifier le chemin vers le fichier .mfx, ou copier le .mfx vers le même dossier que le programme d'exécution.
Dans l’exécution de serveur, vous pouvez aussi exécuter des mappages en tant qu’appel API, ou en tant que tâches de FlowForce Server, soit sur demande ou sur une base récurrente. Pour plus d'informations, voir Automatisation avec MapForce Server.