Code source wiki de Module SOAP

Modifié par jhurst le 2021/04/21 10:01
Afficher les derniers auteurs
1 {{ddtoc/}}
2
3 ----
4
5 Ce document décrit la récupération d’une source de données en interrogeant un service web SOAP.
6
7 = Prérequis =
8
9 * Les acronymes utilisés par la suite sont référencés dans le lexique, à la fin de ce document.
10 * 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.
11 * Avoir en possession la liste des fichiers WSDL correspondant aux Services auxquels nous voudrons faire appel.
12 * 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.
13 * 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.
14
15 |[[image:soap_fr_html_c801e156356d3a0a.png||queryString="width=50&height=50" height="50" width="50"]]
16 |(((
17 DigDash vous propose une aide pour consulter la structure des requêtes SOAP.
18
19 Rendez-vous à l’adresse :
20
21 **<digdash_server>/ddsoap?about=true**
22
23 pour avoir des informations concernant votre configuration SOAP.
24 )))
25
26 = Description =
27
28 == Généralités ==
29
30 DigDash propose la possibilité de récupérer des sources de données en interrogeant des services web SOAP.
31
32 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.
33
34 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.
35
36 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.
37
38 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.
39
40 == Description technique ==
41
42 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.
43
44 |[[image:soap_fr_html_829eaa34e529ef0c.png||queryString="width=54&height=54" height="54" width="54"]]
45 |(((
46 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).
47
48
49 //Pourquoi créer un fichier WLNK ?//
50
51 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.
52
53 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**.
54
55 ⇒ **Un fichier WLNK = Une requête SOAP**
56 )))
57
58 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.
59
60 [[image:soap_fr_html_9ff712d7c68a690d.png||queryString="width=667&height=423" height="423" width="667"]]
61
62 __Schéma : Principe des appels SOAP depuis DigDash__
63
64 = Installation et configuration du module SOAP =
65
66 == Installation et déploiement de l’application web ==
67
68 Arrêter avant tout le serveur DigDash.
69
70 Copier l’application web **ddsoap.war** située dans le dossier **<digdash_installation>/add-ons/soap **vers le dossier **<digdash_install>/apache-tomcat/webapps**.
71
72 Redémarrer le serveur DigDash pour déployer l’application.
73
74 == Dossier wsdls ==
75
76 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.
77
78 == Configuration du fichier soap_props.properties ==
79
80 Dans le dossier de l’application déployée, configurer le fichier **ddsoap/soap_props.properties** comme suit :
81
82 === Propriétés diverses ===
83
84 |Propriétés|Description
85 |PRINT_DEBUG|(((
86 Cette propriété doit être à true pour l’affichage des autres traces. Seules les traces d’erreur sont tout le temps affichées.
87
88 Cette propriété permet d’afficher dans les logs les traces de debug.
89 )))
90 |SHOW_REQUESTS|Permet d’afficher les requêtes SOAP envoyées au Web Service.
91 |SHOW_RESPONSES|Permet d’afficher les réponses SOAP envoyées par le Web Service.
92 |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).
93 |REMOVE_REQUEST_EMPTY_VALUES|Supprime les valeurs vides (identifiées par des « ? ») de la requête SOAP.
94 |REMOVE_REQUEST_EMPTY_NODES|Supprime les nœuds vide de la requête SOAP.
95
96 __Tableau : Propriétés diverses pour la configuration du module SOAP__
97
98 === Propriétés identifiants ===
99
100 Il est possible qu’une authentification soit nécessaire avant de faire appel à une méthode de service.
101
102 **__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).**
103
104 |Propriétés|Description
105 |(% 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]]
106 |**creds_**binding|(Obligatoire) Le nom du service qui permet de s’authentifier.
107 |**creds_**operation|(Obligatoire) Le nom de l’opération d’authentification.
108 |**creds_**<username>|L’éventuel login pour l’authentification.
109 |**creds_**<password>|L’éventuel mot de passe pour l’authentification.
110 |**creds_**<any other parameter>|Les éventuels autre paramètres permettant l’authentification.
111
112 __Tableau : Propriétés utiles à l’authentification pour l’utilisation du module SOAP__
113
114 = Configuration dans DigDash =
115
116 == Création du fichier WLNK ==
117
118 Nous allons partir sur le procédé classique d’une extraction de données à partir d'un fichier au format XML.
119
120 Source de données > Ajouter > Tous types de fichier...
121
122 Sélectionnez ensuite le serveur de documents à utiliser
123
124 Ajouter un nouveau document au serveur en cliquant sur le bouton Ajouter un fichier au serveur.
125
126 Trois options sont disponibles. Pour récupérer du contenu via SOAP, nous allons utiliser l’option « Entrer une URL ».
127
128 → L’URL à appeler est celle de l’application web **ddsoap** précédemment déployée (**<adresse_serveur_digdash>/ddsoap**)
129
130 → Le nom du fichier WLNK doit finir par **.xml**
131
132 → Cocher l’option « Ajouter uniquement le lien URL au serveur de documents ». C’est cette option qui crée un fichier WLNK.
133
134 → 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é).
135
136 [[image:soap_fr_html_3d5c17f40c89cee2.png||queryString="width=382&height=352" height="352" width="382"]]
137
138 __Capture : Appel de la web app ddsoap__
139
140 Vous pouvez** **renseigner les paramètres pour la requête SOAP sous forme de clé-valeur dans les paramètres GET HTTP.
141
142 **Vous __devez__ OBLIGATOIREMENT renseigner au minimum ces deux paramètres **:
143 **_binding** : le nom du Service à appeler
144 **_operation** : le nom de l’opération ou méthode du Service à appeler.
145
146 [[image:soap_fr_html_a68265b5ef8d858a.png||queryString="width=357&height=360" height="360" width="357"]]
147
148 __Capture : Saisie des paramètres SOAP__
149
150 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.
151
152 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).
153
154 |Séparateurs|Description|Exemple
155 |/|Séparateur de chemin dans l’arborescence XML.|(((
156 <a>
157
158 <a1>
159
160 <b>?</b>
161
162 **<c>?</c>**
163
164 </a1>
165
166 <b>?</b>
167
168 **<c>?</c>**
169
170 </a>
171
172 <a1>
173
174 <b>?</b>
175
176 <c>?</c>
177
178 </a1>
179
180 **Pour accéder à l’élément c, on écrira a/c (c sélectionnera le premier élément c)**
181 )))
182 |@|Pour accéder à un attribut d’un élément XML.|(((
183 <a>
184
185 <b>?</b>
186
187 <c **attr=?**>?</c>
188
189 <a>
190
191 **Pour accéder à l’attribut attr de l’élément c, on écrira a/c@attr (ou [[c@attr>>path:mailto:c@attr]] directement)**
192 )))
193
194 __Tableau : Convention de nommage pour accéder à un nœud__
195
196 Une fois les paramètres SOAP saisis, valider et le document WLNK sera créé et déposé sur le serveur de document sélectionné.
197
198 Ce fichier WLNK pourra ensuite être chargé en tant que source de données XML de manière classique.
199
200 (% class="box infomessage" %)
201 (((
202 Le fichier WLNK nouvellement créé pourra être modifié manuellement par la suite si besoin. Le menu "Configurer le fichier WLNK" au clic droit vous permettra d'éditer le lien et les paramètres de la requête.
203 \\[[image:1617959272409-270.png]]
204 \\[[image:1617959393192-841.png]]
205 )))
206
207 == Gestion de la pagination ==
208
209 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.
210
211 Pour cela, vous devez **obligatoirement** spécifier les paramètres GET suivants dans l’URL :
212
213 **_pagination** : ce paramètre doit être à true pour spécifier un cas de pagination.
214
215 **_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).
216
217 **_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)..
218
219 **_pageInc** : l’index de la page commence à 0. Ce paramètre définit l’incrémentation de cet index.
220
221 _//resultSize// (facultatif) : spécifier le nombre de résultat total permet d’optimiser le temps de réponse.
222
223 == Configuration de la source de données XML ==
224
225 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.
226
227 Il faut en effet apporter quelques précisions à la configuration de la source de données DigDash pour que cela soit plus lisible.
228
229 Par exemple : si on considère une réponse SOAP avec la structure XML suivante :
230
231 {{code language="XML"}}
232 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
233 <soapenv:Body>
234
235 <a></a>
236
237 <structs>
238 <struct1>
239 <s11></s11>
240 <s12>
241 <s121></s121>
242 </s12>
243 <s13></s13>
244 <s14></s14>
245 </struct1>
246
247 <struct2>
248 <s21></s21>
249 <s22>
250 <s221></s221>
251 </s22>
252 <s23></s23>
253 <s24></s24>
254 </struct2>
255
256 <struct3>
257 <s31></s31>
258 <s32>
259 <s321></s321>
260 </s32>
261 <s33></s33>
262 <s34></s34>
263 </struct3>
264 </structs>
265
266 </soapenv:Body>
267 </soapenv:Envelope>
268 {{/code}}
269
270 (((
271 __Exemple : exemple de structure d’une réponse SOAP__
272 )))
273
274 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.
275
276 La structure englobant celles-ci est la structure //structs.//
277
278 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 :
279
280 [[image:soap_fr_html_2c3ee679a12936df.png||queryString="width=527&height=307" height="307" width="527"]]
281
282
283 [[image:soap_fr_html_dc89881d6bea0c80.png||queryString="width=304&height=332" height="332" width="304"]]
284
285
286 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.
287
288 On préférera aussi décocher l’option « Déplier les nœuds fils et les attributs en colonnes ».
289
290 = Lexique =
291
292 * Nous appellerons dans ce document :
293 ** 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)(((
294 WSDL : Web Services Description Language. Il s’agit d’un fichier au format XML permettant de décrire un service web.
295 )))
296
297 WLNK : Web LiNK. Les fichiers dont l’extension est .wlnk comportent des liens vers des sources de données.
298
299 = Références =
300
301 //DigDash utilise la librairie OpenSource soapui de SmartBear Software pour supporter les échanges avec les services web SOAP.//
302
303 [[https:~~/~~/www.soapui.org>>url:https://www.soapui.org/]]