Stambia est un outil d’intégration de données qui offre une multitude de composants permettant de collecter et intégrer les données à travers différentes technologies, parmi ces composants figure ‘Stambia API Component’. Ce composant permet de publier ou invoquer des web services REST ou SOAP tout en maintenant un haut niveau de performance et une simplicité de mise en place.
Dans cet article nous allons voir comment mettre en place deux flux Stambia qui ont pour objectifs de :
- Invoquer un web service REST et stocker les données reçues dans une base de données
- Publier un web service REST pour partager/transférer les données d’une base de données
Nous allons voir comment sécuriser un web service publié à l’aide de Stambia. Nous allons également traiter un cas pratique qui s’intéresse à l’archivage des données échangées par un web service.
Invoquer un web service REST
Pour le premier flux, nous allons utiliser un web service de démonstration présenté par le site web : www.mocklab.io.
Définition des métadonnées
Pour pouvoir utiliser le web service dans Stambia il va falloir tout d’abord définir sa métadonnée. Stambia permet d’effectuer un reverse engineering du web service et récupérer automatiquement toutes les propriétés du web service.
Dans un premier temps, il faut créer une métadonnée de type WSDL :
Puis, remplir les informations de la métadonnée comme ci-dessous :
Maintenant, il faut créer un Service et un Port dans la métadonnée WSDL et ensuite faire un reverse engineering du web service REST :
- Clic droit sur la métadonnée ContactManager > New > Service
- Name : ContactManagerService
- Clic droit sur le Service Contact > New Port
- Name : ContactAPI
- Address : https://contact-manager.mocklab.io/v1
- Protocol : HTTP
- HTTP Verb : GET
- Clic droit sur le Port Contacts > New > Operation
- Name : getContactsByCompanyId
- HTTP Address : /contacts
- Clic droit sur l’Operation getContactsByCompanyId > Actions > Reverse REST Web Service
- Ajouter le paramètre companyId avec une valeur 123
- Exécuter la requête GET
- Exécuter le reverse en cochant les éléments nécessaires (Input/Output) comme il suit
Création du mapping
Maintenant que nous avons défini la métadonnée du web service REST avec succès, nous allons créer un mapping qui permettra d’invoquer ce web service. Pour cela, il faut glisser-déposer l’opération getCustomerByID dans le mapping, puis mapper les éléments de la sortie (Output) dans la table de base de données CONTACTS.
L’élément companyId de l’Input ainsi que l’élément getContactsByCompanyId seront alimentés à partir de la colonne id de la table COMPANY. Enfin, un filtre sera créé sur cette colonne pour sélectionner l’id 123.
Une fois ce mapping réalisé puis exécuté, nous allons pouvoir lancer une requête SQL Select sur la table CONTACTS pour vérifier le résultat.
Publier un web service REST
Stambia permet de publier facilement des web service REST, chaque mapping ou process peut être publié comme web service, et hébergé sur le Runtime Stambia.
Dans cette partie, nous allons créer un web service qui permet d’accéder à une liste de clients stockée dans une base de données. Les étapes à suivre pour publier un web services dans Stambia sans les suivantes :
Définition des métadonnées
Dans cet exemple nous allons utiliser un paramètre d’url ‘companyId’ comme paramètre d’entrée du web service pour spécifier l’entreprise pour laquelle la liste des clients sera générée. Après l’appel, le web service donnera en sortie une réponse sous la structure Json suivante :
{"costumers": [
{
"id": "11111",
"CustomerName": "Tom",
"CustomerAddress": "Smith",
"RegisterTime": "2021-01-03 00:00:00.000",
"idState": "123"
} ]
}
Il va falloir alors définir la métadonnée du fichier JSON en sortie, pour cela nous allons créer une métadonnée de type ‘Schema’ (Type JSON):
Après avoir défini le nom de la métadonnée, il faut effectuer le reverse engineering du fichier Json contenant l’exemple ci-dessus. Cela donne le résultat suivant :
Création de mapping ou process
Le mapping permet d’extraire une liste des clients à partir de la table de base de données CUSTOMER, un filtre sera appliqué lors de cette extraction pour sélectionner les clients de l’entreprise qui correspond au paramètre d’entrée du web service ‘companyId’ :
Nous allons également créer un process qui sera utilisé, après sa publication, comme web service :
Le process défini les deux paramètres de sortie et d’entrée du web service :
- idState : paramètre d’entrée du web service, il prend la valeur ‘1’ comme valeur par défaut, si le paramètre est défini dans l’url d’appel au web service la valeur donnée sera prise en compte.
- Customers : paramètres de sortie du web service, il contient la structure Json de la réponse.
Publication du mapping/process comme web service
Pour publier le process vers un runtime Stambia comme web service, il suffit de faire un clic droit sur ce process et puis Publish > As Webservice.
Une fois le process publié sur le runtime Stambia, le web service peut être appelé de la façon suivante :
http://hostName:42200/rest/StambiaDeliveryService/1/<deliveryName>
Notez la valeur ‘<deliveryName>’ qui est à remplacer par le nom du delivery Stambia publié précédemment. (En général, c’est le nom donné au process lors du développement).
L’appel du webservice via un navigateur web donne le résultat suivant :
Sécurisation du web service
Parmi les possibilités proposées en matière de sécurité des web service dans Stambia, figure celle de protéger le runtime avec un user/password, ce qui permet de protéger toutes les opérations de communication avec le Runtime (exécution des Delivery en mode Batch, invocation de web service, …). 1
De plus, stambia permet de sécuriser les appels au web service en configurant des certificats TLS à utiliser pour sécuriser les appels aux web service sur le Runtime de Stambia.2
Il est également possible d’utiliser un outil d’API Management pour gérer et sécuriser les web service publiés avec Stambia.
Les versions plus récentes de Stambia Designer offrent la possibilité de sécuriser, depuis le designer, les web services publiés sur le Runtime. Cela est possible grâce à la métadonnées ‘HTTP Security’, elle propose une multitude de technologies pour sécuriser un webservice : sécurité “Basic”, protocole OAuth, OAuth2, protocole NTLM. Il suffit de définir la métadonnée ‘HTTP Security’ et l’ajouter à une métadonnée à sécuriser. 3
Cas pratique : Composant d’appel web service avec archivage de données
Afin d’avoir plus de visibilité et de pouvoir tracer les données échangées sur un web service, nous avons développé un composant utilisant le Scripting Stambia. Ce composant permet d’effectuer des appels ou des invocations de web service REST tout en gardant la possibilité de tracer les données envoyées vers le web service ainsi que les paramètres techniques renvoyés à l’issue de l’appel (Statut HTTP, message …).
Ce composant facilite l’archivage des données dans la mesure ou celles-ci sont stockées dans les fichiers, ces derniers pouvant être compressés et redirigés vers un dossier d’archivage après l’appel au web service.
Il permet également de tracer et sauvegarder les détails de chaque appel (dates, états, code HTTP, message HTTP, chemin vers le fichier envoyé). Ces valeurs sont publiées dans des variables de session, et peuvent ensuite être sauvegardées dans une table de traçage à l’aide d’un bloc ‘SQL Operation’.
Ce composant permet de structurer les flux d’appel aux web services de manière optimale. Dans un premier temps le flux génère en masse les données à envoyer sous forme de fichiers, puis ceux-ci sont traités par la deuxième partie du flux qui centralise le process d’envoi des données.
Dans ce qui suit, nous allons voir en détail les étapes suivies pour appeler un web service REST en utilisant le Scriping Stambia.
définition des paramètres du web service
Tous d’abord, il faut définir les paramètres Stambia qui seront utilisés comme paramètres d’entrée pour ce module. Ces paramètres sont les suivants :
- endpointAddress : lien complet du web service à appeler
- userName : nom d’utilisateur
- passWord : mot de passe
- filePath : chemin vers le fichier qui contient les données à envoyer
- xmlFileName : nom du fichier qui contient les données à envoyer
Lecture des données depuis le fichier
Dans cette étape, il s’agit de lire le fichier de données et stocker ces données dans une variable de type string, puis convertir la variable string en tableau de Byte, ce dernier sera utilisé dans une étape antérieure pour alimenter le corps de la requête HTTP.
InputStream inStrm = new FileInputStream(new File("${./filePath}$/%{xmlFileName}%"))
BufferedReader xmlbr = new BufferedReader(new InputStreamReader(inStrm, StandardCharsets.UTF_8);
String xmlFile;
StringBuilder sb = new StringBuilder();
while((xmlFile=xmlbr.readLine())!= null){
sb.append(xmlFile.trim());
}
xmlbr.close();
xmlFile=sb.toString();
byte[] postData = xmlFile.getBytes(StandardCharsets.UTF_8);
Initialiser et définir les paramètres de l’appel au web service
L’appel au web service est effectué à l’aide d’une requête HTTP. Pour cela, nous allons utiliser la classe java HTTPUrlConnection.
Cette étape consiste à initialiser la connexion au web service et définir la méthode HTTP ainsi que les paramètres de la requête HTTP.
String url = "%{endpointAddress}%";
URL myurl = new URL(url);
String encoding = Base64.getEncoder().encodeToString(("%{userName}%" + ":" + "%{passWord}%").getBytes());
con = (HttpURLConnection) myurl.openConnection();
con.setReadTimeout(21600000);
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Basic " + encoding);
con.setRequestProperty("Accept", "application/xml");
con.setRequestProperty("Content-Type", "application/xml; charset=UTF-8");
con.setRequestProperty("Accept-Charset", "UTF-8");
Envoie des données au web service et récupération de la réponse
Une fois la connexion est initialisée, il faut envoyer les données du fichier vers le web service et récupérer la réponse.
wr = new DataOutputStream(con.getOutputStream());
wr.write(postData);
StringBuilder content;
br = new BufferedReader(new InputStreamReader(con.getInputStream()));
String line;
content = new StringBuilder();
while ((line = br.readLine()) != null) {
content.append(line);
content.append(System.lineSeparator());
}
Récupération des paramètres de sortie
Après avoir récupéré la réponse du web service, nous allons la publier son contenu dans une variable de session Stambia. Le code HTTP de réponse et le message HTTP sont également publiés comme variables de session Stambia.
__ctx__.publishVariable("~/httpResponseMessage",con.getResponseMessage());
__ctx__.publishVariable("~/httpResponseCode",Integer.toString(con.getResponseCode()));
__ctx__.publishVariable("~/httpResponseContent", content.toString());
Vous trouverez ci-dessous un lien de téléchargement du projet Stambia qui contient un exemple d’appel au web service en utilisant le composant décrit dans cette partie :
Le process ‘searchBooks’ utilise un web service fournis par www.libraryinformationsystem.org 4. Ce process permet de récupérer, à l’aide d’une requête POST, la liste des livres parus entre deux dates. Le fichier contient également les exemples vus dans la première et la deuxième partie de l’article.
Références :
- https://stambia.org/doc/269-stambia-di-software/runtime/configuration/security/417-securing-the-runtime-with-user-password-roles-and-hostname-restriction
- https://stambia.org/doc/269-stambia-di-software/runtime/configuration/security/811-securing-rmi-http-and-web-services-endpoints-with-tls-in-stambia-di-2020-and-higher
- https://stambia.org/doc/63-technology-articles/web-services/1106-getting-started-with-http-security-and-proxy-security
- http://www.libraryinformationsystem.org/services/RestServiceOperation.aspx?uri=book%2fsearch%3fsession_id%3d%7bsession_id%7d&method=POST