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

4e 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 4e Dimension.

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 4e Dimension. Les messages SOAP, et les données qu'ils contiennent suivent les règles syntaxiques et les restrictions de XML.

4e 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 4e Dimension ;
• exécuter les contrôles de sécurité ;
• aiguiller la requête SOAP vers la bonne méthode projet 4e Dimension ;
• lier les valeurs 4e Dimension aux valeurs XML ;
• convertir les valeurs 4e Dimension en valeurs XML ;
• formater et envoyer la réponse SOAP.

Ces process sont invisibles pour nous développeurs 4e 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) ».

Afin de publier des méthodes comme Services Web, les conditions suivantes sont requises :

1. Le serveur natif 4e 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.

4e 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.

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 4e 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.

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 4e Dimension à des éléments de sortie, comme récapitulés dans le tableau ci-dessous :

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 4e 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 4e Dimension.

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 :

4e 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 :

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▲

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 4e dimension.

Téléchargez les bases exemples :

Base 4D 2004

Base 4D 2004 Windows

Base 4D 2003 MacOs