Services WEB

XML vs JSON

Les règles du jeu XML

Elles sont extrêmement simples. Les informations doivent être :

soit encadrées par des balises ouvrantes(ex. <LIVRE>) et fermantes (ex. </LIVRE>) (contrairement à HTML où ses ces dernières n'étaient pas toujours obligatoires). On parle alors d'éléments. Les éléments doivent s'imbriquer proprement les uns dans les autres : aucun chevauchement n'est autorisé. Les éléments vides sont permis, selon le format <ELEMENTVIDE/>.

soit incluses à l'intérieur même des balises : on parle alors d'attributs. Exemple : <LIVRE SUJET="XML">. Ici l'attribut SUJET de l'élément LIVRE a la valeur "XML" . En XML, contrairement à HTML, les valeurs des entités doivent toujours être encadrées par des guillemets (simples ou doubles).

Soit encore définies sous forme d'entités. Les entités sont des abréviations. Par ex; si "Extensible Markup Language" est déclaré comme une entité associée à la notation "xml"; cette chaîne de caractères pourra être abrégée en "&xml;" dans tout le fichier XML. Une entité peut aussi représenter un fichier XML externe tout entier. (inclusion de fichier XML)

Les caractères < , > , & et " doivent être remplacés par les entités < , > , & et &quote;dans les valeurs de type texte.

le document peut enfin contenir :

des commentaires sous la forme 

des processing instructions (PI) c'est à dire des instructions destinées à une application particulière sous la forme <?nom-application instructions-spécifiques?>
par exemple, une "processing instruction" destinées à XML lui même commence souvent les documents XML.

<?xml version="1.0" encoding="ISO-8859-1" ?> (version de XML et jeu de caractères des données, ici "latin-1", c.a.d le nôtre)

La structure arborescente du document XML (intitulé des balises, imbrications des balises, caractère obligatoire ou facultatif des balises et de leur ordre de succession) peut être déclarée formellement dans le corps du document XML ou dans un fichier séparé.

Cette déclaration s'appelle une Définition de Type de Document (DTD) ou un schéma XML (XSD)
un schéma est lui même un fichier XML qui en décrit un autre.

commençons par une partie d'entête :
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
<xsd:annotation> 
 <xsd:documentation xlm:lang="fr"> 
   XML Schema pour la liste des cours AF400. 
 </xsd:documentation> 
</xsd:annotation>
puis la partie descriptive en elle même:
<xsd:element name="AF400" type="AF400Type"/> 

<xsd:complexType name="AF400Type"> 
 <xsd:sequence> 
     <xsd:element name="COURS" type="CoursType" minOccurs="1"/> 
 </xsd:sequence> 
</xsd:complexType>
<xsd:complexType name="CoursType"> 
 <xsd:sequence>
     <xsd:element name="TEXTE" type="xsd:string"/>
     <xsd:element name="TYPE" type="xsd:string"/>
     <xsd:element name="SRCFIL" type="xsd:string"/>
     <xsd:element name="SRCLIB" type="xsd:string"/>
     <xsd:element name="SRCMBR" type="xsd:string"/>
     <xsd:element name="CHEMIN" type="xsd:string"/>
     <xsd:element name="SUJET" type="xsd:string"/>
     <xsd:element name="MOT-DIRECTEUR  type="MotType"/>
     <xsd:element name="DATE" type="xsd:string"/> 
 </xsd:sequence> 
< /xsd:complexType>
<xsd:complexType name="MotType"> 
 <xsd:sequence> 
     <xsd:element name="MOTCLE1 type="xsd:string" minOccurs="1"/>
     <xsd:element name="MOTCLE2 type="xsd:string"/>
     <xsd:element name="MOTCLE3 type="xsd:string"/>
     <xsd:element name="MOTCLE4 type="xsd:string"/>
     <xsd:element name="MOTCLE5 type="xsd:string"/>
 </xsd:sequence> 
< /xsd:complexType>
On peut définir un élément (xsd:element) ou un attribut (xsd:attribut), chacun pouvant faire référence à un type
(voyez ici la liste des types admis dans un schéma XML) comme xsd:nonNegativeNumber
ou bien faire référence à un type définit dans le scéma.

Les types définis peuvent être :

xsd:complexType (structure)

xsd:simpleType (donnée élémentaire, mais subissant, par exemple, des contrôles particuliers)

Lorsqu'un document XML possède une DTD ou un Schéma associé et la/le respecte, on dit qu'il est valide.

Lorsqu'il respecte seulement les règles de la grammaire XML (balises fermées, correctement imbriquées) on dit qu'il est bien formé.
Aujourd'hui JSON est de plus en plus utilisé.

JSON (JavaScript Object Notation) est un format de données textuelles dérivé de la notation des objets du langage JavaScript (Wikipedia)

ce qui s'écrit comme cela en XML s'écrit comme cela en JSON

<producteurs>
  <producteur>
    <numero>45</numero>
   <commune>Reims</commune>
    <appellation>13</appellation>
  </producteur>
</producteurs> ->
{
   "producteurs": {
       "producteur": {
          "numero":45,
            "commune":"Reims",
            "appellation":13
       }
    }
}

D'ailleurs vous trouverez ici deux fonctions bien pratiques XML2JSON et JSON2XML écrites en Java.

Un élément peut contenir un objet, une valeur ou un tableau de valeurs, marqué alors par [ et ]
<PO>
 <id>103</id>
 <orderDate>2014-06-20</orderDate>
 <customer>
   <cid>888</cid>
 </customer>
 <items>
  <item>
   <partNum>872-AA</partNum>
   <shipDate>2014-06-21</shipDate>
   <productName>Lawnmower</productName>
   <USPrice>749.99</USPrice>
   <quantity>1</quantity>
 </item>
 <item>
  <partNum>837-CM</partNum>
  <productName>Digital Camera</productName>
  <USPrice>199.99</USPrice>
  <quantity>2</quantity>
  <comment>2014-06-22</comment>
  </item>
 </items>
</PO>
devient (remarquez le tableau de "item")
{
 "PO":{
 "id": 103, 
 "orderDate": "2014-06-20", 
 "customer": {"@cid": 888}, 
 "items": { 
   "item": [
             { "partNum": "872-AA", 
               "productName": "Lawnmower", 
               "quantity": 1, 
               "USPrice": 749.99, 
               "shipDate": "2014-06-21" 
             }, 
             { "partNum": "837-CM", 
               "productName": "Digital Camera", 
               "quantity": 2, 
               "USPrice": 199.99, 
               "comment": "2014-06-22" 
             } 
          ] 
        } 
    }
}

Présentation de l'architecture
web-services

(ou services web)

Un web-service : c'est un logiciel qui interagis avec d'autres au moyen de protocoles universels (http, xml...)

Il existe deux types de services WEB

Les services dits WS, utilisant de nouveaux protocoles :
- Il existe deux formes de services-web WS : SOAP et XML-RPC. SOAP est orienté objet et gère les états tandis que XML-RPC est procédural et sans gestion des états.
- Les services web présentent les 2 caractéristiques suivantes :
  - enregistrement facultatif auprès d'un service de recherche (UDDI)
  - interface publique avec laquelle le client invoque le service (WSDL)
- UDDI : Universal Desciption, Discovery and Integration peut être vu comme les pages blanches (ou jaunes) des services-web. C'est un annuaire permettant à des fournisseurs de présenter leurs services à des 'clients'.
- WSDL : Web Service Description Language est un langage reposant sur XML dont on se sert pour décrire les services-web. Il est indispensable à UDDI pour permettre aux clients de trouver les méthodes leur permettant d'invoquer les services web. Beaucoup d'outils comme JBuilder, Delphi ou Office se servent de WSDL pour découvrir et générer les mécanismes d'invocation des services-web.
- SOAP : Simple Object Access Protocol est un protocole basé sur XML et qui définit les mécanismes d'échanges d'information entre les clients et les fournisseurs de service-web. Les messages SOAP sont susceptibles d'être transportés en HTTP, SMTP, FTP...(souvent HTTP)
- XML-RPC : protocole RPC (Remote Procedure Call) basé sur XML. Permet donc l'invocation de procédure distante sur internet.

Précisions sur SOAP

Une différence importante entre SOAP et XML-RPC est que les procédures SOAP prennent des paramètres nommés. L'ordre des paramètres lui n'a pas d'importance, contrairement à XML-RPC.

Structure d'un message SOAP :

une enveloppe qui définit le contenu du message,
un en-tête (optionnel) qui contient les informations d'en-tête (autorisations et transactions par exemple),
un corps contenant les informations sur l'appel et la réponse
une gestion d'erreur qui identifie la condition d'erreur

des attachements (optionnel)
Exemples

demande d'une température pour un code postal donné

<?xml version="1.0"?>
<SOAP-ENV:Envelope 
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <SOAP-ENV:Body>
          <m:getTemp xmlns:m="urn:xmethods-Temperature" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                  <zipcode xsi:type="xsd:string">44000</zipcode>
          </m:getTemp>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

réponse

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Body>
          <ns1:getTempResponse xmlns:ns1="urn:xmethods-Temperature" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                  <return xsi:type="xsd:float">22</return>
          </ns1:getTempResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Les éléments SOAP peuvent prendre les attributs suivants :
- actor : indique le point d'arrivée d'un élément d'en-tête. Ceci est lié au fait qu'un message SOAP peut passer par un ensemble d'intermédiaires avant d'arriver à sa destination finale. Il est donc possible de cibler un attribut vers un de ces points intermédiaires via cet attribut.
- encodingStyle : sert à définir les types de données contenu dans le document.
- mustUnderstand : sert à définir si le destinataire d'un message doit traiter un élément d'en-tête (absence de cet attribut = false).
SOAP autorise deux modes de communication :
- SOAP RPC : appel synchrone de procédures distantes où un nœud SOAP envoie un requête SOAP avec des paramètres et reçoit une réponse en retour.
- messages SOAP : communication orientée message où des nœuds SOAP envoient et reçoivent des documents XML de manière synchrone ou non.

Précisions sur WSDL

Un fichier WSDL est un format de description des services web fondé sur XML.
Dans WSDL les services communiquent par échange de messages entre des terminaisons, constituées d'un ou plusieurs ports, chacun doté d'un type.
WSDL définit donc :
- les Types : un système de types applicable à des données. Utilisation de XML Schema pour définir les types de données.
- le Message : décrit les données échangées entre services web. Peut-être comparé aux paramètres d'un appel de procédure.
- le Type de Port (portType): définit les opérations du service web et les messages impliqués (de type input, output ou fault). Peut être comparé à une interface Java.
- La Liaison (binding) : définit le format des messages (par exemple soap:body spécifie que le le message considéré sera transmis dans la partie body du message soap) et le protocole utilisé par chaque type de port (voir par exemple soap:binding et les attributs style et transport). C'est l'implémentation de l'interface.
- Le Port : un point de terminaison identifié de manière unique par la combinaison d'une adresse internet et d'une liaison
- Un Service Web (service) : associe des liaisons à des process concrets de mise en oeuvre des opérations qu'elles décrivent
  (typiquement une URL dans le cas d'une liaison mettant en oeuvre SOAP sur HTTP)
Les services REST, utilisant uniquement des méthodes standard du WWW
- Accès par URI (comme une URL), facile à composer, facile à lire
  -> par exemple (pour une gestion d'articles, n° d'article 24 ) /article/24
- HTTP comme méthode d'appel (GET, POST , PUT et DELETE)
  par exemple :
  -> GET /articles/ : retourne tous les articles, GET /article/123 retourne l'article 123
  -> POST /article/123: créé l'article 123
  -> PUT /article/123 : met à jour l'article 123
  -> DELETE /article/123 : supprime l'article 123
- Retour de la donnée dans un format normalisé comme HTML, XML, JSON, ...
- Ils sont dit stateless, c'est à dire qu'ils fonctionnent comme le web classique, ils ne se souviennent de rien, tout paramètre doit être retransmis.
  
  Par exemple le site Data.Nantes.fr offre des informations possédées par la ville de Nantes, dans le cadre OpenData, sur ce principe
  
  le site de la BCE (Banque Centrale Européenne), fournit les taux de change avec l'Euro sur une simple URL
  
  (ici, on accède via SQL directement à ces informations)

Et sur nos systèmes IBM i?

IBM proposait déjà des mécanismes d'appel de programmes (RPG ou COBOL) depuis une application Java : PCML : langage de description du programme

public static void main(String[] argv)
{
       AS400 as400System = new AS400();
       ProgramCallDocument pcml = null;
       String msgId, msgText;
       Object value = null;
       try {
           System.out. println ("Creating ProgramCallDocument for GetCust pgm.");
           pcml = new ProgramCallDocument(as400System, "GETCUST");
           boolean ok = pcml.callProgram("getcust");
           System.out.println(" rc is---> " + rc);
           if (!ok)
               { /* Retrieve list of AS/400 messages & display them */ }
           else
               {
                  value = pcml.getValue("getcust.gotback.Name");
                  System.out.println("Customer name: " + value);
               }
       } catch (PcmlException exc) {
           System.out.println("*** Call to getcust failed. ***");
           Sy ste m. exit (0);
       }
       System.exit(0 );
} // end main method

Depuis la version 6, WDSc puis RDI proposent maintenant des outils de gestion de services WEB.

WDS Client V7et RDI for SOA contiennent les mêmes fonctionnalités (mais avec un nouvel assistant pour RDI)

Cliquez sur parcourir pour modifier les caractéristiques du service

1/ le choix *SRVPGM ou *PGM

2/ par le bouton Modifier, la connexion :

Profil et mot de passe de connexion
Liste de bibliothèques

Vous devrez indiquer aussi, le(les) type(s) de service(s) à générer

nomdupgm -> service retournant des valeurs
nomdupgm_XML -> service retournant un fichier XML contenant les valeurs

Une page de test est générée puis lancée

IBM i V7 : Serveur intégré Liberty

Il s'agit du nouveau serveur d'application intégré à l'OS pour distribuer les applications Java.

Ce serveur support JSF, JSP, servlets et services web, et implique peu de ressources et d'administration, c'est le même que celui utilisé par DB2 WebQUERY,

Il est basé sur une version de WAS nommée Liberty profile

Lancez le serveur d'administration HTTP, si ce n'est déjà fait par STRTCPSVR *HTTP HTTPSVR(*ADMIN)

Puis loggez vous sur http://<votreas400>:2001/HTTPAdmin/

et voilà, vérifiez les informations récapitulatives (regardez les ports IP attribués automatiquement)

liste des services (l'assistant créé un exemple nommé ConvertTemp)

Le serveur est créé avec un service : ConvertTemp, il faudra utiliser "Manage Deployed Services/ Deploy" pour en créer d'autres.

Depuis 2010, un groupe PTF permet de déléguer des droits via l'administration graphique.

Sans cette délégation, il faut être *ALLOBJ et *IOSYSCFG pour administrer les serveurs mais aussi déployer les web services.

Ajoutons un utilisateur à la liste des utilisateurs autorisés :

Il faut ensuite spécifier les droits (globalement par type de serveur ou serveur par serveur)

Déployons un programme COBOL

Ici W_RECAP de BDVIN0, attendant une zone PR_CODE, et retournant une DS nommée INFOCENTRE,
ce pgm RPG a été compilé avec PROCESS OPTIONS PGMINFO(PCML MODULE)

Si vos programmes sont dans un ASP indépendant, Utilisez plutôt l'option Browse...

Et indiquez /iASP/QSYS.LIB/mabib.LIB/monpgm.PGM ou monsrvpgm.SRVPGM

ou /iASP est le point de montage de votre ASP indépendant

Indiquez ensuite, le nom public du service et un texte explicatif

puis, précisez le sens d'utilisation des paramètres (automatiquement découverts par l'assistant grâce à PGMINFO)

Si vous avez oublié l'option PGMINFO ou si vous appelez un CL (CLLE et non CLP), il faudra faire référence à un fichier PCML, pour faire apparaitre les paramètres

SI vous voulez lancer un COBOL (non ILE) ou un RPG 3, faite un CLLE qui appelle pour vous.

Un fichier PCML devant être structuré comme suit :

<pcml version="4.0"> 
   <program name="MONPGM" path="/QSYS.LIB/MABIB.LIB/MONPGM.PGM"> 
      <data name="P1" type="char"   length="3" usage="inputoutput" /> 
      <data name="P2" type="packed" length="2" precision="0" usage="inputoutput" /> 
   </program> 
 </pcml>

Dans un ASP indépendant

<pcml version="4.0"> 
   <program name="MONPGM" path="/IASP/QSYS.LIB/MABIB.LIB/MONPGM.PGM"> 
      <data name="P1" type="char"   length="3" usage="inputoutput" /> 
      <data name="P2" type="packed" length="2" precision="0" usage="inputoutput" /> 
   </program> 
 </pcml>

avec une structure :

<pcml version="4.0"> 
 <!-- exemple avec une structure complexe -->
 <struct name="INFOCENTRE">
   <data name="PR_CODE" type="int" length="4" precision="31" usage="inherit" /> 
   <data name="PR_NOM" type="char" length="50" usage="inherit" /> 
   <data name="PR_TEL" type="char" length="20" usage="inherit" /> 
   <data name="APPEL00001" type="char" length="80" usage="inherit" /> 
   <data name="NBVIN" type="packed" length="3" precision="0" usage="inherit" /> 
   <data name="ENCAVE" type="char" length="3" usage="inherit" /> 
   <data name="CEPAGE" type="char" length="25" usage="inherit" /> 
   <data name="NBCEPAGE" type="packed" length="3" precision="0" usage="inherit" />
 </struct> 
 <!-- le pgm avec ses paramètres -->
 <program name="AVECDS" path="/QSYS.LIB/MABIB.LIB/AVECDS.PGM">
     <data name="PR_CODE" type="packed" length="9" precision="0" usage="inputoutput" />
     <data name="INFOCENTRE" type="struct" struct="INFOCENTRE" count="500" usage="inputoutput" />
 </program> 
</pcml>

voici les types reconnus par PCML :

historiquement char | int | packed | zoned | float | byte | struct
pcml6 : date , timestamp
- mais malheureusement pas en COBOL, voir https://www.ibm.com/support/knowledgecenter/en/ssw_ibm_i_73/rzase/cblpcml.htm

Pour infos, voici un extrait du programme déployé ici, en ce qui concerne les paramètres :

vous pouvez retourner une structure

Des PTF de 2009, apportent la possibilité de gérer en variable (integer uniquement) le nombre d'occurrences d'une structure

Enfin en Juin 2015, SI56823(7.2) propose de rechercher automatiquement le nombre d'occurrences dans une variable placée avant la DS et nommée comme la DS suivit de _LENGTH

si vous décochez l'option, vous retrouvez l'affichage du dessus permettant de saisir le nbr d'occurrences

Cela permet de gérer les DS imbriquées :

Exemple

un producteur
- contenant les vins de ce dernier (nombre variable, maxi 50 vins par producteur)
  
  Apparait
Les variables _LENGTH n'apparaissent pas dans le fichier wdsl.
Les variables _LENGTH ne sont pas répercutées en tant que données retour

ici un producteur en retour , ce dernier n'ayant que 3 vins
cette technique peut être utilisée pour des variables caractères extrêmement longue (plus de 1000 c.) avant le support des VARCHAR
- REPONSE_LENGTH
- REPONSE, par ex. CHAR(10000), seule la partie significative de REPONSE sera transmise
cette même PTF respecte l'ordre d'apparition des paramètres du pgm (ce n'était pas le cas avant)

Indiquez ensuite le profil utilisateur qui lancera le programme

il doit s'agir d'un profil avec un mot de passe (*NONE provoquera une erreur), et qui a des droits sur le programme.
si vous utilisez l'option server's user ID, vous devez attribuer un mot passe à QWSERVICE
Si vous modifiez le profil ensuite (c'est possible) il faudra redémarrer le serveur.

indiquez aussi, la liste des bibliothèques à utiliser

Si vous travaillez avec un ASP indépendant, vous saisirez /IASP/QSYS.LIB/AUTREBIB.LIB

Le service déployé, vous le retrouverez ici, vous pourrez en gérer certaines caractèristique par Properties

(properties, permet de changer le profil ou d'éditer le fichier WSDL)

le WSDL pouvant être produit dynamiquement ou de manière statique (nouveauté) et donc être édité par vos soins

passez la paramètre "Web service endpoint generation" à Static, appliquez, puis éditer le wsdl.

Important si vous masquez votre Serveur IBM i derrière un nom de domaine public.

Il faudra alors remplacer (par exemple)

   <soap:address location="http://as400.volubis.intra:10030/web/services/W_RECAP"/>

par

   <soap:address location="http://www.volubis.fr:10030/web/services/W_RECAP"/>

Il y avait une option de test, qui a disparue en 7.3. Pour tester utilisez des produits standard comme soapUI

Téléchargez, Installez et lancez le produit.

Créez un nouveau projet en indiquant les coordonnées pour acquérir le fichier WSDL sur le system i.

renseignez les valeurs envoyées en remplacant les ? par vos données (ici le producteur 45)

lancez (flèche verte en haut à gauche de la fenêtre Request1)

Si vous rencontrez des problèmes, voyez

/qibm/userdata/os/osgi/lwisysinst/admin/lwi/logs
les fichiers
- lwistderr.txt : contient la liste des erreurs (stderr) de l'administration
- lwistdout.txt : représente la sortie par défaut (stdout) du serveur d'administration
Pour un service, tout est dans /www/<instance>/webservices/services/<le-service>/
(par exemple /www/WSERVICE/webservices/services/ConvertTemp/ pour le service ConvertTemp du serveur WSERVICE)
- particulièrement un fichier portant le nom du service et l'extension .config (par ex : ConvertTemp.config)
  
  Editez le et remplacez WDT_TRACE= par WDT_TRACE=error ou WDT_TRACE=all
- regardez ensuite le contenu de lwistdout.txt dans /www/<instance>/lwi/logs/
En V7R2, le serveur d'application utilisé est Liberty Profile (une version allégée de WAS)

le produit passe en version 2.6
le répertoire du serveur est /www/xxxxxxxx/wlp (où XXXXXXXX est le nom du serveur de web services)

Pensez que tout cela s'appuie sur PCML qui ne reconnait pas en version 6 et 7.1 :
- les dates (cela n'est plus vrai en pcml6, pour le RPG)
- les heures
- les timestamp (cela n'est plus vrai en pcml6, pour le RPG)
- les pointeurs
- les zones à taille variable (cela n'est plus vrai en pcml7, pour le RPG)
- les zones binaires sur 1 octet et 8 octets (seulement 2 et 4)
- et qui limite le passage de paramètres par valeur aux entiers sur 4 octets.
- Le nombre de paramètres est lui aussi limité à :
  - 7 pour un *SRVPGM
  - 32 pour un *PGM

Les scripts suivants (dans /Qibm/ProdData/os/webservices/V1/server/bin) permettent d'automatiser les déploiements

createWebServicesServer.sh
deleteWebServicesServer.sh
getWebServiceProperties.sh
getWebServicesServerProperties.sh
installWebService.sh
listWebServices.sh
listWebServicesServers.sh
setWebServiceProperties.sh
setWebServicesServerProperties.sh
startWebService.sh
startWebServicesServer.sh
stopWebService.sh
stopWebServicesServer.sh
uninstallWebService.sh

pour le passage en production d'un service WEB, il faut passer en production l'objet *PGM (l'exécutable) et l'enregistrer ensuite par le script installWebService.sh

Des correctifs (2015) proposent un nouveau paramètre -parameterUsage

permettant d'indiquer le sens d'utilisation des paramètres i (input) , o (output) , io (input/output)

par exemple, pour un *SRVPGM ayant deux procédures :
- GetClientDep
  - nocli input
  - depart output
- UpdateClientCA
  - nocli input
  - annee input
  - ca input/output


-parameterUsage GetClientDEp:i,o:UpdateClientCA:i,i,io

nouveaux scripts saveWebservicesServeur.sh et restoreWebservicesServeur.sh

saveWebservicesServer.sh
-server Demo -savefile /qsys.lib/libsavf.lib/wsdemo.file

puis

restorewebservicesserver.sh
-fromserverdirectory /www/Demo
-savefile /qsys.lib/libsavf.lib/wsdemo.file

nouveaux scripts saveWebservices.sh et restoreWebservices.sh

ce dernier peut être utilisé pour migrer un web service du serveur LWI (1.5) à celui basé sur liberty profile (2.6)

pour vous familiariser avec les scripts, passez la commande QSH (émulateur de shell Unix) sur une ligne de commande IBM i

puis CD /qibm/proddata/os/webservices/v1/server/bin

ls vous affiche le contenu du répertoire, pwd vous affiche le répertoire en cours, etc...

si vous tapez le nom d'un script -help , il vous affiche une aide "limitée" , par exemple :

installWebservice.sh -help 
     
Command usage: 

installWebService.sh
 -server 'server-name' -programObject 'program-object'                   
   [-service 'service-name'] [-pcml 'pcml-file'] [-userid 'userid']        
   [-detectFieldLengths] [-serviceType '*SOAP11|*SOAP12|*REST']            
   [-targetNamespace 'target-namespace']                                   
   [-parameterUsage 'parameter-list'] [-propertiesFile 'property-file']    
   [-libraryList 'library-list'] [-libraryListPosition  '*FIRST|*LAST']    
   [-disableNillableWSDLElements] [-disableOptionalWSDLElements]           
   [-addUnderscoreToWSDLElementNames] [-printErrorDetails] [-help]

Quelques Exemples :

installWebService.sh
   -server 'WFORMATION'
   -programObject '/QSYS.LIB/FORMATIONX.LIB/GETVINS.PGM'
   -service 'GETVINJ'   -userid 'CM' -detectFieldLengths
   -serviceType '*REST' -propertiesFile '/home/CM/getvins.properties'
   -libraryList 'FORMATIONX;BDVIN1' -libraryListPosition '*LAST' 


 fichier properties :

uri.path.template=/
GETVINS.uri.path.template=/getvinj/{uncode}
GETVINS.wrap.input.parameters=false
GETVINS.wrap.output.parameter=true
GETVINS.http.request.method=GET
GETVINS.consumes=*/*
GETVINS.produces=application/xml, application/json
GETVINS.response.code.parameter=
GETVINS.http.headers.parameter=
GETVINS.CODE.usage=input
GETVINS.CODE.pathparam=uncode
GETVINS.NOM.usage=output
GETVINS.DESVINS_LENGTH.usage=output
GETVINS.DESVINS.usage=output

 IWS00102I - Command completed successfully.
 $

getWebServiceProperties.sh  -server WFORMATION -service GETVINJ

Name:                        GETVINJ                                      
Description:                 GETVINJ                                      
Startup type:                Automatic                                    
Type:                        REST                                         
Status:                      Stopped                                      
Runtime user ID:             CM                                           
Install path:                /www/WFORMATION/webservices/services/GETVINJ 
Program object path:         /QSYS.LIB/FORMATIONX.LIB/GETVINS.PGM                      
PCML file path:              /www/WFORMATION/webservices/services/GETVINJ/GETVINJ.pcml 
Library list:                FORMATIONX;BDVIN1;                                        
Library list position:       *LAST                                                     
Connection pool properties                                                             
  Default CCSID:                     *USERID                                           
  Use maintenance threads:           true                                              
  Cleanup interval (seconds):        300                                               
  Maximum number of connections:     *NOMAX                                            
  Maximum inactivity time (seconds): 3600                                              
  Maximum life time (seconds):       86400                                             
  Maximum use count:                 *NOMAX                                            
  Maximum use time (seconds):        *NOMAX                                            
Transport metadata:                                                                    
Transport headers:

stopWebservicesServer.sh -server WFORMATION 
IWS00102I - Command completed successfully. 
$ 

startWebservicesServer.sh -server WFORMATION 
IWS00102I - Command completed successfully. 
$

saveWebServices.sh -server WFORMATION -saveFile /QSYS.LIB/LIBSAVF.LIB/WFORMATION.FILE
                   -serviceList *ALL 
IWS00102I - Command completed successfully. 
$ 

-> le fichier WFORMATION (SAVF) a bien été créé dans LIBSAVF

pour passer la commande directement depuis un CL

QSH CMD('/qibm/proddata/os/webservices/V1/server/bin/<votrescript.sh> paramètre1 paramètre2 ...')

Enfin, les Groupes PTF de 2012 (SF99115 level 23 et SF99368 level 11) améliorent le serveur de Web service pour le faire utiliser Axis 1.5 (à la place de 1.3)

(voyez ce Wiki pour accéder aux dernières nouveautés)

Une fois installés ces correctifs vous verrez apparaître une option de migration

Vous aurez aussi d'autres options :

Choix du port HTTP et HTTPS
Choix du protocole SOAP (1.1 ou 1.2)

Possibilité d'exporter des informations de transport HTTP
Dont l'adresse IP remote

Avec la SI56883 vous trouverez aussi les éléments suivants

Ces informations sont passées sous forme de variable d'environnement

REMOTE_ADDR = Adresse IP client
le nom précédé de HTTP_ pour les entêtes HTTP "classiques" (HTTP_CONTENT-TYPE, par exemple)

Voir QtmhGetEnv pour lire :

 QtmhGetEnv
          + char(?)           variable pour recevoir le paramètre à lire
          + int(10)           lg de la variable (ce que je transmet)
          + int(10)           lg de la valeur retour (ce qu'il fallait)
          + Char(?)           nom de la variable d'environnement
          + int(10)           lg du nom
          + char(?)           structure std de gestion des erreurs

De paramétrer le pool de connexion afin de limiter, par exemple, le nombre de thread
Et de paramétrer les informations exposées lors du déploiement
- par exemple, exposer le fichier WSDL (metadata) ou pas

Enfin, avec les correctifs de 2012, le serveur permet de créer des web services REST

Choisissez le pgm ou le pgm de service (comme avant)

Indiquez l'URL permettant de le reconnaître

/chemin/{variable} dans le cas d'une transmission de paramètre dans le PATH (PATH_PARAM)
(vous pouvez alors précisez ":" et une expression régulière devant être vraie, ici que des chiffres)

/chemin, dans tous les autres cas

ici l'URL sera /web/services/W_RECAP/recap/prod/1 pour le producteur 1

Les paramètres sont reconnus grâce à PCML, indiquez le sens d'utilisation

Ensuite précisez

la méthode (GET | POST | PUT |DELETE)

la manière de renseigner les paramètres en entrée

*QUERY_PARAM
les paramètres sont transmis dans l'URL sous la forme ?param1=valeur1&param2=valeur2

*PATH_PARAM
les paramètres sont transmis dans l'URL sous la forme /chemin/valeur, l'URL vue plus haut -> /chemin/{param1} définit le nom du paramètre

*FORM_PARAM
les paramètres sont transmis dans un formulaire contenant une zone de formulaire nommé param1 <input name="param1" type="text">

*COOKIE_PARAM
les paramètres sont transmis sous forme de cookies (param1=valeur1)

*HEADER_PARAM
les paramètres sont transmis dans l'entête HTTP sous la forme param1=valeur1

*MATRIX_PARAM
les paramètres sont transmis dans l'URL sous la forme ;param1=valeur1;param2=valeur2

*NONE
les paramètres sont transmis en tant que structure (XML ou JSON) dans le corps (Body)
<param1>
<zone1>valeur</zone1>
<zone2>valeur</zone2>
</param1>
un seul paramètre peut être transmis via cette méthode

dans tous les cas, Indiquez à quel paramètre RPG correspond param1 (ici noprod)

Notez que :

L'un des paramètres du pgm peut servir à retourner le statut HTTP (404 ou 500, par exemple) dans HTTP response code...

L'un des paramètres du pgm peut servir à retourner l'entête HTTP (LOCATION: url-de-redirection, par ex.) dans HTTP header ...

Avec SI56883, le type est libre (text/html, par ex.) et vous pouvez préciser plusieurs types de média en retour.

Il faut alors fixer la variable d'environnement CONTENT_TYPE pour préciser dynamiquement le type retourné à chaque appel.

Ensuite, Indiquez le profil utilisateur à utiliser

la liste de bibliothèques

les informations d'entête HTTP à transporter, puis vous arrivez sur l'écran final

Quelques tests

*PATH_PARAM (celui déployé ci-dessous)

*QUERY_PARAM

nouveau service

paramètre en entrée

Format de sortie JSON

Format de sortie HTML

Exemple

Avec les tables résultat de CALL CREATE_SQL_SAMPLE

Résultat

Pour retourner du binaire (ce qui n'est pas officiellement supporté) il faut convertir en base64

Ces nouveaux Web services peuvent être testés par les dernières versions de SoapUI

Indiquez l'URL

SoapUI va découvrir les paramètres (ici {prod}) , assignez des valeurs et exécutez :

ou par POSTMAN, plus simple pour tester les web services REST

ici la création d'un client par POST

Un seul paramètre peut être indiqué Input Source *NONE

Le pgm attend une zone de niveau 01 ClientRecu, composée des champs indiqués en haut (id, reference,...)

Depuis Octobre 2016, une documentation complète est disponible : http://www-03.ibm.com/systems/resources/systems_i_software_iws_pdf_WebServicesServer_new.pdf

Depuis Décembre 2016, un fichier swagger est généré pour chaque web service REST (l'équivalent de WSDL pour SOAP)

Il faut aller chercher swaggerUI ici : http://swagger.io/swagger-ui/

puis l'installer sur un serveur Apache (ce sont de simples pages web avec du JavaScript)

Si vous l'installez sur IBMi , ajoutez cette option dans index.html

Malheureusement à ce jour le fichier swagger reste dans HTTPAdmin et n'est donc pas accessible sans authentification, exportez le quelque part !

ce qui s'écrit comme cela en XML		s'écrit comme cela en JSON
<producteurs> <producteur> <numero>45</numero> <commune>Reims</commune> <appellation>13</appellation> </producteur> </producteurs>	->	{ "producteurs": { "producteur": { "numero":45, "commune":"Reims", "appellation":13 } } }