IBM i e Web Services – Trucchi e Faq (IT)

Last Updated on 1 Marzo 2020 by Roberto De Pedrini

You can find an English version of this post here!

Introduzione

Ecco un’altra collection di FAQ (Domande frequenti) sui Web Service e IBM i (ex AS400)… sono domande che ci vengono poste dalla Community IBM i italiana oppure prese direttamente dai forum di settore. Non vuole essere una guida completa per chi si affaccia per la prima volta al mondo dei Web Service in ambiente IBM i per pubblicare e/o consumare servizi, per questo abbiamo dei corsi appositi che facciamo in aula (se si raggiunge un numero sufficiente) oppure direttamente in azienda, vedi in tal caso l’apposita area di Faq400.com ( https://www.faq400.com/corsi-e-workshop/ ).

iWS-FAQ001: Posso pubblicare un Web Service senza la GUI di IWS?

L’interfaccia GUI di IWS semplifica moltissimo la pubblicazione di programmi e service program come Web Service, ma è un processo “lungo” e ripetitivo … se dobbiamo pubblicare pochi web service è ottimo ma se il numero diventa importante o dobbiamo automatizzare la pubblicazione per la distribuizione di un sooftware o altro, meglio ricorrere agli script

Gli script che riguardano i Web Services sono in questa cartella dell’IFS: /QIBM/ProdData/OS/WebServices/V1/server/bin

Per pubblicare un nuovo webservice avendo già il nostro programma o service program RPG/Cobol o, in generale, ILE possiamo fare:

STRQSH
cd /QIBM/ProdData/OS/WebServices/V1/server/bin
installWebService.sh -server 'server-name' -programObject 'program-object'
[-service 'service-name'] [-pcml 'pcml-file'] [-userid 'userid']
[-libraryList 'library-list'] [-libraryListPosition '*FIRST|*LAST']
[-disableNillableWSDLElements] [-disableOptionalWSDLElements]
[-addUnderscoreToWSDLElementNames] [-libraryListPosition '*FIRST|*LAST'] [-printErrorDetails] [-help]  

 Where:
server is the name of the Web services server in which the service will be installed.
programObject is the integrated file system path to the ILE program or
service program. For example, '/QSYS.LIB/MYLIB.LIB/MYPGM.[SRVPGM or PGM]'
service is the name of Web service to be installed. This parameter is
optional. If not specified, the program object name will be used.
pcml is a path to the PCML file. This parameter is optional. If not
specified, the program object must contain the PCML data.
userid is the user profile the Web service will be modified to run under. This parameter is optional. If not specified, the Web service will run
under the Web services server user profile. Note: The Web service server's
user profile needs to have *USE authority to the user profile specified on
this parameter. A value of *SERVER will ensure the Web service runs under the
same user profile as the Web services server.
libraryList is a list of libraries, that will be added to the library
list prior to invoking the Web service. Each library in the list must
be delimited by a colon. This parameter is optional.
libraryListPosition is the position in the user portion of the job
library list where the list of libraries specified in -libraryList will be
placed. A value of *FIRST inserts the libraries at the beginning of
the user portion of the library list. A value of *LAST inserts the libraries
at the end of the user portion of the library list. This parameter is
optional. If not specified the default value of *LAST is used.
disableNillableWSDLElements will define elements in generated WSDL as
not nillable. If not specified, elements are defined as nillable.
This parameter is ignored for version 1.3 of Web services engine.
disableOptionalWSDLElements will define elements in generated WSDL as
not optional. If not specified, elements are defined as optional.
This parameter is ignored for version 1.3 of Web services engine.
addUnderscoreToWSDLElementNames will generate WSDL element names
that start with the underscore (_) character, as was always done in
version 1.3 of the Web services engine. If not specified, element names
in WSDL will not start with the underscore character.
This parameter is ignored for version 1.3 of Web services engine.
printErrorDetails will show additional error information, such as stack
traces and error codes, if the command fails. This parameter is optional.
help displays the command syntax. This parameter is optional. 

iWS-FAQ-002: Come salvo e migro dei Web Service su un’altra partizione IBM i?

Quando dobbiamo migrare dei web service verso una nuova partizione IBM i (ad esempio cambio macchina o passaggio da Sviluppo a Produzione o tra due macchine in Clustering) dobbiamo conoscere un po’ meglio IWS:

I servizi che vediamo pubblicati dalla pagina http://myibmi:2001/HTTPAdmin risiedono in effetti nell’IFS in cartelle generalmente /www/nomedelserver … ad esempio /www/wservice. C’è inoltre una tabella di sistema che contiene un membro per ogni server delle applicazioni esistente

Salvare in un file la configurazione del webservice:

-- QSH and script directory
STRQSH
cd /QIBM/ProdData/OS/WebServices/V1/server/bin 
 
-- Save web service server
saveWebServicesServer.sh -server MyServer  -saveFile /qsys.lib/mylib.lib/mysavf.file 
--- Save some webservices
saveWebServices.sh -server MyServer -serviceList WS2:WS1  -saveFile /qsys.lib/mylib.lib/mysavf.file 

--- Trasfer your save file to another IBM i partition

-- Restore your web service server
restoreWebServicesServer.sh  -fromServerDirectory server-directory  -saveFile save-file  [ -printErrorDetails ] [ -help ] 

--- Restore some web services
restoreWebServices.sh -server MyServer2 -serviceList WS2:WS1  -fromServerDirectory /www/MyServer  -saveFile /qsys.lib/mylib.lib/mysavf.file 

Attenzione: se si stanno migrando i Web service su una nuova partizione IBM i, ad esempio in un cambio di macchina, consiglio di eseguire comunque un “Redeploy” di almeno un Web Service per ogni utente-web-service-server utilizzato: in fase di deploy l’utente del servizio viene autorizzato all’esecuzione dei web service: se non si fa questo passaggio potremmo andare in contro ad un errore 500 sui servizi trasferiti.

Seguono alcuni link di approfondimento sul tema:

• Supporto IBM: https://www-01.ibm.com/support/docview.wss?uid=isg3T1026868
• Supporto IBM: https://www-01.ibm.com/support/docview.wss?uid=nas8N1022190
• ItJungle: https://www.itjungle.com/2018/02/19/guru-moving-web-service-another-web-server/

iWS-FAQ-003: Recuperare le proprietà di un Web Service

Questo script estra le proprietà di un Web Service in un file in formato XML (PCML) … potrebbe risultare utile per installare nuovi web service su una seconda partizione partendo dalle proprietà estrette:

 getConfigurationFile.sh  -server WSERVICE -locationDirectory /tmp  -serviceList ConvertTemp 

installwebservice.sh     -server WSTEST   -propertiesFile    /tmp/ConvertTemp.properties 

Vedi guida su DeveloperWorks: https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/dW%20IBM%20Integrated%20Web%20Services%20for%20i/page/Script%20to%20generate%20property%20file%20for%20a%20service

iWS-FAQ-004: Pubblicare un REST web service direttamente con SQL senza RPG/Cobol?

Dalla versione 7.3 TR7 e 7.4 è possibile pubblicare come Web Service delle semplici istruzioni SQL sempilficando notevolmente la logica.

Ce ne parla direttamente Tim Rowe di IBM in questo post su IBM System Magazine: IBM SystemMag : Getting started with REST and SQL

iWS-FAQ-005: HTTPS e SSL con IBM i – La creazione del certificato *SYSTEM nel Digital Certificate Manager DCM

Per attivare le funzioni HTTPS / SSL nei web service da IBM i è necessario creare un certificato *SYSTEM di base al nostro IBM i … la procedura è molto semplice se si ha un utente autorizzato (autorizzazioni *SECOFR).

E’ sufficiente seguire i 5 passi qui riportati:

https://www.ibm.com/support/pages/how-create-system-store-dcm

iWS-FAQ-006: Utilizzare HTTPGETCLOB e JSON_TABLE per Geolocalizzare un indirizzo

Ormai la geolocalizzazione di un indirizzo è un tema all’ordine del giorno e, sempre più spesso, dobbiamo completare delle nostre tabelle degli indirizzi su IBM i con i dati di geo-localizzazione, latitudine, longitudine ecc. Anche per interfacciarci agli spedizionieri è sempre più importare riportare nelle anagrafiche gli indirizzi pre-formattati correttamente.

Sono disponibile su internet diversi servizi di geo-localizzazione partendo da un indirizzo … vediamo qui sotto come utilizzare i Servizi di Geocoding di Google (**) direttamente da uno statement SQL con HTTPGETCLOB e JSON_TABLE per recuperarne i metadati dal JSON ritornato.

Lo statement SQL è molto semplice e possiamo utilizzarlo direttamente da SQL Script oppure da RPG-SQL-Embedded e avere a disposizione i dati ritornati da memorizzare sulle nostre tabelle … in questa chiamata ho, naturalmente, sostituito la mia KEY di Google Maps con la scritta XXX_YOUR_KEY_HERE, metteteci la vostra KEY presa dal pannello di Google Developers

Select * from
 json_table(
 systools.httpgetclob('https://maps.googleapis.com/maps/api/geocode/json?address=Piazza+Duomo+1,20121+MIlano&components=country:IT&key=XXX_YOUR_KEY_HERE','')
,'$'
COLUMNS( 
formatted_address VARCHAR(200) PATH '$.results.formatted_address',
lat decimal(10, 7) PATH '$.results.geometry.location.lat',
lng decimal(10, 7) PATH '$.results.geometry.location.lng'


) ) as x;

Il risultato dello statement sopra è il seguente:

(**) Geocode è una delle API disponibili dal pannello dei servizi Google. Un tempo era gratuita … ora richiede la registrazione di un apposito account nella Google Cloud Platform, l’attivazione delle API desiderate e l’ottenimento di una KEY univoca di riconoscimento

Solo per gli indirizzi di US e Canada c’è il servizio gratuito United States CENSUS Bureau, gratuito:

Select * from
 json_table(
 systools.httpgetclob('https://geocoding.geo.census.gov/geocoder/locations/address?street=265+Peachtree+St+NE&city=Atlanta&state=GA&zip=30303&benchmark=Public_AR_Current&format=json','')
,'$'
COLUMNS( 
formatted_address VARCHAR(200) PATH '$.result.addressMatches.matchedAddress',
lat decimal(10, 7) PATH '$.result.addressMatches.coordinates.x',
lng decimal(10, 7) PATH '$.result.addressMatches.coordinates.y'
) ) as x;

Con questo risultato:

Se preferisci utilizzare RPG per consumare questo tipo di servizi dai una occhiata a questo post su FieldExit di Bradley Stone

--- Roberto De Pedrini Faq400.com