Lecture d'une requête SOAP complète

En cas de besoin, la section HTTP originale de la requête peut être reconstruite avec le code suivant :

   ` ---------------------------------------
C_TEXTE($headers_t)
$headers_t:=""
LIRE ENTETE HTTP($headers_t)
   ` ---------------------------------------

Journaliser, étudier et déboguer les messages SOAP constituent d’excellentes applications des techniques présentées dans cette note. Ci-dessous, nous décrivons quelques situations spécifiques où l’accès direct au message SOAP entrant peut se révéler utile, voire indispensable.

· Il est plus facile de résoudre des problèmes relatifs à des requêtes de Services Web en regardant le message SOAP complet. De cette façon, il est possible de déterminer si le problème provient d’appels à DECLARATION SOAP inadéquats ou manquants, de requêtes malformées d’un service Web distant, ou d’un comportement inattendu du système de traduction automatique de 4e Dimension. La capture d’entrées SOAP dans 4e Dimension est une technique de débogage utile, mais ne remplace pas toujours la capture de paquets réseau avant qu’ils n’atteignent 4e Dimension. Pour plus d’information, nous vous renvoyons à l'ouvrage « 4D Web Companion » ou à la Note Technique 4D-200308-22-FR « Détecter et suivre un problème TCP/IP ».

· Le journal du serveur Web de 4e Dimension comprend la même entrée pour toutes les requêtes vers le Service Web, comme dans l’extrait ci-dessous :

209.238.253.9 - - [23/Dec/2003:17:04:31 +1100] "POST /4DSOAP/ HTTP/1.1" 200 632

Si un système nécessite de l’information plus détaillée, du code dédié peut extraire et rassembler de l’information depuis les entêtes HTTP ou le message SOAP, par exemple le nom de la méthode appelée.

Nous allons maintenant nous intéresser à un exemple de code créant une journalisation sur mesure des requêtes SOAP.

Dans cet exemple, le système journalise plusieurs informations pour chaque requête SOAP : l’heure, la date, l’adresse IP du client, le nom de la méthode 4e Dimension et le logiciel utilisé comme user-agent (navigateur/client). La méthode base Sur authentification Web s’exécute une fois pour chaque requête au service Web, elle constitue donc l’emplacement logique pour journaliser les requêtes SOAP.

Le code ci-dessous appelle la méthode soap_LogRequest pour exécuter la tâche d’extraction et d’enregistrement des informations de la requête :

   ` ---------------------------------------
   `Méthode Base : Sur Authentification Web

C_BOOLEEN($0;$allowRequest_b)
C_TEXTE($1) ` URL
C_TEXTE($2) ` requête HTTP (entête + corps)
C_TEXTE($3;$clientAddress_t) ` adresse IP Client
C_TEXTE($4;$serverAddress_t) ` adresse IP Serveur
C_TEXTE($5;$userName_t) ` nom Utilisateur
C_TEXTE($6) ` Mot de passe

$clientAddress_t:=$3
$serverAddress_t:=$4
$userName_t:=$5

$allowRequest_b:=Vrai

   `la routine ci-dessous montre comment utiliser une requête complète SOAP entrante
Si (Est une requete SOAP)
      ` Enregistrer la requête complète et les entêtes dans un enregistrement
   soap_SaveRequest ("Sur authentification Web")
      ` Extrait et enregistre les valeurs spécifiques dans un enregistrement
   soap_LogRequest ($clientAddress_t;$serverAddress_t;$userName_t)
Fin de si

$0:=Vrai
   ` ---------------------------------------

La méthode soap_LogRequest, reproduite ci-dessous, enregistre les informations générales de la requête, aussi bien que l’entête HTTP User-Agent et le nom de la méthode appelée comme service Web.

   ` ---------------------------------------
   ` soap_LogRequest

C_TEXTE($1;$clientAddress_t)
C_TEXTE($2;$serverAddress_t)
C_TEXTE($3;$userName_t)

$clientAddress_t:=$1
$serverAddress_t:=$2
$userName_t:=$3

Si (Est une requete SOAP)

      ` ---------------------------------------
      ` Installe la gestion d'erreurs
      ` ---------------------------------------
   C_ENTIER LONG(Error)
   Error:=0
   APPELER SUR ERREUR("demo_TraceErrors") ` Ouvre le débogueur en cas d'erreurs

      ` ---------------------------------------
      `Récupère les entêtes HTTP et extrait les valeurs souhaitées
      ` ---------------------------------------
   TABLEAU TEXTE($httpNames_at;0)
   TABLEAU TEXTE($httpValues_at;0)
   LIRE ENTETE HTTP($httpNames_at;$httpValues_at)
   C_ENTIER LONG($index)
   $index:=Chercher dans tableau($httpNames_at;"User-Agent") ` User-Agent signifie "navigateur" ou
      ` "application cliente"
   C_TEXTE($userAgent_t)
   Si ($index>0)
      $userAgent_t:=$httpValues_at{$index}
   Sinon
      $userAgent_t:=""
   Fin de si

      ` ---------------------------------------
      `Récupère la requête complète SOAP et extrait les valeurs désirées
      ` ---------------------------------------
   C_TEXTE($soapRequest_t)
   $soapRequest_t:=soap_GetFullRequest

      `S'il s'agit d'une requête SOAP, les éléments sont organisés de la manière suivante :
      ` <SOAP-ENV:Envelope
      ` <SOAP-ENV:Body
      ` <nom de la méthode
      `Le code ci-dessous navigue à travers cette structure et extrait le nom de la méthode
   C_ALPHA(16;$xmlroot;$xmlref)
   $xmlroot:=Analyser variable XML($soapRequest_t) ` SOAP-ENV:Envelope
   $xmlref:=$xmlroot ` Préserve la référence originale à l'arbre XML pour la repasser à FERMER XML
   $xmlref:=Lire premier element XML($xmlref) ` SOAP-ENV:Body
   $xmlref:=Lire premier element XML($xmlref) ` Nom de la méthode

   C_TEXTE($methodName_t)
   $methodName_t:=""
   LIRE NOM ELEMENT XML($xmlref;$methodName_t)
   FERMER XML($xmlroot)

      `Le nom de la méthode peut être préfixé par un alias de namespace (espace de noms)
      `, comme ceci :
      ` mns:ConvertFeetToMeters
      `La seule utilisation possible des ":" dans les noms XML s'applique aux préfixes de namespaces
      `Le code suivant cherche ":" et s'il les retrouve, retire le préfixe du namespace. `
   C_ENTIER LONG($index)

   $index:=Position(":";$methodName_t)
   Si ($index>0)
      $methodName_t:=Sous chaine($methodName_t;$index+1)
   Fin de si

      ` ---------------------------------------
      ` Enregistrement des données
      ` ---------------------------------------
      `Cette démo journalise dans un enregistrement, vous pouvez préférer utiliser un
      `autre emplacement, comme un document
   CREER ENREGISTREMENT([Logged_SOAP_Request])
   [Logged_SOAP_Request]ID:=Numerotation automatique([Logged_SOAP_Request])
   [Logged_SOAP_Request]Request_Date:=Date du jour(*)
   [Logged_SOAP_Request]Request_Time:=Heure courante(*)
   [Logged_SOAP_Request]Client_IP:=$clientAddress_t
   [Logged_SOAP_Request]Server_IP:=$serverAddress_t
   [Logged_SOAP_Request]User_Name:=$userName_t
   [Logged_SOAP_Request]Method_Name:=$methodName_t
   [Logged_SOAP_Request]User_Agent:=$userAgent_t
   STOCKER ENREGISTREMENT([Logged_SOAP_Request])

      ` ---------------------------------------
      ` Désactivation de la gestion d'erreurs
      ` ---------------------------------------
   APPELER SUR ERREUR("")

Fin de si ` (Est une requete SOAP)
   ` ---------------------------------------

Si vous êtes intéressés par la construction d’un système de journalisation des requêtes SOAP dans un environnement de production, voici quelques suggestions d’implémentations :

• conserver le code s’exécutant en réponse au service Web, ainsi qu’aux requêtes Web aussi rapide que possible.
• le code proposé ci-dessus peut être remodelé et amélioré pour une meilleure flexibilité.
• cet exemple enregistre les données du journal dans des enregistrements principalement parce qu’il est plus facile de le coder de cette manière ! En environnement de production, l’écriture dans des documents disques est à considérer sérieusement.
• dans un système reposant sur 4D Server, réfléchissez à enregistrer les requêtes entrantes dans des enregistrements au lieu d’extraire les données dans le process gérant la requête au Service Web. Un process spécifique ou un client dédié peut être programmé pour examiner périodiquement les enregistrements sauvés et extraire l’information désirée afin de l’inclure dans les enregistrements d’un fichier de journalisation. C’est une stratégie particulièrement intéressante lorsque le serveur Web s’exécute sur un ou plusieurs 4D Clients et qu’en conséquence le fichier de journalisation doit être consolidé sur une machine.

Une autre application de la technique décrite dans cette note technique est de lire des valeurs d’un message SOAP qui ne sont pas déclarées par DECLARATION SOAP. Par exemple, la méthode ConvertFeetToMeters reproduite plus haut pourrait accepter un argument optionnel spécifiant la précision de l’arrondi. Le fragment XML ci-dessous montre à quoi ressemble la requête XML avec un nouveau champ nommé inRoundTo (en gras pour la mise en évidence) :

<mns:ConvertFeetToMeters xmlns:mns="http://www.4d.com/namespace/default">
<inFeet xsi:type="xsd:float">100</inFeet>
<inRoundTo xsi:type="xsd:float">3</inRoundTo>
</mns:ConvertFeetToMeters>

En utilisant le système de conversion SOAP automatique de 4e Dimension, la méthode ConvertFeetToMeters n’a pas accès à l’entrée inRoundTo. Si ConvertFeetToMeters requiert toujours un argument d’arrondi, l’approche la plus simple est de déclarer l’entrée en tant que paramètre de la méthode ou variable process et de la définir comme entrée SOAP à l’aide de DECLARATION SOAP, comme dans le fragment de code ci-dessous :

   ` ---------------------------------------
C_ENTIER LONG($2)
…
DECLARATION SOAP ($2 ;Est un entier long ;"inroundTo")
   ` ---------------------------------------

Étant donné la facilité de déclaration des entrées SOAP, pourquoi les développeurs se trouveraient-ils dans l’obligation de traiter les entrées – ou certaines entrées – SOAP manuellement ?


Voici quelques raisons :

• en utilisant le système de conversion automatique de 4e Dimension, il n’existe aucun moyen de distinguer entre les messages qui n’incluent pas l’entrée et ceux qui incluent une valeur par défaut pour le type. Par exemple, en utilisant le système automatique, le paramètre $2 ci-dessus vaut 0 si inRoundTo est soumis avec une valeur de 0 ou si inRoundTo n’est pas passé du tout ;
• le système automatique de 4e Dimension demande d’associer les entrées avec des paramètres de méthodes, des variables process ou des tableaux process. En outre, toute variable process ou tableau lié à une entrée SOAP doit être déclaré dans la méthode Compiler_Web, ou dans une sous-routine appelée par Compiler_Web. La lecture manuelle des messages SOAP permet aux développeurs d’extraire, convertir, et stocker les entrées librement dans des champs, documents locaux, variables et tableaux process ou interprocess. De plus, si le système de traduction automatique n’est pas utilisé, les valeurs n’ont pas besoin d’être déclarées dans Compiler_Web ;
• dans la vie d’un service Web, les listes de paramètres et les déclarations peuvent changer. La lecture directe du message révèle exactement quels paramètres ont été envoyés. Il devient alors plus facile de supporter des listes de paramètres multiples pour une même méthode, ou de renvoyer une faute SOAP intelligemment lorsque le client SOAP doit mettre à jour son code.

Le code ci-dessous améliore la méthode ConvertFeetToMeters proposée plus haut en appelant une sous-routine nommée soap_GetRounding qui retourne une valeur d’arrondi depuis le message SOAP ou une valeur d’arrondi par défaut :

   ` ---------------------------------------
C_REEL($0;$meters_r)
C_REEL($1;$feet_r)

DECLARATION SOAP($0;Est un numérique ;SOAP sortie ;"outMeters")
DECLARATION SOAP($1;Est un numérique ;SOAP entrée ;"inFeet")

C_ENTIER LONG($rounding_l)
$rounding_l:=soap_GetRounding

$feet_r:=$1

$meters_r:=$feet_r*0,3048
$meters_r:=Arrondi($meters_r;$rounding_l)

$0:=$meters_r
   ` ---------------------------------------

La seule différence entre la version originale de la méthode ConvertFeetToMeters et la version modifiée consiste dans les trois lignes de code reprises ci-dessous :

   ` ---------------------------------------
C_ENTIER LONG($rounding_l)
$rounding_l:=soap_GetRounding
$meters_r:=Arrondi($meters_r;$rounding_l)
   ` ---------------------------------------

Voici le code de la méthode soap_GetRounding :

   ` ---------------------------------------
C_ENTIER LONG($0;$rounding_l)
$rounding_l:=0

C_TEXTE($xml_t)
$xml_t:=soap_GetFullRequest

C_ALPHA(16;$xmlref)
$xmlref:=Analyser variable XML($xml_t) ` Analyse de l'XML contenu dans une variable texte ou BLOB

C_TEXTE($rounding_t)
$rounding_t:=""

   ` Extrait la valeur de l'élément 'inRoundTo' vers une chaine, si cet élément est trouvé
$rounding_t:=xutil_GetValue ($xmlref;"inRoundTo")

   `Convertit la valeur en nombre (les chaînes vides sont converties en 0)
$rounding_l:=Num($rounding_t)

Si ($rounding_l<=0) `Modif CK
   $rounding_l:=2 ` une valeur négative n'a pas de sens, retour de la valeur par défaut 2
Fin de si

FERMER XML($xmlref) `Toujours faire correspondre un appel à Analyser variable XML
   ` par un appel à FERMER XML
$0:=$rounding_l
   ` ---------------------------------------

La méthode xutil_GetValue retourne la valeur en texte de n’importe quel élément simple XML, s’il existe. Les commandes de navigation XML natives de 4e Dimension ou celles des nombreuses solutions tierces peuvent également s’utiliser.