Souscrire à un Service Web dans 4D

4D vous permet de souscrire à des Web Services, c’est-à-dire faire appel à des Web Services externes à l’intérieur de vos bases de données. 

A l’aide des Web Services disponibles sur Internet, vous pouvez ajouter facilement de nombreuses fonctions supplémentaires dans vos bases, telles que l’accès aux informations boursières, le suivi de livraison de colis, l’exécution de calculs complexes, etc. La multitude de Web Services publiés permet de satisfaire à la plupart des besoins. 

Vous pouvez également souscrire à des Web Services que vous aurez vous-même publiés dans d’autres bases et ainsi faire communiquer diverses bases de données 4D.

Toute base 4D peut souscrire à un Web Service, il suffit simplement qu’elle soit connectée au réseau Internet.

Pour pouvoir faire appel à un Web Service, vous devez en général suivre les étapes décrites ci-dessous : 

1. Récupérez l’URL du Web Service auquel vous souhaitez souscrire.
   Pour cela, vous pouvez utiliser les sites Web recensant les Services Web publiés sur Internet (par exemple http://www.xmethods.net) ou des annuaires tels que UDDI. Dans la plupart des cas, vous devrez obtenir l’URL du fichier WSDL du Service Web.
   Note : 4D peut utiliser des Services Web publiés en mode RPC ou DOC (cf. paragraphe Mode RPC, mode DOC et types composés (ou types complexes)).
2. A l’aide de l’Assistant Web Services, analysez le contenu du WSDL du Web Service à utiliser et générez la méthode proxy correspondante.
   La méthode proxy est la méthode projet locale chargée d’interroger le Web Service et de récupérer les valeurs retournées. Cette étape est détaillée dans le paragraphe ci-dessous.
   Notes :
   
   • Il est possible de créer des méthodes proxy depuis l’Assistant Web Services sans utiliser de fichier WSDL (il suffit de saisir manuellement les paramètres à utiliser).
   • Il est aussi possible de créer des méthodes proxy dans l’éditeur de méthodes sans utiliser l’Assistant Web Services (utilisateurs avancés).
3. Dans le code de votre base, appelez la méthode proxy à chaque fois que vous en avez besoin en lui passant les paramètres adéquats.
   Cette étape est décrite dans le paragraphe Appeler une méthode proxy.

La méthode proxy prend en charge la connexion au Web Service :

La souscription à un Web Service depuis une application 4D est entièrement prise en charge par l’Assistant Web Services. Cet assistant effectue automatiquement :

• l’analyse des fichiers WSDL des Web Services à utiliser,
• la définition des paramètres des méthodes proxy à créer,
• la création des méthodes proxy.

Pour ouvrir la fenêtre de l’Assistant Web Services, choisissez la commande Assistant Web Services... dans le menu Développement de 4D. La fenêtre de l’Assistant apparaît :

Note : Il est possible d’afficher la fenêtre de l’Assistant Web Services depuis le menu d’options de la page Méthodes de l’Explorateur (cf. paragraphe ).

Cette fenêtre comporte trois zones :

• la zone “URL :” vous permet de saisir ou de sélectionner l’URL du fichier WSDL du Web Service choisi. Cette zone est une combo box conservant sous forme de liste déroulante les valeurs précédemment saisies.
• la zone centrale affiche le résultat de l’analyse du contenu du fichier WSDL : noms des services et des méthodes publiées.
• la zone inférieure (“Paramètres avancés”, masquée par défaut) affiche les paramètres de la méthode sélectionnée dans la partie centrale.

Le bouton Découvrir déclenche l’analyse du fichier WSDL désigné et le remplissage des zones d’information.
Le bouton Parcourir affiche une boîte de dialogue standard d’ouverture de fichiers, permettant de sélectionner un fichier WSDL stocké en local. Son chemin d’accès, débutant par “file://” est alors affiché dans la zone “URL :” (il est possible de saisir manuellement le chemin d’accès dans la zone).
Le bouton Créer permet de générer la méthode proxy correspondant au Web Service sélectionné.
Le bouton Fermer referme la boîte de dialogue de l’Assistant Web Services.

L’utilisation type de l’Assistant Web Services consiste à analyser un fichier WSDL puis à générer la ou les méthode(s) proxy correspondante(s). Ce fonctionnement standard est entièrement automatique et ne nécessite aucune programmation ni connaissance particulière de la part de l’utilisateur. 

Pour analyser un fichier WSDL et générer la méthode proxy :

1. Saisissez ou collez dans la zone “URL :” l’URL du fichier WSDL du Web Service que vous souhaitez utiliser :
   
   Cet URL peut, par exemple, provenir d’un “annuaire” de Web Services ou vous avoir été communiqué directement par le serveur du Web Service.
   Vous pouvez également indiquer un URL local, c’est-à-dire l’adresse d’un fichier WSDL stocké sur votre disque dur. Pour cela, cliquez sur le bouton Parcourir... et choisissez le fichier WSDL local, ou saisissez directement son chemin d’accès dans la zone “URL :”. Le chemin d’accès du fichier local débute par “file://” puis utilise le séparateur de dossiers du système. Vous devez passer un chemin d’accès absolu.
2. Cliquez sur le bouton Découvrir afin que 4D analyse le contenu du fichier WSDL.
   Au bout de quelques instants, la zone centrale affiche le résultat de l’analyse du fichier : le nom du ou des Web Service(s) ainsi que de la ou des méthode(s) publiée(s) apparaît sous forme de liste hiérarchique
   
   Note : Vous pouvez afficher directement le code source XML du fichier WSDL dans votre navigateur Web par défaut en maintenant la touche Majuscule enfoncée lorsque vous cliquez sur le bouton Découvrir.
   Vous pouvez cliquer sur un Web Service afin d’afficher sa documentation (si elle existe) à côté de la liste hiérarchique. Le texte “Pas de documentation” apparaît dans le cas contraire.
   De même, la documentation (si elle existe) de chaque méthode apparaît lorsque vous sélectionnez son nom :
   
   Note : Si l’analyse du fichier WSDL fait apparaître la présence de paramètres de type composé, un drapeau jaune  est affiché à côté de la méthode concernée .
3. Sélectionnez la méthode Web Service que vous souhaitez utiliser puis cliquez sur le bouton Créer.
   4D génère instantanément la méthode proxy correspondante et l’affiche dans une fenêtre de l’éditeur de méthodes :
   
   Le nom de la méthode proxy est défini par la concaténation du préfixe par défaut “proxy_” et du nom de la méthode Web Service. Le préfixe par défaut peut être modifié dans la Page Web/Web services des Propriétés de la base. Le nom de la méthode proxy peut également être modifié après sa création, il n’influe pas sur le fonctionnement de la méthode.

Les méthodes proxy générées par l’Assistant Web Service à partir de l’analyse d’un fichier WSDL sont immédiatement opérationnelles et peuvent être utilisées telles quelles (mode standard).

Toutefois, vous pouvez souhaiter modifier les paramètres issus de l’analyse du WSDL. Par exemple, vous pouvez renommer la méthode proxy. 

Vous pouvez également utiliser l’Assistant Web Services pour construire une méthode proxy dont vous aurez saisi manuellement les paramètres. Dans ce cas, vous n’utilisez pas l’analyseur de WSDL.
Il n’est pas obligatoire de saisir tous les paramètres pour pouvoir créer une méthode.
Il est même possible de ne saisir aucun paramètre afin de créer un “modèle” de méthode proxy que vous pourrez remplir ensuite à l’aide du langage de 4D.

Dans ces modes non standard, vous devez utiliser les paramètres avancés de l’Assistant Web Services. Pour afficher ces paramètres, cliquez sur l’icône de déploiement située en bas de la fenêtre de l’Assistant. Si une méthode est sélectionnée, les champs affichent ses paramètres courants :

Tous les paramètres sont modifiables. A noter toutefois que la modification des paramètres issus de l’analyse du WSDL (hormis le nom de la méthode) doit être effectuée avec précaution car le fonctionnement du Web Service peut en être altéré. 

Voici la description des paramètres avancés :

• Nom de la méthode : Nom que l’Assistant donnera à la méthode proxy à créer. Par défaut, ce nom est constitué du préfixe “proxy_” (modifiable dans les Préférences) suivi du nom de la méthode sélectionnée. Ce nom peut être modifié librement (par exemple s’il existe déjà dans la base) sans que cela n’influe sur le fonctionnement du Web Service.
• URL d’accès : URL auquel la méthode proxy adresse les requêtes SOAP.
• SOAP Action : Contenu du champ SOAPAction. Ce champ contient généralement la valeur “NomService#NomMéthode”.
• Espace de nommage : Espace de nommage du Web Service (pour plus d’informations, reportez-vous au paragraphe Personnaliser l’espace de nommage).
• Tableau des paramètres : Ce tableau liste les paramètres de la méthode publiée.
  
  Chaque ligne du tableau décrit un paramètre :
  
  • la première colonne indique si le paramètre est entrant (“in”) ou sortant (“out”). Cette caractéristique est évaluée du point de vue de la méthode proxy, et non de la méthode publiée.
  • la deuxième colonne indique le nom du paramètre.
  • la troisième colonne indique le type SOAP du paramètre. Les différents types SOAP acceptés par 4D peuvent être visualisés dans le menu Type situé dans la zone Propriétés. L’Assistant Web Services se chargera d’associer les types SOAP avec les types 4D correspondants dans la méthode proxy.
    Le tableau suivant décrit les types de valeurs SOAP acceptés et les types 4D correspondants :
           

    Type SOAP	Type 4D correspondant
    boolean	Booléen
    int	Entier long
    time	Heure
    float	Réel
    double	Réel
    date	Date
    string	Texte
    base64Binary	BLOB
    ArrayOfBoolean	Tableau booléen
    ArrayOfInt	Tableau entier long
    ArrayOfTime	Tableau entier long
    ArrayOfFloat	Tableau réel
    ArrayOfDate	Tableau date
    ArrayOfString	Tableau texte
    AsXML	BLOB

    
    Note : Le type AsXML n’est pas un type SOAP à proprement parler mais est utilisé pour la prise en charge des types XML composés (cf. paragraphe Traitement des types composés).
    La zone Propriétés affiche les caractéristiques du paramètre sélectionné dans le tableau. L’Assistant Web Services vous permet de modifier les paramètres existants ou d’ajouter des paramètres, par exemple si le fichier WSDL désigné n’est pas à jour.
    
    • Pour modifier un paramètre, sélectionnez-le puis effectuez vos modifications dans la zone Propriétés.
    • Pour ajouter un paramètre, cliquez sur le bouton Ajouter puis définissez ses caractéristiques dans la zone Propriétés.
    • Pour supprimer un paramètre, sélectionnez-le dans la liste puis cliquez sur le bouton Supprimer.
    Note : Les modifications effectuées dans les paramètres avancés ne seront prises en compte que si une méthode proxy est effectivement créée à l’aide du bouton Créer.

Pour appeler une méthode proxy dans votre code, il suffit d’écrire son nom et de lui passer les paramètres requis. Ces paramètres sont déclarés dans la zone d’en-tête de la méthode proxy par l’Assistant Web Services. Conformément à la syntaxe standard du passage de paramètres entre les méthodes dans 4D, ils sont nommés $0, $1, $2... Ils peuvent être visualisés dans les paramètres avancés de la description de la méthode publiée (cf. paragraphe Utiliser les paramètres avancés) et sont parfois décrits dans sa documentation. 

Par exemple, une méthode proxy appelée WS_EuroConverter pourrait être appelée de la manière suivante :

4D vous permet d’utiliser des Web Services publiés en mode RPC ou DOC et comportant des types composés ou complexes (cf. Mode RPC, mode DOC et types composés (ou types complexes)).

Note : Bien qu’étant des types XML composés, les tableaux de données sont gérés par 4D comme des types simples. 

Les méthodes proxy générées par l’Assistant pour les Services Web comportant des types composés (c’est-à-dire publiés en mode RPC avec type composé ou en mode DOC) sont semblables aux méthodes proxy standard. Vous pouvez toutefois constater dans certains cas qu’avec ces Services Web la commande WEB SERVICE APPELER comporte en paramètre une constante contenant le libellé manuel. 

En effet, l’utilisation de tels Services Web nécessite des traitements supplémentaires. La principale raison en est que les types composés sont échangés sous forme de documents ou éléments xml. Cela signifie que, pour extraire ou inclure des informations dans ces paramètres SOAP, une analyse xml préalable est nécessaire — alors que dans le cas des types simples, les valeurs des paramètres sont directement lisibles.

• Utilisation de types simples (RPC)
  

• Utilisation de types composés (DOC)
  

Seuls les tableaux et les données de type composé sur un niveau (un seul niveau hiérarchique dans la requête SOAP) sont pleinement pris en charge par l’Assistant Web Services. Si des éléments plus complexes sont présents dans la requête, l’Assistant le signalera lors de la découverte du WSDL par un drapeau affiché à côté du nom de la méthode. La prise en charge de ce type de Web Service nécessite généralement des traitements personnalisés de la part du développeur. 

Dans 4D, les paramètres de type composé (hormis les tableaux) sont manipulés sous forme de BLOBs. Les commandes XML de 4D permettent de traiter le contenu de ces BLOBs. Pour plus d’informations, reportez-vous aux thèmes de commandes Web Services (Client) et XML DOM dans le manuel Langage de 4D.