Code source wiki de Module SOAP

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