Code source wiki de Module SOAP

Modifié par jhurst le 2024/04/02 14:25
Afficher les derniers auteurs
1 **Documentation**
2
3 Récupération d’une source de données en interrogeant un service web SOAP
4
5 {{ddtoc/}}
6
7 ----
8
9 (% class="wikigeneratedid" %)
10 = Prérequis =
11
12 * Les acronymes utilisés par la suite sont référencés dans le lexique, à la fin de ce document.
13 * Disposer du dossier **<digdash_installation>/add-ons/soap** contenant l’application web nécessaire à la mise en place des appels vers des Web Services SOAP depuis DigDash. L’installation de cet add-on sera décrit dans ce document.
14 * Avoir en possession la liste des fichiers WSDL correspondant aux Services auxquels nous voudrons faire appel.
15 * Connaître un minimum la structure des requêtes SOAP (en XML) des méthodes à appeler, une documentation du Fournisseur des Services (que DigDash ne fournit pas) peut être nécessaire.
16 * Connaître les formats des valeurs des paramètres des requêtes SOAP à renseigner, une documentation du Fournisseur des Services (que DigDash ne fournit pas) peut être nécessaire.
17
18 |[[image:soap_fr_html_c801e156356d3a0a.png||queryString="width=50&height=50" height="50" width="50"]]
19 |(((
20 DigDash vous propose une aide pour consulter la structure des requêtes SOAP.
21
22 Rendez-vous à l’adresse :
23
24 **<digdash_server>/ddsoap?about=true**
25
26 pour avoir des informations concernant votre configuration SOAP.
27 )))
28
29 = Description =
30
31 == Généralités ==
32
33 DigDash propose la possibilité de récupérer des sources de données en interrogeant des services web SOAP.
34
35 Les échanges SOAP se faisant via des messages au format XML, le but est de pouvoir récupérer les réponses SOAP au format XML du service web et des les utiliser directement en tant que sources de données XML que DigDash sait traiter.
36
37 Pour ce faire, DigDash travaillera principalement avec les interfaces des services web, les fichiers WSDL que vous devrez fournir. Ceux-ci fournissent en effet une description détaillée de ce qu’offrent les services web à appeler.
38
39 DigDash se base sur l’API Java du fameux client SOAP, SOAP UI. La logique et la manière d’interroger le web service souhaité sera assez semblable, dans le sens où il faudra renseigner les valeurs des paramètres des requêtes.
40
41 D’où, comme indiqué en prérequis, la nécessité de connaître un minimum la structure de la requête SOAP au format XML.
42
43 == Description technique ==
44
45 DigDash propose cette fonctionnalité en tant que module (ou add-on) à installer au produit (il n’est pas installé nativement). Il n’y a donc pas de source de données type « web service », mais on utilisera le principe existant dans DigDash des fichiers WLNK pour héberger les informations nécessaires à la récupération des données via SOAP.
46
47 |[[image:soap_fr_html_829eaa34e529ef0c.png||queryString="width=54&height=54" height="54" width="54"]]
48 |(((
49 Un fichier WLNK dans DigDash contient une URL. Le contenu pointé par l'URL est téléchargé par le serveur à chaque fois qu'il en a besoin (pour une source de données ou sur demande d'un utilisateur).
50
51
52 //Pourquoi créer un fichier WLNK ?//
53
54 Nous pourrions créer un simple fichier de source de données XML mais celui-ci ne serait qu’une capture à un instant t des données. Le fichier WLNK permet de rafraîchir les données lorsque nécessaire.
55
56 Il faut aussi prendre en compte qu’un fichier WLNK ne contient que les informations nécessaires à l’appel d’**une seule requête SOAP seulement**.
57
58 ⇒ **Un fichier WLNK = Une requête SOAP**
59 )))
60
61 Dans DigDash, vous ne devrez pas faire appel directement au point d’ entrée du service mais passer par une application web (déployable sur le même serveur Tomcat DigDash) que DigDash a mise au point et qui constitue principalement l’add-on. C’est cette application web qui va se charger d’envoyer la requête SOAP avec les informations que vous aurez fournies dans DigDash et c’est elle-même qui se chargera de rapatrier la réponse SOAP dans DigDash.
62
63 [[image:soap_fr_html_9ff712d7c68a690d.png||queryString="width=667&height=423" height="423" width="667"]]
64
65 __Schéma : Principe des appels SOAP depuis DigDash__
66
67 = Installation et configuration du module SOAP =
68
69 == Installation et déploiement de l’application web ==
70
71 Arrêter avant tout le serveur DigDash.
72
73 Copier l’application web **ddsoap.war** située dans le dossier **<digdash_installation>/add-ons/soap **vers le dossier **<digdash_install>/apache-tomcat/webapps**.
74
75 Redémarrer le serveur DigDash pour déployer l’application.
76
77 == Dossier wsdls ==
78
79 Dans le dossier **<digdash_installation>/add-ons/ddsoap/wsdls**, placer la liste des fichiers WSDL (.wsdl) correspondant aux descriptions des services que vous souhaitez interroger.
80
81 == Configuration du fichier soap_props.properties ==
82
83 Dans le dossier de l’application déployée, configurer le fichier **ddsoap/soap_props.properties** comme suit :
84
85 === Propriétés diverses ===
86
87 |Propriétés|Description
88 |PRINT_DEBUG|(((
89 Cette propriété doit être à true pour l’affichage des autres traces. Seules les traces d’erreur sont tout le temps affichées.
90
91 Cette propriété permet d’afficher dans les logs les traces de debug.
92 )))
93 |SHOW_REQUESTS|Permet d’afficher les requêtes SOAP envoyées au Web Service.
94 |SHOW_RESPONSES|Permet d’afficher les réponses SOAP envoyées par le Web Service.
95 |LOGIN_BEFORE_CALL_SERVICE|Permet d’opérer une authentification avant l’envoi de la requête grâce aux propriétés identifiants (préfixées de **_creds **voir partie suivante).
96 |REMOVE_REQUEST_EMPTY_VALUES|Supprime les valeurs vides (identifiées par des « ? ») de la requête SOAP.
97 |REMOVE_REQUEST_EMPTY_NODES|Supprime les nœuds vide de la requête SOAP.
98
99 __Tableau : Propriétés diverses pour la configuration du module SOAP__
100
101 === Propriétés identifiants ===
102
103 Il est possible qu’une authentification soit nécessaire avant de faire appel à une méthode de service.
104
105 **__TOUTES__ ces propriétés doivent être préfixées de « creds_ » __ET__ la propriété LOGIN_BEFORE_CALL_SERVICE doit être à ‘true’ (voir III.3.1).**
106
107 |Propriétés|Description
108 |(% colspan="2" %)**Attention **: les caractères spéciaux doivent être échappés dans les noms des propriétés (\= pour = , \: pour [[image:icon:emoticon_smile]]
109 |**creds_**binding|(Obligatoire) Le nom du service qui permet de s’authentifier.
110 |**creds_**operation|(Obligatoire) Le nom de l’opération d’authentification.
111 |**creds_**<username>|L’éventuel login pour l’authentification.
112 |**creds_**<password>|L’éventuel mot de passe pour l’authentification.
113 |**creds_**<any other parameter>|Les éventuels autre paramètres permettant l’authentification.
114
115 __Tableau : Propriétés utiles à l’authentification pour l’utilisation du module SOAP__
116
117 = Configuration dans DigDash =
118
119 == Création du fichier WLNK ==
120
121 Nous allons partir sur le procédé classique d’une extraction de données à partir d'un fichier au format XML.
122
123 Source de données > Ajouter > Tous types de fichier...
124
125 Sélectionnez ensuite le serveur de documents à utiliser
126
127 Ajouter un nouveau document au serveur en cliquant sur le bouton Ajouter un fichier au serveur.
128
129 Trois options sont disponibles. Pour récupérer du contenu via SOAP, nous allons utiliser l’option « Entrer une URL ».
130
131 → L’URL à appeler est celle de l’application web **ddsoap** précédemment déployée (**<adresse_serveur_digdash>/ddsoap**)
132
133 → Le nom du fichier WLNK doit finir par **.xml**
134
135 → Cocher l’option « Ajouter uniquement le lien URL au serveur de documents ». C’est cette option qui crée un fichier WLNK.
136
137 → Il est possible de personnaliser le timeout (en secondes) de la requête dans le cas d’un WLNK (seules les valeurs > 0 seront prises en compte, sinon c’est le timeout par défaut qui est appliqué).
138
139 [[image:soap_fr_html_3d5c17f40c89cee2.png||queryString="width=382&height=352" height="352" width="382"]]
140
141 __Capture : Appel de la web app ddsoap__
142
143 Vous pouvez** **renseigner les paramètres pour la requête SOAP sous forme de clé-valeur dans les paramètres GET HTTP.
144
145 **Vous __devez__ OBLIGATOIREMENT renseigner au minimum ces deux paramètres **:
146 **_binding** : le nom du Service à appeler
147 **_operation** : le nom de l’opération ou méthode du Service à appeler.
148
149 [[image:soap_fr_html_a68265b5ef8d858a.png||queryString="width=357&height=360" height="360" width="357"]]
150
151 __Capture : Saisie des paramètres SOAP__
152
153 Pour les autres paramètres SOAP, il faudra mentionner leur nom (ne pas oublier les espaces de nommage s’il y en a). Si plusieurs paramètres apparaissent dans la requête, renseigner les noms des parents permettant de parvenir au nœud voulu.
154
155 En général, le premier nœud de la requête avec le nom spécifié sera sélectionné, à moins que le chemin pour accéder à un nœud spécifique est spécifié (en remontant dans les parents, sans pour autant remonter jusqu’à la racine).
156
157 |Séparateurs|Description|Exemple
158 |/|Séparateur de chemin dans l’arborescence XML.|(((
159 <a>
160
161 <a1>
162
163 <b>?</b>
164
165 **<c>?</c>**
166
167 </a1>
168
169 <b>?</b>
170
171 **<c>?</c>**
172
173 </a>
174
175 <a1>
176
177 <b>?</b>
178
179 <c>?</c>
180
181 </a1>
182
183 **Pour accéder à l’élément c, on écrira a/c (c sélectionnera le premier élément c)**
184 )))
185 |@|Pour accéder à un attribut d’un élément XML.|(((
186 <a>
187
188 <b>?</b>
189
190 <c **attr=?**>?</c>
191
192 <a>
193
194 **Pour accéder à l’attribut attr de l’élément c, on écrira a/c@attr (ou [[c@attr>>path:mailto:c@attr]] directement)**
195 )))
196
197 __Tableau : Convention de nommage pour accéder à un nœud__
198
199 Une fois les paramètres SOAP saisis, valider et le document WLNK sera créé et déposé sur le serveur de document sélectionné.
200
201 Ce fichier WLNK pourra ensuite être chargé en tant que source de données XML de manière classique.
202
203 == Gestion de la pagination ==
204
205 Le module SOAP peut vous aider à agréger les données d’une requête paginée pour récupérer dans DigDash la totalité des données.
206
207 Pour cela, vous devez **obligatoirement** spécifier les paramètres GET suivants dans l’URL :
208
209 **_pagination** : ce paramètre doit être à true pour spécifier un cas de pagination.
210
211 **_pageTag** : vous devez spécifier dans ce paramètre le nom du tag (il peut s’agir d’un élément ou d’un attribut) qui définit la pagination (voir le tableau : //Convention de nommage pour accéder à un nœud //pour définir ce paramètre).
212
213 **_pageStartElement** : il s’agit du nom de l’élément englobant les lignes de données qui nous intéressent (voir partie suivante). Si vous ne connaissez pas la structure de la réponse SOAP, il vous faudra en général envoyer une première requête sans pagination dans un premier temps pour connaître le nom de ce tag (voir le tableau : //Convention de nommage pour accéder à un nœud //pour définir ce paramètre)..
214
215 **_pageInc** : l’index de la page commence à 0. Ce paramètre définit l’incrémentation de cet index.
216
217 _//resultSize// (facultatif) : spécifier le nombre de résultat total permet d’optimiser le temps de réponse.
218
219 == Configuration de la source de données XML ==
220
221 Le chargement de la réponse SOAP au format XML en tant que source de données dans DigDash peut être difficilement lisible aux premiers abords.
222
223 Il faut en effet apporter quelques précisions à la configuration de la source de données DigDash pour que cela soit plus lisible.
224
225 Par exemple : si on considère une réponse SOAP avec la structure XML suivante :
226
227 {{code language="XML"}}
228 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
229 <soapenv:Body>
230
231 <a></a>
232
233 <structs>
234 <struct1>
235 <s11></s11>
236 <s12>
237 <s121></s121>
238 </s12>
239 <s13></s13>
240 <s14></s14>
241 </struct1>
242
243 <struct2>
244 <s21></s21>
245 <s22>
246 <s221></s221>
247 </s22>
248 <s23></s23>
249 <s24></s24>
250 </struct2>
251
252 <struct3>
253 <s31></s31>
254 <s32>
255 <s321></s321>
256 </s32>
257 <s33></s33>
258 <s34></s34>
259 </struct3>
260 </structs>
261
262 </soapenv:Body>
263 </soapenv:Envelope>
264 {{/code}}
265
266 (((
267 __Exemple : exemple de structure d’une réponse SOAP__
268 )))
269
270 Nous devons tenter d’identifier la structure englobant les structures (les lignes) qui nous intéressent. Dans cet exemple de réponse SOAP, les structures //struct1//, //struct2//, //struct3// sont celles qui nous intéressent.
271
272 La structure englobant celles-ci est la structure //structs.//
273
274 Il faudra donc préciser dans la configuration de la source de données, dans les options avancées de la sélection de données :
275
276 [[image:soap_fr_html_2c3ee679a12936df.png||queryString="width=527&height=307" height="307" width="527"]]
277
278
279 [[image:soap_fr_html_dc89881d6bea0c80.png||queryString="width=304&height=332" height="332" width="304"]]
280
281
282 Cocher l’option « Commencer la lecture du XML à partir d’un tag spécifié » et préciser à partir de quelle structure commencer la lecture du XML.
283
284 On préférera aussi décocher l’option « Déplier les nœuds fils et les attributs en colonnes ».
285
286 = Lexique =
287
288 * Nous appellerons dans ce document :
289 ** SOAP : Simple Object Access Protocol. C’est un protocole d'échange d'information structurée dans l'implémentation de services web bâti sur XML. (Wikipédia)(((
290 WSDL : Web Services Description Language. Il s’agit d’un fichier au format XML permettant de décrire un service web.
291 )))
292
293 WLNK : Web LiNK. Les fichiers dont l’extension est .wlnk comportent des liens vers des sources de données.
294
295 = Références =
296
297 //DigDash utilise la librairie OpenSource soapui de SmartBear Software pour supporter les échanges avec les services web SOAP.//
298
299 [[https:~~/~~/www.soapui.org>>url:https://www.soapui.org/]]