Developpez.com - 4D
X

Choisissez d'abord la catégorieensuite la rubrique :


Retourner des données par Service Web (via SOAP)

Date de publication : Mars 2005

Par David Adams
 

Cette note technique traite de la manière de retourner des données au travers d’un service Web et du type des valeurs retournées. Elle fournit également une base de données qui démontre les caractéristiques et le comportement de 4ème Dimension.

I. Introduction
II. Rappel : Web Services, SOAP et XML
III. Rappel : Activer les Services Web
IV. Définir les données retournées
V. Le paramètre de résultat $0
VI. DECLARATION SOAP et les sorties autres que $0
VII. Types de données supportés et sources
VIII. Base de démo
Requêtes et réponse
Configuration des méthodes proxy
Le client peut s'exécuter dans une copie distincte de 4D
Numéros de port
IX. Notes et rappels sur DECLARATION SOAP
X. Bases exemples


I. Introduction

4ème Dimension version 2003 et ultérieures propose la publication de méthodes en tant que Services Web. Une même méthode peut souvent être appelée à la fois localement depuis la base de données et à distance comme Service Web sans codage ou modification spécifique.

Cependant, les méthodes publiées comme Services Web présentent plus de souplesse dans leur retour d'arguments que lorsqu'elles sont appelées localement par une autre méthode 4D. Au lieu d'être limitées au paramètre de retour $0, les méthodes peuvent retourner ce $0, mais également n'importe quelle combinaison de variables et de tableaux process. Le retour de valeurs multiples avec SOAP est comparable au retour d’un enregistrement complet au lieu d'un simple champ. Cette note technique traite de la manière de retourner des données au travers d'un Service Web et du type des valeurs retournées. Elle fournit également une base de données qui démontre les caractéristiques et le comportement de 4ème Dimension.


II. Rappel : Web Services, SOAP et XML

En interne, les requêtes et réponses des méthodes de Service Web utilisent des messages SOAP (Simple Object Access Protocol) envoyés par l'intermédiaire du serveur Web natif de 4ème Dimension. Les messages SOAP, et les données qu'ils contiennent suivent les règles syntaxiques et les restrictions d’XML.

4ème Dimension s'acquitte automatiquement de toutes ces tâches :

   · Recevoir des messages entrants SOAP ;
   · Convertir les types de données XML en types de données 4ème Dimension ;
   · Exécuter les contrôles de sécurité ;
   · Aiguiller la requête SOAP vers la bonne méthode projet 4ème Dimension ;
   · Lier les valeurs 4ème Dimension aux valeurs XML ;
   · Convertir les valeurs 4ème Dimension en valeurs XML ;
   · Formater et envoyer la réponse SOAP.


Ces process sont invisibles pour nous développeurs 4ème Dimension, ils fonctionnent et c'est tout ! Cependant, lorsque nous développons et mettons au point des Services Web, nous devrions nous familiariser avec les messages SOAP sous-jacents.

Cette note technique inclut les structures XML des messages SOAP afin d'en illustrer le comportement et d'en montrer les caractéristiques. Aucune de ces fonctionnalités, cependant, ne requiert de manipuler directement du XML. Pour plus d'information sur la façon de capturer et d'examiner les messages SOAP, reportez-vous au 4D Web Companion, ou à la Note Technique 4D-200308-22-FR "Détecter et suivre un problème TCP/IP (partie 1)".


III. Rappel : Activer les Services Web

Afin de publier des méthodes comme Services Web, les conditions suivantes sont requises :
  1. le serveur natif 4ème Dimension doit être démarré et accessible ;

  2. la préférence suivante de la base de données doit être activée :
    Préférences -> Web->Web Services -> Autoriser requêtes Web Services ;

  3. La propriété de méthode suivante doit être activée pour chaque méthode publiée :
    Propriétés de la méthode -> Offert comme Web Service

IV. Définir les données retournées

4ème Dimension procure deux manières de spécifier les données retournées par une réponse SOAP :
  • Le paramètre $0 de n’importe quelle méthode offerte comme Web service peut être inclus automatiquement comme sortie. Aucune programmation spécifique n’est nécessaire.

  • Les variables et tableaux process peuvent être liés aux paramètres de sortie en utilisant la commande DECLARATION SOAP.

V. Le paramètre de résultat $0

Ce code retourne dans $0 le texte reçu dans $1 :

   `--------------------
C_TEXTE($0;$1)
$0:=$1
   `--------------------


En dépit de la simplicité du code ci-dessus, il illustre la facilité de publication d'un Service Web. Ci-dessous se trouve la structure XML de la réponse SOAP correspondant à un appel à cette méthode en lui passant le texte "Hello world !" (interlignes et espaces rajoutés pour plus de clarté) :
<?xml version="1.0" encoding="UTF-8" ?>								
<SOAP-ENV:Envelope

	SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	
<SOAP-ENV:Body>
				
	<ns1:returnInputTextResponse
	xmlns:ns1="http://www.4d.com/namespace/default"
	SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
						
		<FourD_arg0 xsi:type="xsd:string">Hello world!</FourD_arg0>
							
	</ns1:returnInputTextResponse>
					
</SOAP-ENV:Body>

</SOAP-ENV:Envelope>


Comme décrit dans la référence du langage de 4ème Dimension, la valeur de $0 est retournée dans l’élément XML nommé FourD_Arg0. La commande DECLARATION SOAP permet de modifier le nom de l’élément XML dans la sortie, comme dans l’exemple ci-dessous :

   `--------------------
DECLARATION SOAP($0 :Est un texte ;SOAP sortie ; "outEchoInputString")
   `--------------------


Le fragment XML ci-dessous illustre la manière dont DECLARATION SOAP modifie la réponse SOAP :
<outEchoInputString xsi:type="xsd:string">Hello world!</outEchoInputString>


Définir des noms d’éléments XML clairs et descriptifs n’est que l'une des applications de la commande DECLARATION SOAP. Comme nous l'exposerons plus loin, c’est grâce aux appels à DECLARATION SOAP qu'une méthode peut retourner plusieurs valeurs, variables et tableaux y compris.


VI. DECLARATION SOAP et les sorties autres que $0

La commande DECLARATION SOAP peut être appelée plusieurs fois à l’intérieur d’une méthode pour définir de multiples paramètres d’entrée et de sortie. Le code ci-dessous définit trois variables process à retourner dans une seule réponse SOAP :

   `--------------------
DECLARATION SOAP(returnLongint_l;Est un entier long ;SOAP sortie ;"outSecondsSinceMidnight")
DECLARATION SOAP(returnReal_r;Est un reel;SOAP sortie ;"outPi")
DECLARATION SOAP(returnString_s;Est une variable chaîne ;SOAP sortie ;"outServerVersion")
returnLongint_l:=Heure courante(*)+0 `Convertit le temps en secondes depuis minuit
returnReal_r:=Pi
returnString_s:="Version #"+Version application
   `--------------------


Les appels à DECLARATION SOAP listés ci-dessous lient des valeurs 4ème Dimension à des éléments de sortie, comme récapitulés dans le tableau ci-dessous :

Objet 4ème Dimension Nom d'élément XML
returnLongint_l outSecondsSinceMidnight
returnReal_r outPi
returnString_s outServerVersion


Les noms d'éléments retournés et leurs valeurs sont surlignés dans la structure XML de la réponse SOAP ci dessous:
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
<ns1:returnThreeResultsResponse
xmlns:ns1="http://www.4d.com/namespace/default"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<outSecondsSinceMidnight xsi:type="xsd:float">40174</outSecondsSinceMidnight>
<outPi xsi:type="xsd:float">3,141592653589793116</outPi>
<outServerVersion xsi:type="xsd:string">Version #0703</outServerVersion>
</ns1:returnThreeResultsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Un nombre indéfini de valeurs 4ème Dimension peuvent être incluses dans la réponse SOAP, dans la limite des ressources disponibles et des restrictions propres aux types de données supportés. La capacité de retourner plusieurs valeurs depuis une seule méthode - y compris des tableaux complets - procure une bien plus grande flexibilité que le seul paramètre de retour $0 de 4ème Dimension.


VII. Types de données supportés et sources

Les valeurs de sortie SOAP peuvent provenir d'un paramètre de retour $0, de variables process et de tableaux process, comme récapitulés dans le tableau ci-dessous :

Source supporté
$0 Oui
Expression Non
Champs Non
Tableaux interprocess Non
Variables interprocess Non
Littéraux Non
Tableaux locaux Non
Variables locales Non
Paramètres autres que $0 Non
Tableaux process Oui
Variables process Oui


4ème Dimension traduit automatiquement et en toute transparence les types de données 4D en types SOAP, en utilisant les conversions listées dans le tableau ci-dessous :

info Note 1 : les données de type image peuvent être envoyées après conversion en BLOB, comme le montre la base de démo accompagnant cette note. Cette technique est détaillée dans la Note Technique 4D-200503-09-FR "Retourner des images par Web Services (via SOAP)".
info Note 2: 4ème Dimension n'a pas de type distinct pour les valeurs d’heure. A la place, il utilise un tableau d'entiers longs. C'est une caractéristique de longue date du langage de 4ème Dimension qui n'a pas changé pour les Services Web.

VIII. Base de démo


Requêtes et réponse

La base exemple accompagnant cette note consiste en une série de méthodes simples illustrant la manière d'envoyer chacun des types de variables et de tableaux supportés par SOAP, aussi bien que la manière d'envoyer des valeurs multiples. Les noms de méthodes listés sur la gauche représentent les méthodes de Service Web qui retournent des données, et les noms de méthodes listés à droite sont les méthodes Client SOAP correspondantes qui récupèrent les données. Les formulaires de démo fournissent un système simple à utiliser pour exécuter les méthodes Client.

Méthode de Service Web Méthode de client proxy
returnBlobVariable request_BlobVariable
returnBooleanArray request_BooleanArray
returnBooleanVariable request_BooleanVariable
returnDateArray request_DateArray
returnDateVariable request_DateVariable
returnInputText request_InputText
returnIntegerArray request_IntegerArray
returnIntegerVariable request_IntegerVariable
returnLongintArray request_LongintArray
returnLongintVariable request_LongintVariable
returnPictureVariable request_PictureVariable
returnRealArray request_RealArray
returnRealVariable request_RealVariable
returnStringArray request_StringArray
returnStringVariable request_StringVariable
returnTextArray request_TextArray
returnTextVariable request_TextVariable
returnThreeResults request_ThreeResults
returnTimeArray request_TimeArray
returnTimeVariable request_TimeVariable
   

Configuration des méthodes proxy

Les méthodes proxy SOAP de 4ème Dimension précisent directement l'URL d’appel du Web service.

Dans le cas de cet exemple, les méthodes appellent l'adresse de loopback (la machine courante) à http://127.0.0.1/.

Au lieu de coder en dur cette adresse dans chaque méthode, les méthodes proxy appellent une méthode nommée requestGetAccessURL qui retourne l'adresse correcte. Pour indiquer aux méthodes Client d’utiliser une adresse de serveur différente, il suffit d'ajuster la ligne de code qui se trouve dans la méthode requestGetAccessURL.

Dans un système de production, l'URL du serveur SOAP cible pourrait être stockée dans d’autres emplacements, des enregistrements, des énumérations, des ressources, afin de faciliter la maintenance.


Le client peut s'exécuter dans une copie distincte de 4D

Les méthodes Client et les méthodes de Service Web sont fournies dans une seule base par commodité.

Pour créer un environnement de déploiement de Service Web plus typique, dupliquez la base de donnée et exécutez les méthodes Client dans une copie de 4ème Dimension et les méthodes de Service Web dans une autre copie de 4ème Dimension.

Assurez-vous de désactiver le serveur Web dans la copie de la base fonctionnant en client.


Numéros de port

La base exemple est configurée par défaut pour écouter les requêtes Web - y compris les requêtes Web service - sur le port 8080. Vous pouvez fixer ce numéro de port sur n’importe quel port disponible et autorisé par votre OS (1).

info Note : Compiler_Web

La méthode projet Compiler_Web peut être source de confusion pour les développeurs débutant dans l'emploi des fonctionnalités Web et Service Web de 4ème Dimension. La méthode Compiler_Web lie automatiquement les valeurs des formulaires Web et des requêtes SOAP aux variables et tableaux process. Les valeurs utilisées comme sortie n'ont pas besoin d’être déclarées dans la méthode Compiler_Web.

IX. Notes et rappels sur DECLARATION SOAP

Ci-dessous des notes importantes et des rappels sur l’utilisation de DECLARATION SOAP :
  • La commande DECLARATION SOAP doit s’appeler directement depuis la méthode appelée en tant que Service Web, et non dans une sous-routine.

  • Les noms d'éléments XML sont soumis à des restrictions par rapport aux caractères spéciaux, tout particulièrement les espaces. Assurez-vous de fournir des noms XML corrects à la commande DECLARATION SOAP.

  • La commande DECLARATION SOAP n'a pas de relation avec les déclarations de compilation Dimension. Les variables, paramètres et tableaux doivent être déclarés et initialisés normalement.

  • La commande DECLARATION SOAP est ignorée si l'appel de la méthode courante ne provient pas d’un Service Web. Ce comportement permet d'appeler la même méthode localement depuis une autre méthode 4ème dimension.

X. Bases exemples

Téléchargez les bases exemples :

Base 4D 2004

Base 4D 2004 Windows

Base 4D 2003 MacOs



(1) NDT : la version 2004 automatise la publication sur le port 80 de MacOSX.

__________________________________________________
Copyright © 1985-2009 4D SA - Tous droits réservés
Tous les efforts ont été faits pour que le contenu de cette note technique présente le maximum de fiabilité possible.
Néanmoins, les différents éléments composant cette note technique, et le cas échéant, le code, sont fournis sans garantie d'aucune sorte. L'auteur et 4D S.A. déclinent donc toute responsabilité quant à l'utilisation qui pourrait être faite de ces éléments, tant à l'égard de leurs utilisateurs que des tiers.
Les informations contenues dans ce document peuvent faire l'objet de modifications sans préavis et ne sauraient en aucune manière engager 4D SA. La fourniture du logiciel décrit dans ce document est régie par un octroi de licence dont les termes sont précisés par ailleurs dans la licence électronique figurant sur le support du Logiciel et de la Documentation afférente. Le logiciel et sa documentation ne peuvent être utilisés, copiés ou reproduits sur quelque support que ce soit et de quelque manière que ce soit, que conformément aux termes de cette licence.
Aucune partie de ce document ne peut être reproduite ou recopiée de quelque manière que ce soit, électronique ou mécanique, y compris par photocopie, enregistrement, archivage ou tout autre procédé de stockage, de traitement et de récupération d'informations, pour d'autres buts que l'usage personnel de l'acheteur, et ce exclusivement aux conditions contractuelles, sans la permission explicite de 4D SA.
4D, 4D Calc, 4D Draw, 4D Write, 4D Insider, 4ème Dimension ®, 4D Server, 4D Compiler ainsi que les logos 4e Dimension, sont des marques enregistrées de 4D SA.
Windows,Windows NT,Win 32s et Microsoft sont des marques enregistrées de Microsoft Corporation.
Apple, Macintosh, Power Macintosh, LaserWriter, ImageWriter, QuickTime sont des marques enregistrées ou des noms commerciaux de Apple Computer,Inc.
Mac2Win Software Copyright © 1990-2002 est un produit de Altura Software,Inc.
4D Write contient des éléments de "MacLink Plus file translation", un produit de DataViz, Inc,55 Corporate drive,Trumbull,CT,USA.
XTND Copyright 1992-2002 © 4D SA. Tous droits réservés.
XTND Technology Copyright 1989-2002 © Claris Corporation.. Tous droits réservés ACROBAT © Copyright 1987-2002, Secret Commercial Adobe Systems Inc.Tous droits réservés. ACROBAT est une marque enregistrée d'Adobe Systems Inc.
Tous les autres noms de produits ou appellations sont des marques déposées ou des noms commerciaux appartenant à leurs propriétaires respectifs.
__________________________________________________
 



Valid XHTML 1.1!Valid CSS!

Ce document est issu de http://www.developpez.com et reste la propriété exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise à l'obtention préalable de l'autorisation de l'auteur.
Contacter le responsable de la rubrique 4D