OpenAPI
La spécification OpenAPI est utilisée pour définir les API HTTP. Elle définit les points terminaux/finaux, les opérations, les paramètres d’entrée et de sortie, les paramètres de sécurité et d’autres détails d’une API, généralement dans les format JSON ou YAML. MapForce prend en charge la OpenAPI Specification 2.0 (connu précédemment comme Swagger RESTful API Documentation Specification), 3.0 et 3.1.
Les paramètres OpenAPI que vous pouvez configurer sont décrits ci-dessous sont affichés dans la capture d’écran ci-dessous. Pour plus d’information sur chaque paramètre, voir les sous-sections ci-dessous.
Paramètres OpenAPI
Pour remplir les paramètres d’un appel de service Web, vous allez devoir fournir un fichier OpenAPI qui décrit le service Web : Cliquez sur Naviguer situé à côté du champ Fichier OpenAPI, et sélectionnez le fichier pertinent. Dès que vous avez sélectionné le fichier OpenAPI, les paramètres de ce service Web seront remplis automatiquement. Le cas échéant, vous pouvez changer les paramètres. Ceci n’affectera pas le fichier OpenAPI.
Fichier OpenAPI | Il s’agit du chemin vers le fichier de spécification OpenAPI qui décrit le service Web.
|
Chemin et Opération | Le champ Chemin se réfère à un point de terminaison API (par ex., /users) dont MapForce a besoin d’appeler la fonction souhaitée. Tous les chemins sont relatifs à l’URL du serveur API (voir ci-dessous).
Les opérations se réfèrent aux méthodes HTTP (par ex., GET, DELETE, POST) qui sont utilisées pour exécuter différentes actions sur les chemins. Sélectionnez un chemin, puis une opération pour ce chemin (par ex., POST /users pour ajouter un nouvel utilisateur). Il peut y avoir de multiples chemins disponibles, et pour chaque chemin, il peut y avoir une ou plusieurs opérations définies.
Le chemin et l’opération peuvent être configurés par le biais du même bouton Choisir. Lorsque vous cliquez sur ce bouton, un dialogue (capture d’écran ci-dessous) s’ouvrira et vous invitera à sélectionner un chemin et une opération pour celui-ci. Dans la capture d’écran ci-dessous, l’opération POST a été sélectionnée pour le chemin /pets.
|
Serveur | Le champ Server se réfère à l’URL base d’une API (par ex., https://api.example.com) auquel les chemins du point de terminaison sont relatifs (par ex., https://api.example.com/users).
|
Par défaut, les champs sélectionnés Serveur et Chemin sont concaténés pour constituer l’URL dans les Paramètres de connexion (voir ci-dessous).
Paramètres de connexion
URL | La case de texte URL spécifie l’adresse de votre (URL) service Web.
Services Web RESTful En option, vous pouvez 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 :
•Si vous appelez un service Web avec des paramètres style modèle ou matrice, englobez les paramètres à l’intérieur des accolades, par exemple : http://example.org/api/products/{id}. Ensuite, définisez les paramètres de chaque paramètre dans la table des 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. •Si vous appelez un service Web avec des paramètres d'URL requête (ex., http://example.org/api/products?sort=asc&category=1&page=1), ne saisissez pas la partie de requête dans le champ de saisie URL. À la place, définissez les paramètres uniquement dans la table des Paramètres et assurez-vous de les désigner en tant que paramètres de style requête.
| ||
URL dynamique (fournie par le mappage) | Si vous souhaitez fournir l'URL du service Web provenant du mappage principal, sélectionnez la case à cocher URL dynamique (fournie par le mappage). Ceci crée un connecteur d’entrée supplémentaire dans le composant de service du mappage, auquel vous pouvez connecter quelque entrée qui fournit l’URL du service Web.
Avec des 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).
| ||
Délai d’expiration | Le paramètre Timeout définit l’intervalle de temps après lequel l’appel de service Web sera en mode ‘délai d’expiration’ s’il n’existe pas de réponse depuis le serveur. Sélectionnez Infinite si l’appel doit attendre une réponse pour un moment indéfini.
|
Notes relatives au paramètres dans l’URL
En option, vous pouvez transformer des parties spécifiques de l'URL dans des paramètres et les fournir des valeurs à ces paramètres depuis le mappage principal. Pour des URL définies de cette manière, veuillez noter les points suivants :
•Si vous appelez un service Web avec des paramètres style modèle ou matrice, englobez les paramètres à l’intérieur des accolades, par exemple : http://example.org/api/products/{id}. Ensuite, définissez les paramètres 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.
•Si vous appelez un service Web avec des paramètres d'URL requête (ex., http://example.org/api/products?sort=asc&category=1&page=1), ne saisissez pas la partie de requête dans le champ de saisie URL. À la place, définissez les paramètres uniquement dans la table des Paramètres et assurez-vous de les désigner en tant que paramètres de style requête.
Paramètres
Les paramètres définis dans le fichier OpenAPI sont affichés dans la section Paramètres du dialogue Paramètres d’appel de service Web (capture d’écran ci-dessous). Pour chaque paramètre, vous devez définir si le paramètre est mappable ou s’il a une valeur fixée, mais vous ne devez pas modifier d’autre paramètres des paramètres OpenAPI définis, à l’exception s’ils sont incorrects.
Si un fichier OpenAPI a été mis à jour, et que le service a obtenu des paramètres supplémentaires ou différents, cliquez sur le bouton Réinitialiser pour mettre à jour les paramètres.
En ce qui concerne les nouveaux paramètres, vous allez normalement avoir besoin d’ajouter les paramètres manquants et non documentés dans la section Paramètres.
Pour les détails concernant les paramètres que vous pouvez configurer dans la section Paramètres, voir Paramètres.
Paramètres de sécurité HTTP
Vous allez éventuellement devoir configurer les paramètres de sécurité HTTP dans les scénarios suivants :
•Le service Web est appelé via HTTPS et requiert un certificat client.
•Le serveur utilise un certificat incorrect, et vous aimeriez autoriser un décalage entre le certificat et la requête.
•Le service Web requiert l’authentification HTTP de base ou l’autorisation OAuth 2.0.
Pour plus d’information, voir Paramètres de sécurité HTTP.
Enregistrer tous les chemins de fichier relatifs au fichier MFD
Lorsque cette option est activée, MapForce enregistre les chemins de fichier affichés dans le dialogue Paramètres de composant relatif à l’emplacement du fichier de MapForce Design (.mfd). Voir aussi Utiliser des chemins relatifs et absolus.