Exemple : appeler un service web style REST
Cet exemple vous montre comment appeler un service Web HTTP générique depuis MapForce. La description du service Web appelés dans cet exemple peut être trouvé sous https://app.swaggerhub.com/apis/FAA/ASWS/1.1.0. Ce service Web retourne le statut actuel des aéroports principaux US, en tant qu'une structure XML ou JSON, qui accepte le code d'aéroport à trois lettres en tant qu'argument (par exemple, "SFO", "IAD", "ABE", "DFW", etc). L'exemple est accompagné par un fichier de design de mappage, qui est disponible sur le chemin suivant : <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.mfd.
Dans cet exemple, la réponse du service Web se trouve en format JSON, et est mappé dans un fichier JSON. Ainsi, le schéma JSON de la structure de réponse du service Web sera requis. Pour une utilisation plus simple, le schéma JSON a été généré avec XMLSpy depuis une réponse d'échantillon apportée par le fournisseur de service Web. Elle est disponible sur le chemin suivant : <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json.
En ce qui concerne la partie de la requête, nous allons appeler le service Web avec un paramètre qui fournira la valeur "SFO" dans la requête. Pour la partie de la réponse, nous allons mapper les données de réponse sur un fichier JSON. C'est pourquoi le mappage consistera en trois composants principaux : l'appel de service Web, le paramètre d'entrée, et le fichier de sortie JSON.
Étape 1: Ajouter le composant de service Web
1.Veuillez assurer que le langage de transformation du mappage est BUILT-IN.
2.Dans le menu Insérer, cliquer sur Fonction Service Web.
3.Sous Définition de Service, cliquer sur Manuel.
4.Configurer la méthode de requête sur GET et l'URL sur https://soa.smext.faa.gov/asws/api/airport/status/{airportCode}}. La valeur se trouvant entre les accolades est un paramètre de modèle qui seront remplacée avec le vrai code d'aéroport lors de l'exécution (voir Ajouter un appel de service Web (Style REST).
5.Cliquer sur la touche Ajouter Paramètre ( 
) et ajouter un nouveau paramètre dans la table "Paramètres". Veuillez noter que le nom du paramètre doit être le même que celui du paramètre spécifié dans les accolades dans l'URL. Configurer le style "Modèle", sur "String", cocher l'option "Mappable" et "Requis". Le champ "Description" est optionnel.
6.Ajouter un en-tête pour indiquer au serveur Web que le client (donc MapForce) attend JSON en réponse. Pour ce faire, cliquer à nouveau sur la touche Ajouter Paramètre ( ), nommer le paramètre "Accepter", définir le style sur "En-tête" et saisir application/json en tant que valeur fixe.
7.Sous Réponse, cliquer sur la touche Éditer et chercher le schéma de la réponse de service Web. Le schéma peut être trouvé sur le chemin suivant : <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json.
8.Cliquer sur OK. Le service Web est maintenant disponible sur la zone de mappage.
Étape 2: Ajouter le paramètre d'entrée
1.Dans le menu Insérer, cliquer sur Insérer entrée.
2.Saisir "airportCode" en tant que nom de paramètre et cliquer pour désactiver l'option Entrée est requise (puisque l'entrée sera fournie par une constante, comme indiqué dans l'étape suivante).
3.Ajouter une constante (en utilisant la commande de menu Insérer | Constante) avec la valeur "SFO" et la connecter à l'entrée du paramètre.
4.Connecter la sortie du paramètre aiportCode à l'entrée de la requête, comme indiqué ci-dessous.
À ce niveau, la partie requête du service Web est prêt. Lors du mappage, le service Web sera appelé avec la valeur fournie par la constante (dans ce cas, "SFO").
Étape 3: Ajouter la sortie JSON
1.Dans le menu Insérer, cliquer sur Schéma JSON /Fichier.
2.Chercher <Documents>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json, et cliquer sur Ouvrir.
3.Lorsque vous serez invité à fournir un fichier JSON échantillon, cliquer sur Sauter (un fichier JSON d'échantillon n'est pas nécessaire puisqu'il sera généré).
4.Dans le menu Connexion, veuillez vous assurer que l'item de menu Auto-connexion des enfants correspondants est activé. Le fait d'activer cette option vous permet de gagner du temps pour l'étape suivante.
5.Connecter le nœud object du corps de réponse du service Web au nœud object du composant JSON, comme indiqué ci-dessous. Puisque Auto-connexion des enfants correspondants a été activé dans l'étape précédente, tous les nœuds descendants sont connectés automatiquement, il n'est donc pas nécessaire de tracer des connexions individuelles pour chacun d'entre eux.
Étape 4: Exécuter le mappage
Vous êtes maintenant prêt à appeler le service Web. Cliquer sur la touche Sortie pour exécuter le mappage et consulter la sortie générée. Si l'appel de service Web est exécuté avec succès, l'onglet Sortie affiche la structure JSON retournée. Si l'appel ne réussit pas, MapForce retournera l'erreur adéquate. Comme déclaré dans la description du service Web, le code 500 HTTP peut être retourné par le service Web en cas de réponse d'erreur. Le code 404 HTTP peut s'afficher si l'information de retard n'est pas disponible.
Si vous avez MapForce Server (https://www.altova.com/mapforce-server), vous pouvez aussi compiler le mappage vers un fichier d'exécution de mappage (*.mfx) et de l'exécuter depuis la ligne de commande ou depuis l'API MapForce Server sur l'appareil de serveur sur lequel MapForce Server est exécuté (voir Compiler des mappages sur des fichiers d'exécution MapForce Server ).
Vous avez maintenant terminé de créer un service Web HTTP générique qui utilise une méthode GET pour extraire les données de statut d'aéroport en temps réel. Pour plus d'informations concernant le travail avec les services Web génériques, voir aussi Ajouter un appel de service Web (Style REST).