Via requêtes REST
Les paramètres pour les requêtes REST sont définis dans le dialogue RESTful API Request (capture d'écran ci-dessous). Ce dialogue est accessible dans deux situation :
•Lors de la définition d'une source de page qui utilise une requête REST pour se connecter à une source de données
•Par le biais de l'action Exécuter requête REST ; dans ce cas, la réponse à la requête peut être stockée dans une variable $MT_HTTPExecute_Result.
Vous pouvez choisir de (i) définir vos propres paramètres, (ii) importer une URL, ou (iii) utiliser un fichier WADL. Si vous choisissez de définir vos propres paramètres, vous pouvez spécifier vos propres définitions pour les paramètres individuels. Si vous importez une URL ou utilisez un fichier WADL, certains paramètres seront définis dans l'URL ou le fichier WADL et ne pourront donc pas être modifiés par vous.
Les différents paramètres sont décrits ci-dessous :
•Modèles et parsage de résultat, y compris $MT_HTTPExecute_Result
•URL
Modèles et parsage cible
Le terme de modèle désigne les trois frameworks dans le cadre desquels les paramètres peuvent être définis (vos propres paramètres, URL et WADL ; voir capture d'écran ci-dessus). Vous pouvez passer entre les modèles à tout moment en sélectionnant le bouton radio approprié. Si le modèle URL ou WADL est déjà sélectionné et que vous souhaitez utiliser une URL ou un fichier différent, cliquez respectivement, Importer depuis URL ou Importer depuis WADL. En sélectionnant l'option URL ou WADL (ou leur bouton respectif Importer), un dialogue s'ouvre dans lequel vous pouvez spécifier l'URL ou le fichier WADL à utiliser.
Définir vos propres paramètres
Si vous définissez vos propres paramètres, vous pouvez saisir la requête dans un serveur REST en tant qu'une URL, spécifier le format de données de la ressource cible (XML, HTML ou JSON), puis saisir les informations d'authentification de l'utilisateur et, le cas échéant, requêter des paramètres et des contenus et en-têtes HTTP. Voir les descriptions en-dessous de chacun de ces paramètres.
Utiliser une URL
Si une URL est longue ou complexe, il vaut mieux l'importer dans le modèle Utiliser une URL plutôt que de la saisir dans le modèle Définir les propres paramètres. Par exemple, une URL peut contenir un certain nombre de paramètres, comme indiqué dans l'exemple ci-dessous (qui est une requête Google contenant cinq paramètres) :
https://www.google.at/search?q=REST+WADL&ie=utf-8&oe=utf-8&gws_rd=cr&ei=89cDVrDHMIP0Up_5vcAB
Si vous importez cette URL, elle sera saisie dans le champ URL du modèle, et les paramètres seront saisis dans la table Paramètres du modèle. Vous pouvez sélectionner le format de données de la ressource cible (XML, HTML ou JSON) et la Méthode de requête (GET, PUT, POST ou DELETE). Vous pouvez ensuite saisir les valeurs pour les paramètres, mais vous ne pouvez pas supprimer un paramètre ou changer son type. Si vous souhaitez changer l'URL, cliquez sur Importer depuis URL. Pour une description des paramètres, voir la section Paramètres ci-dessous.
Utiliser un fichier WADL
Un fichier WADL est un document XML qui définit les ressources fournies par un service web et la relation entre les ressources. Celles-ci sont définies par les éléments resource. Chaque ressource contient : (i) des éléments param pour décrire les entrées et des (ii) éléments method pour décrire la requête et la réponse d'une ressource. L'élément request spécifie comment représenter l'entrée, les types requis et les en-têtes HTTP spécifiques requises. L'élément response décrit la réponse du service, ainsi que l'information d'erreur.
Lorsque vous sélectionnez l'option WADL, vous êtes invité à choisir le fichier WADL que vous souhaitez utiliser. Après avoir cliqué sur OK, le dialogue Choisir la méthode apparaît (capture d'écran ci-dessous). Ce dialogue affiche les méthodes définies dans le fichier WADL.
Choisir la méthode que vous souhaitez utiliser puis cliquer sur OK. L'URL de la ressource est saisie dans le champ URL du modèle et les paramètres ainsi que le contenu et en-têtes HTTP définis dans le fichier WADL pour cette ressource sont saisis dans les tables respectives du modèle (voir capture d'écran ci-dessous). Dans le modèle, vous pourrez saisir les valeurs des paramètres et du contenu et en-têtes HTTP, mais les noms de paramètres ne peuvent pas être édités et les paramètres ne peuvent pas être supprimés.
Parser le résultat en tant que
Le résultat est ce qui est retourné par le service web en réponse à la requête. Dans les modèles Définir propres paramètres et URL, vous devez spécifier comment ce résultat devra être parsé (en tant que XML, HTML ou JSON) afin que MobileTogether puisse traiter le résultat correctement. Dans le modèle WADL, l'information concernant le format de l'information est prélevée depuis les définitions dans le fichier WADL et seront sélectionnées automatiquement ; en conséquence, ces boutons de radio seront désactivés dans ce modèle.
$MT_HTTPExecute_Result
Vous pouvez choisir si le résultat sera stocké dans le $MT_HTTPExecute_Result ou pas. Une fois stocké, vous pouvez utiliser le résultat, par le biais de cette variable, dans d'autres emplacements du design. Veuillez noter que cette option n'est pas affichée dans le dialogue Requête API RESTful lorsque la source de page est définie pour la première fois. Elle s'affiche lorsque le dialogue s'ouvre par le biais de l'action Exécuter requête REST.
Méthode de requête
Dans les modèles Propres paramètres et URL, vous devrez spécifier la méthode de Requête (GET, PUT, POST ou DELETE, ou quelques autres verbes que nous appelons verbe personnalisé). Un verbe personnalisé serait un qui est utilisé par le serveur duquel vous sollicitez une source de données et celui que vous souhaitez utiliser pour la requête. Pour utiliser un verbe personnalisé, sélectionnez son option et saisissez le verbe personnalisé dans le champ de texte qui apparaît. Vous pouvez, au lieu de saisir directement un verbe personnalisé, utiliser une expression XPath pour générer le verb personnalisé.
Dans le modèle WADL, la méthode de requête est déterminée par votre sélection dans le dialogue Choisir une méthode pour une ressource (voir ci-dessus pour capture d’écran), et elle sera sélectionnée automatiquement dans le modèle ; en conséquence, ces boutons radio seront désactivés dans le modèle.
Vous pouvez définir les délais d’expiration suivants :
•Un délai d’expiration de connexion, qui est le moment jusqu’à ce qu’une connexion TCP soit établie.
•Une demande de délai d’expiration, qui est le moment de compléter la requête.
Les deux valeurs peuvent être saisies soit directement ou via une expression XPath et doit être donnée en secondes, avec des décimales à utiliser pour des fractions d’une seconde. La plus petite fraction qui sera acceptée est la milliseconde.
URL
Le champ d'URL peut être édité uniquement dans le modèle Définir propres paramètres. Dans ce modèle, vous pouvez saisir l'URL directement ou en tant qu'expression XPath. Utiliser le bouton Réinitialiser pour supprimer l'entrée dans le champ URL.
Permettre des connexions SSL non approuvées
Un certificat associé à une URL est considéré non approuvé s’il n’est pas signé par un certificat racine approuvé ou s’il ne peut pas mettre en lien vers un certificat racine approuvé. Si le certificat est signé par une autorité majeure de certificat, cela signifie uniquement qu’un des certificats de chaîne entre vous et la racine n’est pas installée sur le serveur web. Si un certificat approuvé est attendu (par exemple, parce que le protocole HTTPS est précisé), alors sélectionner l’option permet aux connexions aussi avec des URL d’avoir un certificat non approuvé.
Authentification
Vous pouvez fournir les informations d'authentification si celle-ci sont nécessaires pour accéder au serveur. Sélectionner Aucun dans le dialogue Requête RESTful API (voir capture d'écran ci-dessus) si aucune authentification n'est nécessaire.
Les informations d'authentification peuvent être fournies des manières suivantes :
•Basic: un nom d'utilisateur et un mot de passe sont fournis (voir capture d'écran ci-dessous)
•OAuth 1.0
•OAuth 2.0
Si vous souhaitez configurer les informations d'authentification, cliquez sur Configuration de l'authentification dans le dialogue Requête RESTful API (voir capture d'écran ci-dessus). Le dialogue de Paramètres d'authentification s'affiche (capture d'écran ci-dessous), dans lequel vous pouvez sélectionner le type d'authentification nécessité par le serveur puis fournir les détails d'authentification.
Authentification OAuth
En principe, OAuth authentifie MobileTogether Designer et autorise l'accès aux ressources du service web identifié par l'URL. Cela, en partant du principe que le service web prenne en charge OAuth. Pour voir un exemple du service web qui prend en charge OAUTH, voir la documentation BitBucket concernant OAuth 1.0.
En gros, le système OAuth fonctionne de la manière suivante :
1.Au niveau du service web, créer une clé OAuth (ou ID) et un secret. Mis ensemble, ces éléments sont connus en tant qu'un Consumer OAuth.
2.Notez les points de terminaison OAuth du service web. Il y a trois points de terminaison pour OAuth 1.0 (Point de terminaison initial, Point de terminaison d'autorisation, et point de terminaison de jeton), et deux points de terminaison pour OAuth 2.0 (Point de terminaison d'autorisation et point de terminaison de jeton). Les points de terminaison sont généralement constants pour tous les consommateurs.
3.Configurer l'application pour accéder au service web avec ces cinq (OAuth 1.0) ou quatre (OAuth 2.0) pièces d'information d'authentification.
Une fois avoir obtenu votre clé et votre secret du service web et que vous avez noté les points de terminaison que vous nécessitez, vous êtes prêt à configurer MobileTogether Designer pour accéder au service web. Procédez comme suit :
1.Dans le dialogue Paramètres d'authentification (capture d'écran ci-dessus), cliquer sur Configurer OAuth 1.0 ou Configurer OAuth 2.0. Le dialogue Paramètres OAuth (capture d'écran ci-dessous) apparaît.
2.Configurer l'Adresse callback à http://localhost:8083. Cette adresse est fixe ; il s'agit de l'adresse de la machine sur laquelle vous travaillez.
3.Créer de nouveaux paramètres : Donnez un nom à vos paramètres. Cela permet de le réutiliser (par le biais de l'option de liste de choix Réutiliser les paramètres) pour d'autres solutions utilisant les mêmes ressources.
4.Saisir les points de terminaison déclarés par le service web. Ceux-ci sont généralement constants sur tout le service web pour tous les consommateurs du service.
5.Saisir votre clé (ou ID) et secret.
6.Cliquer sur Autoriser pour terminer.
Paramètres
Dans le modèle Définir propres paramètres, les paramètres peuvent être ajoutés, édités et supprimés à volonté. Néanmoins, dans les modèles Utiliser URL et Utiliser WADL, vous pouvez uniquement éditer les valeurs des paramètres, vous ne pouvez pas ajouter ou éditer de paramètres ou éditer leurs noms.
Vous pouvez ajouter les types suivants (ou styles) de paramètres (voir la colonne 'Styles' de la capture d'écran ci-dessous.)
•Modèle : les paramètres de modèle utilisent des espaces réservés pour substituer une valeur dans une URL pendant la marche. Par exemple, dans la capture d'écran ci-dessous, il y a un paramètre de modèle avec un espace réservé {product}. Cet espace réservé est utilisé dans l'URL (voir capture d'écran ci-dessous). Il est marqué par des accolades pour indiquer qu'il s'agit d'un espace réservé. Lorsque l'URL est utilisée pendant la marche, la valeur de l'espace réservé est substituée dans l'emplacement correspondant de l'URL. La partie pertinente de l'URL serait donc : https://docs.altova.com/XMLSpy.../features.
•Matrice : Dans le cas des paramètres de matrice, l'espace réservé dans l'URL est remplacé par une paire name=value. Dans l'exemple de la capture d'écran ci-dessous, il y a deux paramètres de matrice, donnés dans l'URL par les espaces réservés {language} et {version}. Ces espaces réservés dans l'URL donnent les parties marquées en bleu : https://docs.altova.com/XMLSpy;lang=en;ver=2016.../features. Le point-virgule de séparation ; est préfixé à chaque paramètre en tant que partie intégrante de la substitution.
•Matrice Booléenne : si la valeur d'un paramètre de matrice booléenne est définie sur true, alors l'espace réservé du paramètre est remplacé par le nom du paramètre. Si la valeur est définie à false, alors l'espace réservé du paramètre est remplacé par la chaîne vide (donc par rien). Ainsi, dans l'exemple indiqué dans la capture d'écran ci-dessous, l'espace réservé de matrice booléenne donne la partie surlignée : https://docs.altova.com/XMLSpy;lang=en;ver=2016;sort/features. Le point-virgule de séparation ; est préfixé à chaque paramètre en tant que partie intégrante de la substitution.
•Requête : les paramètres de requête n'utilisent pas d'espaces réservés. Tous les paramètres de requête sont rassemblés dans une seule chaîne de requête et cette chaîne est ajoutée lors de la marche à la partie du chemin d'accès de l'URL. Par exemple, l'URL montrée dans la capture d'écran ci-dessous résoudra lors de la marche à : https://docs.altova.com/XMLSpy;lang=en;ver=2016;sort/features?type=PDF. Le point d'interrogation de séparation ? est préfixé à la chaîne de requête. Des séries supplémentaires sont préfixées par le séparateur esperluette &. Donc une chaîne de requête avec deux requêtes apparaîtrait de la manière suivante : ?type=PDF&about=json.
Colonnes de la table Paramètres
La table Paramètre a quatre colonnes. L'utilisation de ses trois premières colonnes est expliquée dans la description des types de paramètres indiqués ci-dessus. Veuillez noter que les paramètres modèles, matrice et matrice booléenne utilisent des espaces réservés. Alors que les espaces réservés des paramètres modèles sont remplacés par des valeurs, les espaces réservés de paramètres matrice et matrice booléenne sont remplacés par des paires nom-valeur et des noms, respectivement. Les paramètres de requête n'ont pas d'espaces réservés ; leurs paires nom-valeur sont ajoutés au chemin d'accès de l'URL. La colonne Description contient des descriptions du paramètre pour vous, l'utilisateur MobileTogether Designer.
Icônes de table Paramètre et édition de table
En haut à droite de la tale Paramètres, vous trouverez des icônes qui vous permettent de gérer les entrées dans la table.
•Ajouter et insérer des paramètres : utiliser Ajouter pour ajouter un nouveau paramètre en tant que le dernier paramètre dans la table. Utiliser Apposer pour apposer un nouveau paramètre en tant que le dernier paramètre dans la table. Utiliser Insérer pour insérer un nouveau paramètre directement au-dessus du paramètre sélectionné actuellement. L'ordre dans lequel les paramètres sont saisis dans la table a peu d'importance. C'est l'ordre des espaces réservés dans l'URL qui est important. Tous les paramètres de requête sont rassemblés dans une seule chaîne de requête et cette chaîne est ajoutée lors de la marche à la partie du chemin d'accès de l'URL.
•Supprimer des paramètres : cliquer sur Supprimer pour supprimer le paramètre sélectionné.
•XPath expressions for parameter values: Expressions XPath pour les valeurs de paramètre : lorsqu'un paramètre est sélectionné, cliquer sur XPath pour ouvrir le dialogue Éditer expression XPath/XQuery et saisir une expression qui résout en une chaîne. Cette chaîne est saisie en tant que la valeur du paramètre. Dans ces cas, une icône XPath apparaît dans la colonne Valeur du paramètre. Cliquer sur cette icône afin d'éditer l'expression XPath.
•Réinitialiser les valeurs de paramètre : cliquer sur Réinitialiser les paramètres pour supprimer la valeur d'un paramètre.
•Éditer des noms et des valeurs de paramètre : Cliquer dans le champ respectif et éditer.
Contenu HTTP
Vous pouvez spécifier un contenu à envoyer avec des requêtes HTTP PUT et POST. Vous pouvez envoyer le contenu en tant qu'un seul élément dans le corps de la requête (Envoyer contenu en tant que corps) ou en tant qu'éléments multiples dans une requête multipartie (Envoyer contenus en tant que multipartie). Sélectionner le bouton radio approprié.
Ajoute ou insère un contenu à l'aide des icônes en haut à droite.
Envoyer le contenu en tant que corps
Saisir la valeur du contenu et le types MIME du contenu. Le contenu peut être saisi directement ou peut être accédé depuis un nœud XML.
Envoyer des contenus en tant que multipartie
Saisir le nom pour la partie du contenu à envoyer, le type d'accès au contenu, le contenu lui-même et le type MIME du contenu. La valeur du contenu est le contenu véritable qui sera envoyé. Dans la capture d'écran ci-dessus, le contenu est obtenu par le biais des expressions XPath, depuis les nœuds de source de page. Les images sont envoyées en format Base64 ou en tant que fichier.
Champs d'en-tête HTTP
Les champs d'en-tête HTTP sont des paires nom-valeur séparés par un point-virgule, par exemple : Accept:text/plain. Ajouter ou insérer une entrée pour chaque en-tête, puis saisir le nom et la valeur d'en-tête (voir capture d'écran ci-dessous).
