|
|
|
|
|
|
|
|
|
|
- Présentation
- Importer un Webservice dans un projet
- Importation
- Volet "Explorateur de projet"Â : visualiser un webservice
- Description et propriétés d'un Webservice
- Mettre à jour la description d'un Webservice
- Propriétés d'un Webservice modifiables dans l'éditeur
- Utilisation d'un Webservice
- Principe
- Comment écrire dans l'entête HTTP d'un appel à un Webservice SOAP ?
- Appel asynchrone d'un Webservice
- Propriétés associées au Webservice
- Propriétés disponibles sur les types de variables
- Manipulation avancée du flux XML du Webservice
- Cas particulier : le Webservice renvoie un résultat dans un type non reconnu par WINDEV, WEBDEV et WINDEV Mobile
- Distribuer une application WINDEV qui utilise un Webservice
Importation/consommation de Webservices
WINDEV, WEBDEV et WINDEV Mobile permettent d'importer directement des Webservices dans vos applications. Un Webservice est un ensemble de points d'entrées mis à la disposition des utilisateurs afin d'effectuer différents traitements. Par exemple, un service d'accès distant met à votre disposition les traitements d'accès aux données. Les échanges d'informations avec un Webservice se font au format XML et utilisent les protocoles SOAP (Simple Object Access Protocol) et HTTP. A partir de la description au format WSDL (Web Services Description Language) de ce service, WINDEV, WEBDEV ou WINDEV Mobile va générer automatiquement des types et des fonctions WLangage correspondants à l'interface de programmation du Webservice. Pour utiliser le Webservice, il suffit d'utiliser les fonctions générées au moment de l'import. Cette page d'aide présente :
Importer un Webservice dans un projet Importation Pour importer un Webservice : - Sous le volet "Projet", dans le groupe "Projet", déroulez "Importer" et sélectionnez "Un Webservice".
L'assistant d'importation d'un Webservice se lance.
- Dans l'assistant, l'écran de présentation s'affiche. Passez à l'étape suivante.
- Indiquez la localisation du WSDL (prononcer wizdeul). Ce fichier correspond à la description du webservice. Il contient la description de chaque fonction contenue dans le Webservice ainsi que leurs paramètres. Deux méthodes peuvent être utilisées pour localiser le WSDL :
- soit à partir d'une URL, adresse HTTP où se trouve le WSDL.
Remarques : - Il est possible d'indiquer le nom d'utilisateur et le mot de passe si une authentification est nécessaire.
- Le bouton "Proxy" permet de configurer les options du proxy si nécessaire.
- soit depuis un fichier XML présent sur le poste en cours.
- Terminez l'assistant. Un message apparaît indiquant que l'importation est terminée.
- Le Webservice est automatiquement ajouté dans le volet "Explorateur de projet" (dans la branche "Webservices importés"). Il est prêt à être utilisé.
Volet "Explorateur de projet" : visualiser un webservice Le Webservice importé est présent dans le volet "Explorateur de projet", dossier "Webservices importés" : La structure est constituée de : - le nom du Webservice.
- le nom de chaque fonction.
- le nom d'une structure contenant soit les paramètres d'appel, soit les valeurs de retour.
- le nom de chaque variable de la structure.
Description et propriétés d'un Webservice Mettre à jour la description d'un Webservice Lorsqu'un Webservice évolue (corrections, nouvelles versions, etc.), sa description peut également être amenée à évoluer. Pour mettre à jour la description d'un Webservice dans votre projet : - Sélectionnez le Webservice dans le volet "Explorateur de projet".
- Sélectionnez l'option "Mettre à jour" du menu contextuel.
Remarque : Les Webservices importés en utilisant le mécanisme de compatibilité avec les versions précédentes ne peuvent pas être mis à jour. Propriétés d'un Webservice modifiables dans l'éditeur Pour modifier les propriétés d'un Webservice dans l'éditeur : - Sélectionnez le Webservice dans le volet "Explorateur de projet".
- Choisissez l'option "Description" du menu contextuel.
- La fenêtre des propriétés s'ouvre. Dans cette fenêtre, il est possible de modifier les propriétés suivantes :
- L'adresse d'importation du Webservice : il s'agit de l'URL permettant d'atteindre le WSDL décrivant le Webservice.
- Le nom d'utilisateur et le mot de passe utilisés pour importer le WSDL.
Utilisation d'un Webservice Principe Pour utiliser un Webservice, il faut : - Déclarer 2 variables : une variable permettant de spécifier les paramètres d'appel, une variable permettant de récupérer la réponse.
- Initialiser chaque variable de la structure d'appel.
Important : l'ordre d'affectation des variables est repris dans le XML généré dans la requête SOAP. Il est donc nécessaire d'affecter les variables dans l'ordre indiqué dans la documentation de la fonction du webservice. - Appeler la fonction du Webservice en passant en paramètre la variable d'appel et récupérer en retour la variable de réponse.
Exemple :
trackingSearch est un trackSearch
trackingSearchRes est un resultTrackSearch
trackingSearch.accountNumber = 99999999
trackingSearch.consigneesCountry = "FR"
trackingSearch.consigneesZipCode = "37100"
trackingSearch.sendersRef = "111111"
trackingSearchRes = TrackingServiceWSService.trackSearch(trackingSearch)
SI ErreurDétectée() ALORS
Trace("Echec de l'appel au service Web : " + ErreurInfo(errComplet))
SINON
Trace("Webservice correctement exécuté")
FIN
Le résultat renvoyé par le Webservice est généralement au format XML. Il est donc nécessaire d'utiliser et de connaître les fonctions XML pour décoder la réponse. Comment écrire dans l'entête HTTP d'un appel à un Webservice SOAP ? Pour écrire dans l'entête HTTP d'un appel à un Webservice SOAP : - Déclarer une variable de type wsRequête.
- Utiliser la propriété EntêteHTTP pour définir les valeurs d'entête.
- Appeler la procédure du webservice en spécifiant en 1er paramètre le nom de la variable de type wsRequête.
Exemple :
C est un wsRequête
C.EntêteHTTP["cle"] = "Valeur"
ProcWebService(C, param1_WS, param2_WS)
Trace(C.SourceXML)
Appel asynchrone d'un Webservice Dans certains cas, le temps d'exécution de la demande au Webservice peut être long et bloquant. Il peut être nécessaire de faire un appel asynchrone au Webservice, en utilisant la syntaxe suivante :
APRES <Résultat> = <Procédure d'appel au Webservice> FAIRE
<Code exécuté uniquement lorsque le Webservice aura été exécuté et aura envoyé la réponse>
FIN
<Code exécuté directement après l'appel du Webservice> Grâce à cette syntaxe, l'appel au Webservice n'est pas bloquant. Le programme continue de s'exécuter même si le Webservice n'a pas encore répondu. L'exemple précédent devient :
trackingSearch est un trackSearch
trackingSearchRes est un resultTrackSearch
trackingSearch.accountNumber = 99999999
trackingSearch.consigneesCountry = "FR"
trackingSearch.consigneesZipCode = "37100"
trackingSearch.sendersRef = "111111"
APRÈS trackingSearchRes = TrackingServiceWSService.trackSearch(trackingSearch) FAIRE
SI ErreurDétectée() ALORS
Trace("Echec de l'appel au service Web : " + ErreurInfo(errComplet))
SINON
Trace("Webservice correctement exécuté")
FIN
FIN
Pour plus de détails, consultez Instruction APRES. Propriétés associées au Webservice Pour manipuler un Webservice par programmation, il suffit d'utiliser le nom du Webservice (présent dans le volet "Explorateur de projet"). Remarque : Il est possible de faire un glisser-déposer directement depuis le volet "Explorateur de projet" vers l'éditeur de code pour insérer le nom du Webservice. Les propriétés modifiables par programmation sont : | | | | Nom | Type manipulé | Effet |
|---|
| Adresse | Chaîne de caractères | Permet de remplacer l'adresse d'appel du Webservice décrite dans le WSDL par une autre URL. Cette propriété est notamment utile si le Webservice est hébergé sur des serveurs différents. Cette propriété est de la forme : "http://serveur:port/chemin_du_webservice". Dans le cas d'un Webservice généré avec WINDEV et déployé sur un Serveur d'Application WEBDEV, il s'agit de l'URL du fichier d'extension "awws". Remarques : - La modification de cette propriété remplace toutes les URL décrites dans le WSDL.
- Si cette propriété correspond à une chaîne vide (""), les URL décrites dans le WSDL seront de nouveau utilisées.
| | Constante de type entier | Permet de forcer la méthode d'authentification HTTP : - auAutomatique (valeur par défaut) : méthode d'authentification automatique.
- auBasic : méthode d'authentification Basic.
- auNegotiate : méthode d'authentification Negotiate.
| | IgnoreErreur | Combinaison de constantes | Permet d'ignorer les erreurs de certificat. les constantes utilisables sont les suivantes :- httpIgnoreCertificatInvalide : Permet d'ignorer un certificat invalide ou ne provenant pas d'une société connue.
- httpIgnoreNomCertificatInvalide : Permet d'ignorer le nom du site figurant dans le certificat.
- httpIgnoreCertificatExpiré : Permet d'ignorer la date du certificat.
- httpIgnoreRenvoiHTTP : Permet le renvoi vers un serveur non sécurisé.
- httpIgnoreRenvoiHTTPS : Permet le renvoi vers un serveur sécurisé.
- httpIgnoreRévocation : Permet d'ignorer le contrôle dans la liste des certificats révoqués.
Remarques :  Les erreurs concernant la sécurité des transactions sont ignorées. La propriété IgnoreErreur n'est pas disponible.  Seules les erreurs suivantes sont gérées : httpIgnoreCertificatExpiré, httpIgnoreCertificatInvalide, httpIgnoreNomCertificatInvalide, httpIgnoreRévocation. Les autres erreurs sont ignorées. Par défaut, pour compatibilité, toutes les erreurs sont ignorées.
| | MéthodeHTTP | Constante de type Entier | Méthode HTTP utilisée pour appeler le Webservice :- httpPost (valeur par défaut) : Méthode POST
- httpPut : Méthode PUT
Non disponible.
| | MotDePasse | Chaîne de caractères | Mot de passe utilisé pour réaliser l'authentification lors des requêtes HTTP au Webservice. Ce nom est utilisé uniquement dans le cas où une authentification est nécessaire pour accéder au serveur sur lequel est hébergé le Webservice. | | Port | Chaîne de caractères | Nom du port défini dans le WSDL. Il s'agit du port utilisé pour communiquer avec le serveur hébergeant le Webservice. Consultez votre administrateur réseau ou le propriétaire du Webservice. | | Utilisateur | Chaîne de caractères | Nom d'utilisateur utilisé pour réaliser l'authentification lors des requêtes HTTP au Webservice. Ce nom est utilisé uniquement dans le cas où une authentification est nécessaire pour accéder au serveur sur lequel est hébergé le Webservice.
Avec la méthode d'authentification Negotiate, suivant la configuration il faut ajouter à l'utilisateur le domaine : monWebservice..Utilisateur = "DOMAINE\Utilisateur" monWebservice..Utilisateur = "Utilisateur@DOMAINE" | | VersionHTTP | Constante de type Entier | Version du protocole HTTP utilisée par le serveur : - httpVersion2 : Protocole HTTP version 2.0. Si le serveur ne gère pas cette version, une version plus ancienne est utilisée.
- httpVersion2Uniquement : Protocole HTTP version 2.0 forcée : si le serveur ne gère pas cette version, une erreur fatale est affichée.
- httpVersion1_1 : Protocole HTTP version 1.1.
- httpVersion1_0 : Protocole HTTP Version 1.0.
- httpVersionDéfaut : Protocole HTTP Version 1.0.
|
Remarque : - Si un nom d'utilisateur et un mot de passe sont spécifiés, l'authentification des requêtes HTTP se fera en utilisant le schéma d'authentification "Basic", dans lequel les paramètres sont en clair dans la requête HTTP. Il est préférable d'utiliser des requêtes HTTPS si l'authentification est nécessaire.
- Si le serveur qui héberge le Webservice nécessite une authentification Windows en HTTP, il faut utiliser la fonction HTTPParamètre avant de consommer le Webservice (afin d'utiliser Internet Explorer pour les requêtes HTTP).
- Le temps maximum d'attente de la réponse peut être précisé avec la fonction HTTPTimeout.
Attention : Les propriétés modifiables dans l'éditeur et les propriétés modifiables par programmation n'ont pas de lien. Propriétés disponibles sur les types de variables Les types de variables déclarés automatiquement lors de l'importation du WSDL offrent un certain nombre de propriétés : | | | | Nom | Type manipulé | Effet |
|---|
| Existe | Booléen | - Vrai si le type de variable existe dans la réponse du Webservice,
- Faux dans le cas contraire.
| | Occurrence | Entier | Nombre d'éléments de ce type dans la réponse du Webservice. Un Webservice peut retourner des tableaux de variables. La propriété Occurrence permet de connaître la taille du tableau renvoyée et l'opérateur [ ] permet d'accéder aux éléments du tableau. | | Type | Chaîne de caractères | Nom du type de la variable. Cette propriété est utilisée lorsqu'un Webservice est susceptible de retourner des réponses de différents types. | | Valeur | Variant | Valeur de la variable.Remarque : Cette propriété est accédée par défaut lorsque seul le nom de la variable est utilisé. Par exemple :
monWebservice.VariableRequete = SAI_Valeur
est équivalent à :
monWebservice.VariableRequete..Valeur = SAI_Valeur
|
Manipulation avancée du flux XML du Webservice Dans certains cas, il est nécessaire de manipuler précisément le flux de données XML échangé avec le Webservice. Certains Webservices demandent par exemple d'ajouter des entêtes dans leur flux XML pour permettre l'authentification ou retournent des meta informations dans les entêtes de la réponse. Pour répondre à ces demandes particulières, les fonctions suivantes peuvent être utilisées : | | | SOAPAjouteAttribut | Déclare des attributs supplémentaires (non présent dans le WSDL) sur une variable de Webservice générée automatiquement. Elle est utilisée en programmation avancée dans les cas où le WSDL renvoyé par le Webservice ne correspond pas complètement au type attendu. | | SOAPAjouteEntête | Ajoute des entêtes personnalisés dans un appel de Webservice. | | SOAPPrépare | Construit la requête au Webservice pour une fonction et des paramètres donnés mais n'envoie pas la requête. | | SOAPRécupèreEntête | Relit les informations présentes dans l'entête de la réponse d'un Webservice. |
Cas particulier : le Webservice renvoie un résultat dans un type non reconnu par WINDEV, WEBDEV et WINDEV Mobile Les types de variables disponibles dans WINDEV et ceux disponibles dans un Webservice de type SOAP peuvent être différents. Les types simples (booléen, entier, etc.) et complexes (dateheure, durée, structures, tableaux de types simples et de structures, structures imbriquées, etc.), utilisés dans le Webservice sont automatiquement convertis au format du WLangage (et inversement) lors de l'importation du service dans un projet. Les types Tableaux sont également gérés. Les types plus évolués (classes, types avancés du WLangage, etc.) sont traités en tant que chaînes de caractères dans le code WLangage. Ces chaînes de caractères contiennent le code XML correspondant au type de variable renvoyé par le Webservice et à son contenu. Ainsi, si un Webservice renvoie un résultat sous forme d'instance de classe, ce résultat sera traité dans la procédure comme une chaîne de caractères au format XML. Il sera ensuite nécessaire de traiter cette chaîne de caractères (en WLangage) pour en extraire les informations voulues. Pour plus de détails, consultez les fonctions XML. Remarques : - Si le Webservice retourne une structure, le nom des membres de la structure de retour est sensible à la casse.
- Si vous utilisez une structure en paramètre d'une fonction d'un Webservice et si un membre de type DATE n'est pas affecté, l'erreur "La valeur 0000-00-00 ne respecte pas le schéma XSD" sera affichée.
Distribuer une application WINDEV qui utilise un Webservice Pour distribuer une application qui utilise un Webservice, il suffit d'intégrer le fichier décrivant le Webservice (fichier .wdsdl) dans la bibliothèque de l'application. Pour que l'application puisse exécuter le Webservice, le poste des utilisateurs finaux doit disposer d'un accès à Internet. Remarque : Avant de distribuer une application qui utilise un Webservice, il est conseillé de vérifier la licence d'utilisation et les droits d'utilisation de ce service (cas des services payants).
Liste des exemples associés :
|
Exemples didactiques (WINDEV) : WD Client Webservice
[ + ] Cet exemple illustre l'utilisation des WebServices. Il montre comment récupérer, à partir d'un WebService, des images en fonction de mots clés. Ce projet est le client qui se connecte au WebService "WD Serveur Webservice".
|
|
Exemples didactiques (WINDEV) : WD Serveur Webservice
[ + ] Cet exemple illustre l'utilisation des WebServices. Il montre comment créer un WebService fournissant des images en fonction de mots clés. Ce projet est le WebService qui est utilisé par le projet WD Client Webservice.
|
Documentation également disponible pour…
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|