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

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

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

- Auteur : David Adams

- Parution : 1 mars 2005

- Licence : 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.

Sommaire

- 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

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.

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 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) ».

III - Rappel : Activer les Services Web

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.

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

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.

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

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

1. C_TEXTE($0;$1)

2. $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 :

1. 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 :

1. DECLARATION SOAP(returnLongint_l;Est un entier long ;SOAP sortie ;"outSecondsSinceMidnight")

2. DECLARATION SOAP(returnReal_r;Est un reel;SOAP sortie ;"outPi")

3. DECLARATION SOAP(returnString_s;Est une variable chaîne ;SOAP sortie ;"outServerVersion")

4. returnLongint_l:=Heure courante(*)+0 `Convertit le temps en secondes depuis minuit

5. returnReal_r:=Pi

6. 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 :

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

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

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 :

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) ».

Note 2 : 4e Dimension n'a pas de type distinct pour les valeurs d’heure. À la place, il utilise un tableau d'entiers longs. C'est une caractéristique de longue date du langage de 4e 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 4e 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ées et exécutez les méthodes Client dans une copie de 4e Dimension et les méthodes de Service Web dans une autre copie de 4e 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).

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