Exemple : Lire des données depuis les Protocol Buffers
Cet exemple vous montre comment lire les données depuis un fichier binaire encodé en format Protocol Buffers. Le fichier binaire de source est disponible sous le chemin suivant : <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\assets.bin. Le fichier .proto décrivant le fichier binaire est disponible dans le même répertoire et ressemble à l'exemple suivant :
syntax="proto3";
package mapforce.demo;
message CulturalAssets { repeated PaintingType painting = 1; }
message PaintingType { string name = 1; string period = 2; float height = 3; // in cm float width = 4; // in cm string remarks = 5; LocationEnum location = 6;
enum LocationEnum { UNKNOWN = 0; MUSEUM = 1; TEMPLE = 2; PRIVATE = 3; } } |
assets.proto
Le fichier binaire de source contient des informations concernant les différents atouts culturels (dans cet exemple, une collection de tableaux). Comme illustré par le fichier .proto ci-dessus, chaque tableau présente une hauteur et une largeur exprimée en centimètres. Il existe d'autres champs divers qui décrivent un tableau, y compris une énumération qui spécifie son emplacement (musée, collection privée ou temple). L'exigence commerciale est d'extraire cette information dans un fichier de valeurs séparées par des virgules (CSV). De plus, toutes les dimensions des tableaux doivent être converties de centimètres en pouces et doivent être représentées en tant que string unique, dans un format comme par exemple "24 in x 56.8 in".
Le mappage qui extrait des données conformément aux exigences ci-dessus et qui produit la sortie désirée comme illustré ci-dessous. Ce mappage est disponible dans le répertoire suivant : <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\. Vous pouvez ouvrir le mappage et l'exécuter directement, ou suivre les étapes ci-dessous pour le créer de zéro.
ReadProtocolBuffers.mfd
Comme illustré ci-dessus, le mappage consiste en un composant binaire de source (assets) et un composant cible CSV (PaintingInfo). De plus, il contient les composants intermédiaires suivants :
•Une table value-map responsable de la conversion des valeurs d'énumération comme 0, 1, 2, 3 en une représentation en string lisible pour les humains (par exemple, 0 = UNKNOWN, 1 = MUSEUM, etc.).
•La fonction ConvertCmToInch. Comme suggéré par le titre, il s'agit d'une fonction définie par l'utilisateur qui convertit les centimètres en pouces. Cette fonction est appelée deux fois dans le mappage (respectivement hauteur et largeur).
•La fonction concat. Cette fonction concatène plusieurs valeurs et retourne un string dans le format "# en x # en", où # représente la hauteur et la largeur du tableau (en pouces).
Les étapes suivantes illustrent comment créer le mappage ci-dessus à partir de zéro.
Étape 1 : Ajouter le fichier binaire de source
1.Dans le menu Insérer, cliquer sur Fichier Protocol Buffers et chercher le fichier suivant : <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\assets.proto.
2.Sur invitation, choisir "CulturalAssets" en tant que message root et cliquer sur OK.
3.Double-cliquer sur la barre de titre du nouveau composant. Le dialogue "Paramètres de composant binaire" s'ouvre.
4.Cliquer sur Chercher situé à côté de Fichier binaire entrée, et choisir le fichier suivant : <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\assets.bin.
Voir aussi Ajouter Fichiers binaires dans le mappage.
Étape 2 : Ajouter le composant CSV cible
1.Dans le menu Insérer, cliquez sur Fichier texte.
2.Sélectionnez la case à cocher Use simple processing for standard CSV... et cliquez sur Continue. Le dialogue "Paramètres de composant CSV" s'ouvre.
3.Cliquer plusieurs fois sur la touche Ajouter champ pour créer cinq champs cibles requis pour stocker les données attendues.
4.En option, double-cliquer sur l'en-tête de chaque champ pour lui donner un nom plus parlant.
Pour plus d’information, voir Configurer les options CSV.
Étape 3 : Ajouter une value-map
1.Dans le menu Insérer, cliquer sur Value-Map.
2.Créer une entrée pour chaque enregistrement mappé, comme indiqué ci-dessous.
La condition "Otherwise" gère le cas quand le fichier binaire ne contient aucune valeur pour le champ Location. Dans ces cas, le mappage écrira la valeur "Inconnu" dans la cible au lieu de ne pas produire de résultat. Pour plus d’informations, voire Utiliser des Value-Maps.
Étape 4 : Créer la fonction définie par l'utilisateur
1.Dans le menu Fonction, cliquer sur Créer fonction définie par l'utilisateur et l'appeler "ConvertCmToInch". Ne pas modifier les autres options.
2.Glisser les fonctions built-in divide et round-precision depuis la fenêtre Bibliothèques dans la fenêtre de mappage de la fonction. Voir aussi Ajouter une fonction dans le mappage.
3.Ajouter deux constantes et effectuer toutes les connexions comme illustré ci-dessous, voir aussi Ajouter une constante au mappage. La première constante fournit la constante décimale nécessaire pour convertir des centimètres en pouces conformément à la formule, et la deuxième apporte l'arrondissement.
En principe, la fonction divise la valeur d'entrée par 2.54, puis arrondit le résultat à un chiffre décimal, comme illustré ci-dessous :
Pour éviter des erreurs potentielles, définir le type de données des composants d'entrée et de sortie sur "decimal". Pour consulter ou modifier le type de données, double-cliquer sur la barre de titre du composant, ou cliquer avec la touche de droite sur la barre de titre et sélectionner Propriétés depuis le menu contextuel. |
Une fois que la fonction définie par l'utilisateur, cliquer sur Retourner au mappage principal 
et glisser la fonction depuis la fenêtre Bibliothèques dans le mappage pour l'appeler. Dans cet exemple, il est appelé deux fois. Pour plus d'informations, voir Fonctions définies par l'utilisateur.
Étape 5 : Ajouter la fonction de concaténation
Commencer à saisir "concat" dans la fenêtre Bibliothèques, puis glisser la fonction concat dans le mappage. Pour éviter tous les arguments d'entrée requis, cliquer sur Ajouter paramètre ( 
) plusieurs fois, voir aussi Ajouter ou supprimer des arguments de fonction. Les constantes " in" et " x " sont des valeurs string. Essentiellement, la fonction retourne la hauteur du tableau, suivi par le string " in ", suivi par " x ", suivi par la largeur du tableau et suivi à nouveau par " in".
Exécuter le mappage
Pour consulter le fichier généré dans MapForce, cliquez sur l’onglet Sortie. Notez que le troisième colonne CSV contient des dimensions de peinture dans le format requis.
Sortie de mappage
Pour enregistrer la sortie de mappage sur le disque :
•Dans le menu de Sortie, cliquez sur Enregistrer le fichier de sortie.
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 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.Exécuter le serveur MapForce avec la commande ci-dessous.
mapforceserver run ReadProtocolBuffers.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.
•Le fichier .mfx est autonome ; le fichier .proto n'est pas nécessaire pour l'exécution de serveur.
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.