Services WEB

Vous devez avant tout être à jour sur les syntaxes des formats

Et sur le bases du protocole

 

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


Précisions sur SOAP


Précisions sur WSDL

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
<pcml version="1.0">
 <!-- Create a Data Structure -->
 <struct name ="custinfo" >
   < data name ="Number" type="char" length= " 7"
            usage="inputoutput" init="0014400"> </data>
   < data name ="Name"   type="char" length= " 40"
            usage="inputoutput" init=" "> </data>
 </struct>
 <!-- Program getcust -->
 <program name="getcust"
              path="/QSYS.lib/MABIB.lib/GETCUST.pgm" >
   < data name ="gotback" type=" struct"
            usage="inputoutput" struct="custinfo"> </data>
 </program >
</pcml>


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

IBM i V7 : Serveur intégré Liberty

 

Il s'agit du 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



 

Une fois le nom de votre serveur défini vous pouvez préciser les ports du serveur

 

 

Pour diriger le serveur de web services vers un sous-sytème spécifique, vous pouvez préciser:

 



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 le service ConvertTemp donc, et 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 RPG

Ici W_RECAP de AF4TEST, attendant une zone PR_CODE, et retournant une DS nommée INFOCENTRE,
    ce pgm RPG a été compilé avec PGMINFO(*PCML:*MODULE) , en COBOL ->PROCESS OPTIONS PGMINFO(PCML MODULE)

Depuis 2014, l'option *DCLCASE permettant de demander le respect de la casse quant aux noms dans le PCML

 

ET depuis les correctifs d'Avril 2020, vous devrez saisir selon cette dénomination de type "IFS"

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

 

 

Vous pouvez choisir un service de type SOAP



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 apparaître 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 :  

 

un paramètre déclaré const sera utilisé en input, sinon inputoupout


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

Colonné.
 
H PGMINFO(*PCML : *MODULE)
 DPR_code                          S              6  0    
 DINFOCENTRE                     E DS                  qualified   

                                                              
 C              *entry                      plist                                    
 C                                          parm                    pr_code          
 C                                          parm                    infocentre    

En free

 Ctl-opt PGMINFO(*PCML : *MODULE);
 Dcl-DS  INFOCENTRE_T EXT EXTNAME('INFOCENTRE') Qualified Template;   
 DCL-PI *n;
    pr_code packed(6:0);
    infocentre likeds(infocentre_T);
 End-PI;

 

Des PTF de 2009, apportaient 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 :

Indiquez ensuite le profil utilisateur qui lancera le programme

 

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 le paramètre "Web service endpoint generation" à Static, appliquez, puis éditez 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"/>


Sur les anciennes versions, il y avait un utilitaire de test, aujourd'hui 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 l'IBM 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

* pour passer en pcml 7, installez SI66149 (7.2) ou SI66150 (7.3)

puis ajoutez une variable d'environnement niveau système
ADDENVVAR ENVVAR(QIBM_RPG_PCML_VERSION) VALUE(7.0) LEVEL(*SYS)

la V7R2 amenant une nouvelle version de PCML (6) supportant les dates, les restrictions concernant les paramètres s'estompent


• Déclarons un programme ayant des dates en paramètre

le service est déployé , testons

les variables DATE doivent être saisie au format xs:date


Résultat ->

le format pour les timestamp est xs:dateTime



EN Juin 2018, Les PTF SI67769/SI67772 (7.2) ou SI67770/SI67773 (7.3) améliorent encore la gestion des champs date/heure.

 

Exemple, ce programme

exposé en tant que web service retournant du XML affiche ceci :


EN JSON :

 

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


Ensuite précisez




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


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





Vous pouvez aussi exposer des programmes de service (*SRVPGM)

Sélectionnez un PGM de service

 

Choisissez les procédures à exposer (seules celles qualifiées par EXPORT apparaissent)

 

Pour chaque fonction vous préciserez les paramètres et informations de retour

 

 

 

Dans les propriétés vous retrouvez l'ensemble des méthodes exposées

 


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é pour les web services basés sur des pgm) il faut convertir en base64


Ces Web services REST, 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 dédié 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 DS ClientRecu composée des champs indiqués en haut (id, reference,...)

Il retourne plusieurs paramètres :

Les champs sont transmis en minuscules, car le programme utilise PGMINFO(*PCML:*MODULE : *DCLCASE)

Il est aussi possible d'utiliser JMeter pour tester les performances du serveur


Automatisation des déploiements

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) 


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

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 ...')

Dans les propriétés du Serveur

Vous aurez aussi d'autres options :




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

Tout cela devrait continuer d'évoluer rapidement...voyez par exemples les web services basés sur SQL

Copyright © 2020 VOLUBIS