Appels du Service Web
Les services Web génériques (pas de style WSDL) incluent toute une catégorie de services Web qui suivent ou suivent partiellement un style architectural référé en tant que "REST" (et généralement appelés "RESTful", ou services Web de style REST). Les services Web HTTP génériques contiennent généralement des requêtes personnalisées ou des structures de réponse dans la partie du corps de message. MapForce prend en charge les types suivants de corps de requête ou de réponse : JSON, XML, Protocol Buffers et des corps non structurés portant des types MIME personnalisés. C'est pourquoi, d'un point de vue de MapForce, les conditions préalables pour appeler un service Web dépendent du type de requête.
•Dans le cas de requêtes ou de réponses XML ou JSON, MapForce nécessite la structure de requête ou de réponse en tant que schéma JSON, XML ou DTD. MapForce acceptera aussi un fichier XML avec une référence de schéma valide en tant que structure. La structure du service Web peut être publiée par le fournisseur de service en tant que schéma XML ou JSON, ou par le biais d'un langage formel comme WADL. Si vous possédez déjà le schéma XML ou JSON de la requête/réponse, vous n'aurez aucun mal à créer l'appel de service Web. Si vous possédez la définition de service Web sous la forme de fichier WADL, vous pouvez l'importer depuis le fichier WADL, puis vous pourrez effectuer tout ajustement manuellement, le cas échéant. Veuillez noter, néanmoins que WADL ne fournit aucune méthode standard pour définir des structures JSON, il ne fournit que des structures XML. Enfin, si vous possédez un fichier d'instance XML ou JSON d'échantillon, mais que vous n'avez pas de fichier de schéma, vous pouvez soit créer, soit générer le schéma avec XMLSpy (https://www.altova.com/xmlspy.html). Le cas échéant, XMLSpy peut convertir votre fichier d'instance de XML à JSON, ou vice-versa.
•Dans le cas de requêtes ou de réponses Protocol Buffers, il vous faut le fichier .proto qui décrit le fichier binaire Protocol Buffers. Dans ce scénario, le corps du service Web peut être mappé de ou vers un composant Protocol Buffers. Pour plus d'informations, voir Exemple : Lire des données depuis Protocol Buffers et Exemple : Écrire les données dans les Protocol Buffers.
•Vous pouvez aussi appeler des services Web dans laquelle la structure de requête ou de réponse est flexible et n'est pas liée à un schéma particulier. Dans ces cas, vous pouvez utiliser les fonctions MapForce mime built-in soit pour créer le corps de message brut envoyé dans le service Web (l'entité MIME) soit traiter depuis le mappage l'entité MIME retourné par le service Web.
Ajouter un appel à un service Web générique
1.Dans le menu Insérer, cliquez sur Fonction du service Web. (En alternative, cliquez sur la touche de barre d'outils Insérer Fonction de service Web
).
2.Sous Définition de service, cliquer sur Manuel.
3.En option, si vous possédez le fichier WADL décrivant le service, cliquer sur Importer depuis fichier WADL et choisir le fichier (voir Importer des informations de service Web depuis un fichier WADL).
4.Choisir la méthode de requête HTTP que MapForce devrait utiliser pour appeler le service Web. Vous pouvez soit sélectionner une valeur depuis la liste existante, soit saisir le nom de la méthode de requête. Les noms de méthode HTTP sont sensibles à la casse.
5.Suivez une des étapes suivantes :
a.Saisir l’URL du service Web dans le champ de texte URL. Avec cette approche, vous pouvez en option transformer des parties spécifiques de l'URL dans des paramètres et les fournir depuis le mappage principal. Pour des URL définies de cette manière, veuillez noter les points suivants :
i.Si vous appelez un service Web avec des paramètres de style "modèle" ou "matrice", il faudra contenir les paramètres dans des accolades, par exemple : http://example.org/api/products/{id}. Ensuite, définir les paramètres réels de chaque paramètre dans la table "Paramètres". Au moment de l'exécution, MapForce remplace les espaces réservés dans des accolades avec les valeurs de paramètre réelles et produit l'URL finale.
ii.Si vous appelez un service Web avec des paramètres d'URL "requête" (par exemple, http://example.org/api/products?sort=asc&category=1&page=1), ne pas saisir la partie de requête dans le champ de saisie URL. Au lieu, définir les paramètres uniquement dans la table "Paramètres", et s'assurer de les désigner en tant que paramètres de style "Query".
iii.Pour voir des exemples, voir Définir les paramètres de service Web.
b.Si vous souhaitez fournir l'URL complète du service Web provenant du mappage principal (ou peut-être en tant que paramètre du mappage), cocher la case URL dynamique (fournie par le mappage). Cela désactive le champ de saisie URL et dans ce cas, vous devez créer l'URL complète du service Web (y compris des paramètres URL) provenant du mappage principal et le connecter à l'entrée respective qui apparaît dans le composant de service Web. Veuillez noter que cette approche n'est plus pertinente pour spécifier tout paramètre dans la table "Parameters", sauf pour les paramètres de style "Header". Si vous tentez de le faire, un dialogue vous avertira.
URL dynamiques Les deux approches décrites ci-dessus (URL entièrement ou partiellement dynamiques), vous pouvez ajuster l'URL de manière flexible selon vos besoins. Par exemple, vous pouvez exécuter le mappage avec une URL spécifique pendant le développement et utiliser une URL différente en production, sans modifier le mappage. Une URL comme https://{host}/some/path/to/service le permettrait, en partant du principe que le nom d'hôte est la seule différence entre la production et le test des URL, et vous pouvez le fournir en tant que paramètre dans le mappage. Noter que les URL partiellement dynamiques renforcent une validation plus stricte, puisque seules les parties d'URL désignées sont remplacées avec des valeurs mappables ou de marche runtime.
Avec des URL entièrement dynamiques, toute l'URL est mappable et vous en détenez le contrôle complet ; la seule exigence est que l'URL doit commencer avec http:// ou https:// et il faut une URI valide. Les URL dynamiques permettent également de fournir l'URL retournée depuis un appel de service Web en tant qu'entrée dans un autre composant qui peut appeler le même service Web (ou un autre). |
6.En option, sous Timeout, saisir une période en secondes au bout de laquelle la connexion devrait expirer si le serveur ne répond pas.
7.Si la méthode HTTP requiert ou retourne une partie de corps (comme XML, JSON ou autre), cliquez sur la touche Éditer sous Structure et chercher le schéma de la partie de corps. Pour plus d'information, voir Définir la structure de requête et Définir la structure de réponse.
8.Sous Paramètres, définir les paramètres du service Web. En option, cliquez sur Importer depuis URL pour importer les paramètres depuis une URL échantillon du service Web et remplir la table « Paramètres » automatiquement (voir Importer des paramètres de service Web depuis une URL). Après avoir importé les paramètres depuis une URL, vous pouvez modifier le contenu de la table « Paramètres », le cas échéant.
| Note : | pour spécifier des en-têtes de requête personnalisées, ajouter un paramètre avec le style « En-tête », dans lequel le nom de paramètre correspond au nom d'en-tête, et la valeur de paramètre correspond à la valeur d'en-tête. De plus, si vous devez fournir la valeur de l'en-tête de requête depuis le mappage lui-même, définir le type de paramètre sur "Mappable". Pour de plus amples informations, voir Définir paramètres du service Web. |
9.Si le service Web requiert une authentification HTTP de base, une autorisation OAuth 2.0 ou une sécurité basée sur certificat, cliquer sur la touche Éditer sous les Paramètres HTTP Security et remplir les champs requis, voir aussi Configurer la Sécurité HTTP.
Une fois avoir cliqué sur OK, un nouveau composant de service Web est ajouté à la surface de mappage. Par exemple, le mappage ci-dessous appelle un service Web dans l'objectif d'extraire un produit par son ID en utilisant une requête GET. Dans cet exemple, l'ID fournie par la requête HTTP possède la valeur de constante "2". Néanmoins, elle pourrait aussi être un paramètre du mappage, ou bien être fournie par tout composant pris en charge par MapForce. Outre le paramètre id, la requête contient l'en-tête Accept: text/json. Vous pouvez définir les en-têtes de requête par le biais de paramètres "en-tête", comme indiqué dans Définir les paramètres de Service Web.
Notez que le composant de service Web consiste en deux parties : Requête et Réponse. La partie Requête vous permet de fournir des données depuis le mappage vers le service Web, alors que la partie Réponse vous permet d'accéder aux données retournées par le service Web et de le mapper vers d'autres formats. La structure de la requête et de la réponse dépend des paramètres, ainsi que la structure de la requête ou de la réponse que vous avez définie en cliquant sur la touche 
. Dans l'appel du service Web ci-dessus, la structure du corps de requête n'est pas définie, alors que la structure du corps de réponse est défini en tant que JSON, ce qui permet de mapper le résultat du service Web vers un fichier JSON.
Pour appeler le service Web avec des paramètres de requête (le cas échéant), tracer des connexions de mappage entre tout composant pris en charge par MapForce (par exemple, un fichier XML ou JSON) et la partie Requête. De même, pour mapper des données retournées par le service Web dans un autre format, tracer des connexions de mappage entre la partie Réponse et tout autre type de composant pris en charge par MapForce. Si vous êtes un novice de MapForce et que vous nécessitez de l'aide en ce qui concerne le traçage des connexions de mappage, voir Travailler avec des Connexions
Les en-têtes de réponse retournés par le service Web sont aussi mappables, s'il s'agit d'en-têtes supplémentaires (ceux qui ne commencent pas avec "Content"). Les valeurs d'en-tête sont disponibles dans le composant de service Web par le biais d'un item appelé "En-têtes" ( 
) qui contient deux items enfant : "Nom" et "Valeur". Cette structure fonctionne en tant que séquence et vous permet de mapper des données provenant des en-têtes retournés par le service Web. Pour mapper les données depuis les en-têtes de réponse sur un autre format pris en charge par MapForce, connecter le nœud de structure "En-têtes" dans une séquence cible dans le mappage. Par exemple, si vous connectez la séquence En-têtes (et ses enfants) à une séquence Lignes (et ses enfants) d'un composant CSV, un en-tête correspondrait à une ligne dans le fichier CSV.
Le Corps 
représente le corps d'entité du message HTTP. Les données à ce niveau sont encodées en binaire, une interaction directe nécessite des fonctions mime MapForce. Veuillez noter qu'il est généralement inutile d'interagir avec le Corps si le service Web attend ou retourne des données structurées comme XML ou JSON. Le mappage de données direct de ou vers le Corps est uniquement nécessaire lorsque vous appelez des services Web qui attendent ou retournent un contenu non structuré.
Par défaut, l'item Corps est configuré afin de parser le résultat si le code de statut HTTP va de 200 à 299. Cela signifie que le mappage retournera une erreur pour des codes de statut supérieurs à 299. De plus, une erreur sera retournée si la réponse ne peut pas être parsée ou si le service Web ne peut pas être appelé en raison d'une erreur de connexion ou de problèmes de résolution de DNS. |
Dans certains cas, vous souhaiterez que le mappage ne lance pas d'erreur même si le code de statut HTTP est supérieur à 299. Pour ce faire, cliquer sur la touche située à côté du Corps de réponse et changer la plage de code de statut HTTP. En alternative, vous pouvez créer plusieurs items Corps de réponse. La création de plusieurs items Corps est utile lorsque vous souhaitez gérer le mappage de manière conditionnelle selon le code de statut HTTP retourné par le service Web. Pour ce faire, cliquer avec la touche de droite sur le Corps de la partie de réponse, et sélectionner Ajouter nœud de corps avant/après depuis le menu contextuel. Par exemple, vous pouvez créer deux items Corps :
1.Un Corps pour tous les codes de statut qui se trouvent dans la plage à succès (200 à 299). Vous pouvez configurer la plage des codes de statut en cliquant sur la touche . En ce qui concerne ce scénario, vous allez habituellement mapper la structure Corps vers une sortie à "succès", comme un fichier JSON ou XML.
2.Un Corps pour tous les autres codes de statut, dans la plage située entre 300 et 599. Certains services Web peuvent fournir des détails supplémentaires concernant les codes de statut d'erreur dans le corps. Afin de découvrir les raisons de l'erreur, vous pouvez mapper le Corps « erroné » dans une sortie autre que le corps de "succès" (par exemple, un string).
Lorsque plusieurs items Corps existent, MapForce les évalue du haut en bas. Pour changer la priorité, cliquer avec la touche de droite sur l'item Corps, et choisir Déplacer vers le haut ou Déplacer vers le bas depuis le menu contextuel Pour plus d'informations concernant la gestion de la réponse HTTP de manière conditionnelle, voir Gérer la réponse HTTP de manière conditionnelle.
Les mappages contenant les appels de service Web HTTP génériques peuvent être exécutés comme la plupart des autres mappages :
•Manuellement, avec MapForce, en cliquant sur le volet Sortie. Dans ce cas, le résultat de l'appel de mappage est disponible immédiatement dans le volet Sortie. Si le mappage a plusieurs composants de sortie comme celui présenté dans l'exemple ci-dessus, appuyer sur la touche Aperçu 
sur le composant désiré avant d'exécuter le mappage.
•Par le biais de la ligne de commande ou d'appels API, avec MapForce Server (https://www.altova.com/fr/mapforce-server). Cela exige de tout d'abord compiler le mappage en un fichier d'exécution de mappage (voir Compiler des mappages pour une version MapForce Server spécifique).
•En tant que tâche récurrente, avec MapForce Server fonctionnant sous contrôle de FlowForce Server (https://www.altova.com/fr/flowforceserver). Voir aussi Déployer des mappages sur FlowForce Server.
Pour consulter des exemples étape par étape de la création d'un appel de service Web générique, voir :
•Exemple : Pour ajouter un appel à un service Web de style REST :