Paramètres REST Web Services
Lorsque vous devez appeler un service Web avec des paramètres URL, les paramètres doivent être définis dans le dialogue de Paramètres d'appel de Service web. Ce dialogue vous permet aussi de configurer la requête de service Web avec des en-têtes personnalisés. Vous pouvez configurer les valeurs de paramètre pour qu’elles soient mappables (fournies par le mappage) ou fixes (définies dans la boîte de dialogue).
Pour définir des paramètres de service, suivez les étapes suivantes :
1.Double-cliquez la barre de titre du composant de service Web dans le mappage ou cliquez avec la touche de droite et sélectionnez Propriétés. La boîte de dialogue Paramètres d’appel de service Web s’ouvre.
2.Sous Définition de Service, choisir Manuel. Vous pouvez saisir les paramètres manuellement ou automatiquement (en les important depuis une URL existante ou depuis un fichier WADL). Les paramètres importés sont disponibles dans la table Paramètres (voir la sous-section ci-dessous) où vous pouvez les modifier, le cas échéant.
3.Utilisez les boutons Ajouter Paramètre ( 
) et Supprimer Paramètre ( 
), selon vos besoins.
Paramètres
Les sous-sections résument les paramètres disponibles dans le dialogue Paramètres d’appel de service web.
Spécifie le nom du paramètre URL. Le nom du paramètre doit être unique et peut se composer de caractères alphanumériques, périodes, tirets et tirets bas. Les espaces ne sont pas autorisés dans le nom de paramètre.
|
Spécifie la syntaxe (style) du paramètre URL.
•Utiliser le style En-tête pour ajouter un paramètre à l'en-tête HTTP lorsque vous appelez le service Web. Par exemple, l'ajout d'un paramètre Accepter avec la valeur text/xml est équivalent à spécifier l'en-tête Accept: text/xml, qui informe le serveur Web que MapForce attend une réponse en format XML. Pour plus d'informations sur les en-tête HTTP, voir la Spécification En-tête de Message. •Utiliser le style Query pour des paramètres URL qui définissent les paires key-value utilisant le format ?key=value&key=value (par ex., http://example.org/api/products?sort=asc&category=1&page=1). Les caractères autorisés sont : ASCII alphanumérique, caractères Unicode, espace -._~ /?:@!$'()*; . Les caractères suivants ne sont pas autorisés : =&#. •Utilisez le style Modèle pour les paramètres URL intégré dans les accolades (par ex., http://example.org/api/products/{id}). Pour ce type de paramètres, MapForce échappe les valeurs conformément aux Règles RFC 6570 https://tools.ietf.org/html/rfc6570. •Utilisez le style Matrix pour les paramètres URL qui définissent les paires key/value dans le format ;key=value;key=value; (par ex., http://example.org/api/products;sort=asc;category=1;page=1;). Pour utiliser les paramètres de matrice booléenne, définir le style sur Matrix et le type sur boolean). •Sélectionnez Corps pour envoyer une structure de requête application/x-www-form-urlencoded à un service REST (la méthode de requête doit être POST). Pour en savoir plus sur le format urlencoded, voir la Spécification URL. Les caractères autorisés sont : ASCII alphanumérique, caractères Unicode, espace -._~!$'()*+,;:@%/?#[] . Les caractères suivants ne sont pas autorisés : =&.
|
Spécifie le type de données du paramètre (string, entier, date, etc). Il peut s'agir de n'importe quel type de schéma XML. Veuillez noter que toute valeur qui n'est pas un string sera convertie en un string lorsque l'appel de service Web a lieu. Définir un type est pertinent si vous souhaitez que MapForce affiche des messages d'erreur de conversion lorsque vous tentez d'appeler un service Web avec les mauvaises valeurs.
|
Cocher cette case si vous souhaitez passer des valeurs sur ce paramètre depuis le mappage. Cette option est mutuellement exclusive avec l'option Valeur fixe.
|
Spécifie la valeur du paramètre. Applicable uniquement si le paramètre a une valeur constante. N'est pas applicable si le paramètre est mappable (voir option précédente).
|
Cocher cette case si le paramètre est requis par le service Web. Pour les paramètres qui sont requis et également mappables, MapForce renforce les vérifications de validation : Un message d’erreur est affiché si le paramètre n’a pas de valeur.
|
Spécifie si le paramètre a une valeur unique ou s'il peut avoir plusieurs valeurs. Ce paramètre est applicable uniquement pour les paramètres mappables. Cette option vous permet de passer plusieurs valeurs dans le même appel de service Web par le biais d'un paramètre unique. Si vous cochez la case, vous pouvez vous connecter à une séquence de valeurs au nœud de structure du paramètre sur le mappage au lieu d'une valeur unique. MapForce gérera ensuite la séquence des valeurs selon le style du paramètre :
•Pour les paramètres Modèle, les valeurs seront fournies au service Web avec une séparation par virgule (par exemple, http://example.org/api/products/1,2,3 •Pour les paramètres Requête, le nom du paramètre sera répété pour chaque valeur, par exemple : http://example.org/api/products?color=red&color=green&color=blue •Si le style est Matrix, de multiples valeurs seront séparées par une virgule (par exemple : http://example.org/api/products;color=red;color=green;color=blue;size=big;size=small;). •Si le style est Header, l'en-tête HTTP sera répétée pour chaque valeur.
|
Spécifie la description optionnelle du paramètre. Si le paramètre est mappable, la description saisie ici apparaît dans le composant de mappage comme annotation à côté de l’item de mappage.
|
Exemple 1 : En-tête et paramètres de modèle
Le service Web illustré ci-dessous extrait un produit par son identifiant (id) utilisant la méthode HTTP GET. L'URL du service Web spécifie le paramètre id dans des accolades. Veuillez noter que le paramètre id existe aussi dans la table Paramètres et comporte le style Modèle. Il est également mappable : cela entraîne l'apparition du paramètre dans le mappage sous la forme d'un nœud de structure auquel vous pouvez connecter la valeur réelle de id (qui pourrait être, par exemple, prélevée d'une base de données, d'un fichier, ou d'une constante). Lors de l'exécution du mappage, ce paramètre serait remplacé avec la valeur réelle ; donc si la valeur est "1", l'URL devient http://example.org/api/products/1 .
Pour fournir une valeur id constante au lieu d'une valeur provenant du mappage, vous pouvez décocher l'option "Mappable" et saisir la valeur dans la colonne "Valeur fixe".
Les paramètres Accepter et Accept-Charset ont le style Header. Ces paramètres sont utilisés pour appeler le service Web avec des en-têtes de requête personnalisées. Il existe deux moyens de fournir la valeur d'en-tête :
•Laisser l'option Mappable cochée et fournir la valeur d'en-tête personnalisée à partir du mappage ou bien
•Supprimer l'option Mappable et saisir la valeur directement dans la colonne "Valeur fixe".
Exemple 2 : Paramètres Matrix
Le service Web illustré ci-dessous extrait une liste de produits qui correspondent à la couleur et à la taille fournies comme arguments. Le style des paramètres est "Matrice", ils sont donc définis tous les deux en tant qu'espaces réservés dans l'URL et dans la table de mappage. Veuillez noter que les paramètres sont mappables et que l'option "Répétitif" est cochée. Cela signifie que leur valeur sera lue à partir de séquences de valeurs dans le mappage (par exemple, une liste de lignes à l'intérieur d'un fichier de texte, un nœud XML, ou une colonne de base de données) et fournies au service Web lors de l'exécution. Ainsi, une URL comme celle ci-dessous peut devenir http://example.org/api/products/;color=red;color=blue;size=big;size=small, si le mappage fournit red et blue en tant que couleurs et big et small en tant que taille.
Si vous souhaitez que l'URL soit http://example.org/api/products;color=red,blue;size=big,small, procéder comme suit :
1.Saisir l'URL http://example.org/api/products;color={color};size={size}
2.Dans la table "Paramètres", changer le style de paramètre sur Matrice.
Si vous souhaitez que l'URL soit http://example.org/api/products?color=red,blue&size=big,small, procéder comme suit :
1.Saisir l'URL comme http://example.org/api/products?color={color}&size={size}
2.Dans la table "Paramètres", changer le style de paramètre sur Matrice.
Exemple 3 : Paramètres Requête
Le service Web illustré ci-dessous extrait une liste de produits qui correspondent à la couleur et à la taille fournies comme arguments sélectionnant cette fois Moteur intégré le style " Pour ce style, il n'est pas nécessaire de définir les paramètres en tant qu'espaces réservés dans l'URL, ils sont donc uniquement définis dans la table "Paramètres". Dans cet exemple, partons du principe que les valeurs de paramètre sont saisies et ne doivent pas être fournies depuis le mappage. Pour ce faire, les valeurs de paramètre ont été saisies sous "Valeurs fixes" et l'option "Mappable" est non-cochée. Donc, au moment de l'exécution du mappage, l'URL ci-dessous devient http://example.org/api/products?color=red&size=big.
