Web Services Servizio Telematico Dogane

Web Services Servizio Telematico Dogane MANUALE PER L'UTENTE Pagina 1 di 21

Indice 1 Introduzione... 3 2 Test funzionale dei web services... 6 3 Creazione del client... 10 3.1 Soluzioni Open Source... 10 3.2 Soluzioni Proprietarie... 10 4 Funzionalità di base... 13 4.1 LS... 13 4.2 DIR... 13 4.3 PUT... 14 4.4 GET... 14 4.5 GETLOG... 14 5 Sicurezza... 16 6 WSDL Servizio Telematico Dogane... 17 Pagina 2 di 21

1 Introduzione Un Web Service è per definizione un servizio descritto dal fornitore (provider) in modo standard e indipendente dal linguaggio di programmazione in cui è stato sviluppato. Per usufruire dei Web Services forniti dal provider (servizio telematico doganale) occorre creare un client di Web Services. Ciò è possibile attraverso il file WSDL (Web Services Description Language) che definisce l interfaccia del servizio, cioè l elenco delle operazioni fornite, i vari parametri che ogni operazione si aspetta di ricevere da chi la richiama e l elenco dei parametri che l operazione fornisce come output. Un Web Service viene richiamato parametricamente dall utente del servizio (requester) attraverso programmi applicativi e basandosi su un protocollo di chiamata remota, indipendente dalla rete e dai linguaggi di programmazione, detto SOAP (Simple Object Access Protocol). Un documento WSDL è un documento XML che contiene un insieme di definizioni per descrivere il servizio (Web Service). Gli elementi più importanti utilizzati da WSDL sono i seguenti:? <types> definisce i tipi di dati utilizzati nel servizio;? <message> contiene le definizioni dei messaggi di scambio del servizio utilizzando parti definite come tipi nella sezione types;? <porttype> descrive il servizio, le operazioni che possono essere eseguite e i messaggi che sono coinvolti in queste operazioni. Per ogni metodo viene definito il messaggio di input ed il messaggio di output. L elemento portype può essere paragonato ad una libreria di funzioni in un tradizionale linguaggio di programmazione;? < binding> contiene il collegamento tra il porttype (cioè la definizione astratta del servizio) e l end-point fisico. Questa informazione indica il protocollo da utilizzare e come ricondurre i messaggi di input ed output al protocollo utilizzato;? <port> definisce la porta di accesso al servizio.un servizio può avere anche più porte ciascuna con un nome e un protocollo di binding;? <service> contiene la definizione del servizio in termini della sua descrizione e della posizione fisica del servizio (tipicamente il suo URL) definiti endpoint. Pagina 3 di 21

Il file WSDL che descrive i servizi (Web Services) esposti dal servizio telematico doganale è disponibile, per i client che devono utilizzarlo, collegandosi da un browser internet alle seguenti URL: ambiente di prova: https://ws-telematicoprova.agenziadogane.it/telematicoftpejbhttprouter/telematicoftpwsbindingimplservice/ META-INF/wsdl/TelematicoFtp.wsdl ambiente reale: https://ws-telematico.agenziadogane.it/telematicoftpejbhttprouter/telematicoftpwsbindingimplservice/ META-INF/wsdl/TelematicoFtp.wsdl ed è riportato nel presente documento al capitolo 6 WSDL Servizio Telematico Dogane. Per poter accedere alla pagina che espone il file WSDL è necessario inserire il nome utente e la password. Digitando la URL del WSDL viene infatti visualizzata la seguente pagina di login: Il nome utente è il codice fiscale del soggetto che ha richiesto l'adesione al servizio telematico seguito dal segno "-" e dal progressivo sede. La password è la "Password di accesso all'applicazione", relativa al codice fiscale prima indicato, che si trova indicata nella stampa fornita dal "Primo accesso". Pagina 4 di 21

Una volta effettuato l accesso con utente e password, il sistema fornisce in risposta il WSDL dell applicazione: Pagina 5 di 21

2 Test funzionale dei web services Si consiglia di effettuare un test sui Web Services esposti prima della creazione del client vero e proprio. A tale scopo l utente si può avvalere ad esempio del tool SoapUI, uno strumento Java Open Source, rilasciato sotto la licenza GNU LGPL (Lesser General Public License), estremamente utile e utilizzabile su qualsiasi piattaforma (Windows/Unix/Linux). SoapUI è destinato a sviluppatori e collaudatori di servizi web in quanto consente di ispezionare i servizi web, richiamarli, realizzarli e fare delle prove di carico. I test funzionali e di caricamento possono essere fatti sia interattivamente, usando una comoda interfaccia utente, che attraverso un processo automatico, grazie all'uso dei tool a linea di comando. Per quanto riguarda le funzionalità di invocazione e analisi dei Web Services, SoapUI mette a disposizione:? importazione del WSDL;? generazione automatica delle richieste;? supporto per i vari tipi di autenticazione (Digest, WS-Security, NTLM, ecc.);? supporto di SOAP 1.1 e 1.2;? editor con sintassi colorata e funzionalità di undo/redo e formattazione automatica. Per lo sviluppo e la validazione dei Web Services vi sono:? generazione del codice sia Client che Server con supporto dei toolkit più diffusi: JBossWS, JWSDP, Axis 1 e 2, XFire,.NET e gsoap;? generazione del WSDL da codice Java esistente;? generazione delle classi di binding XML per JAXB e XMLBeans;? validazione delle definizioni dei Web Services. Inoltre è possibile usare potenti funzioni per quanto riguarda sia i test funzionali dei Web Service che le prove di carico. In questo caso è possibile avere report dettagliati, statistiche varie, log completi e analisi sulle prestazioni. L interfaccia dell applicazione è intuitiva e facile da utilizzare come mostrato nella figura riportata di seguito. Pagina 6 di 21

Per effettuare i test di un web service è sufficiente creare un nuovo progetto specificando il nome ed il file WSDL descrittore del servizio. Verranno automaticamente create le chiamate ai diversi servizi esposti e per ogni chiamata sarà visualizzata una scheda in basso in cui è possibile specificare una serie di proprietà da aggiungere alla richiesta. Pagina 7 di 21

Per i web services esposti dal servizio telematico tali proprietà consentono di specificare il Nome utente e la Password per accedere al servizio. Nella finestra centrale è possibile visualizzare la richiesta SOAP. Mentre nella combo in alto bisogna specificare per ogni richiesta l endpoint del servizio: https://ws-telematicoprova.agenziadogane.it/telematicoftpejbhttprouter/telematicoftpwsbindingimplservice Pagina 8 di 21

selezionando la freccia verde in alto a destra otteniamo la risposta SOAP del server. In basso ci sono i vari log relativi alla chiamata. Pagina 9 di 21

3 Creazione del client Esistono diversi framework, Axis ne è un esempio, che a partire da un file WSDL creano il codice Java sia lato client che lato server. Questi framework possono essere integrati negli ambienti di sviluppo e quindi consentono di usufruire delle varie funzionalità fornite all interno di interfacce grafiche che agevolano lo sviluppatore. Esistono diversi prodotti dedicati ai web services da integrare nei vari IDE (Integrated Development Environment) sia nell ambito open source che in quello commerciale. 3.1 Soluzioni Open Source Gli IDE più conosciuti in ambito open source sono:? Eclipse? Netbeans Essi rendono molto più agevole l approccio top-down in quanto permettono di creare facilmente il client del web service mediante un interfaccia grafica partendo dal file WSDL. Dobbiamo tener presente che un client di servizi web potrebbe a sua volta essere una web application e quindi l ambiente di sviluppo in tal caso avrebbe bisogno di un application server di supporto. Eclipse è un ambiente di sviluppo integrato multi-linguaggio e multipiattaforma. Viene sviluppato da una comunità strutturata sullo stile dell'open source. Uno dei componenti più utili, per lo sviluppo di applicazioni Web, è certamente quello appartenente al progetto Web Tools Platform (WTP). WTP è una piattaforma che estende le funzionalità base di Eclipse e include strumenti di vario genere che possono facilitare in modo sostanziale il lavoro dello sviluppatore di web services; tra le funzionalità che spiccano vi sono un editor specifico, tools per il testing e API per supportare il programmatore durante la stesura del codice. L application server che solitamente si utilizza con Eclipse è Tomcat. NetBeans è un ambiente di sviluppo multi-linguaggio scritto interamente in Java. È stato scelto dalla Sun Microsystems come IDE ufficiale. Possiede numerosi plug-in ed interessanti wizard per sviluppare Web Services con facilità. L application server che normalmente utilizza è Glassfish, che rappresenta senza dubbio un ottima soluzione. 3.2 Soluzioni Proprietarie Oltre alle soluzioni open source descritte in precedenza ci sono diverse soluzioni proprietarie per la creazione di un client di servizi web tra cui ad esempio:? RAD (Rational Application Developer) di IBM.? Microsoft Visual Studio Pagina 10 di 21

In RAD la creazione delle classi java utili alla generazione del client è facile ed intuitiva. Basta inserire nel progetto il file WSDL, cliccando poi col tasto destro selezionare Servizi Web e di seguito Genera Client, apparirà la seguente finestra: Qui lo sviluppatore potrà selezionare le varie opzioni di configurazione tra cui ad esempio il runtime del servizio (JAX-WS nel nostro esempio). Visual studio è un ambiente di sviluppo integrato sviluppato da Microsoft, che supporta attualmente diversi tipi di linguaggio. Visual studio permette di creare client di web services grazie all integrazione del framework.net. Dato il file WSDL del servizio Web, possiamo creare una classe che faccia da proxy per una nostra futura pagina in ASP.NET, ovvero un componente che ci permetta di accedere in modo trasparente al Web Service, senza preoccuparci delle modalità con le quali questo viene chiamato ed utilizzato. La classe proxy metterà quindi a disposizione il servizio esattamente come se fosse un componente da noi realizzato ed utilizzato nel progetto. L'utility a riga di comando wsdl.exe dell'sdk di.net ci permette di generare una classe proxy: wsdl /language:cs http://localhost/webservice/wsftp.asmx?wsdl Il parametro language ci permette di specificare uno dei linguaggi supporati dal.net framework (nell'esempio si è richiesto a wsdl.exe di generare una classe C#). Il risultato della suddetta operazione è la generazione del file wsftp.cs, contenente il codice della classe proxy per il servizio. A questo punto non ci resta che compilare il file di cui sopra, sempre utilizzando l'sdk: csc /t:library /out: wsftp.dll wsftp.cs /r:system.dll /r:system.xml.dll /r:system.web.services.dll Pagina 11 di 21

Abbiamo cioè compilato la classe come libreria di classi (/t:library) indicando come risultato della compilazione wsftp.dll ed utilizzando i metadata specificati nei parametri /r. A questo punto il file wsftp.dll dovrà essere inserito nella cartella /BIN dell'applicazione che lo utilizzerà. Pagina 12 di 21

4 Funzionalità di base 4.1 LS La funzione consente di estrarre e fornire la lista dei file di risposta ed esito disponibili per l utente autorizzato al servizio, effettuando la ricerca in base ad uno specifico pattern e limitatamente ad un determinato intervallo temporale.? Input: rappresenta il pattern in base al quale viene filtrata la richiesta? Output: rappresenta la stringa che contiene l esito dell operazione e quindi il risultato della richiesta Di seguito un esempio dell output opportunamente rivisitato nell applicazione client a fronte del pattern di input: 00001209.* 00001209.B99 00001209.UYY.p7m 00001209.UXX.p7m 00001209.UCC.p7m 00001209.UBB.p7m 00001209.UAA.p7m 00001209.UB2.p7m 00001209.UB1.p7m 00001209.P99 4.2 DIR La funzione fornisce la lista dei file di risposta ed esito corredata con la relativa data dell operazione di invio al servizio telematico doganale. La funzione effettua la ricerca per un determinato intervallo temporale.? Input: Pattern in base al quale filtrare la richiesta? Output: Stringa contenete il risultato dell operazione Di seguito un esempio dell output opportunamente rivisitato da una possibile applicazione client a fronte del pattern di input: 00001209.* 14076171,00001209.B99,RISPOSTA,Dec 28 19:18,112 14076157,00001209.UYY.p7m,RISPOSTA,Dec 09 17:05,1890 14076156,00001209.UXX.p7m,RISPOSTA,Dec 09 16:42,1890 14076155,00001209.UCC.p7m,RISPOSTA,Dec 09 16:13,1890 14076154,00001209.UBB.p7m,RISPOSTA,Dec 09 16:12,1890 14076153,00001209.UAA.p7m,RISPOSTA,Dec 09 13:32,1890 14076152,00001209.UB2.p7m,RISPOSTA,Dec 09 13:19,1890 14076171,00001209.P99,ESITO,Dec 09 19:22,330 Pagina 13 di 21

Nell ordine i dati riportati sono: codice file, nome file ricevuta, tipo ricevuta, data, dimensioni ricevuta. 4.3 PUT La funzione realizza la trasmissione di un file al servizio telematico doganale.? Input: una stringa contenente il nome del file e un array di byte per il file stesso? Output: una stringa contenente il risultato dell operazione. In caso di esito positivo viene restituito il nome del file, la data di trasmissione e il codice del file. In caso di esito negativo viene prodotta una segnalazione con il codice di errore riscontrato. Si precisa che, poiché la funzione esposta prende in input la rappresentazione in byte del file che si vuole trasmettere al servizio telematico doganale, la lettura iniziale del file e la successiva trasformazione in array di byte sono demandati all applicazione client. Di seguito un esempio dell output per esito positivo: Upload del file: Output : C:\Programmi\FirmaVerifica2.1\firmati\00001122.I08.p7m Caricato con successo. Di seguito un esempio dell output per esito negativo, dovuto al fatto che l utente collegato ha codice utente abilitato 0000 mentre ha trasmesso un file il cui nome presenta i primi 4 caratteri diversi da tale codice: Upload del file: Output : C:\Programmi\FirmaVerifica2.1\firmati\057R1209.I0B.p7m Nome file fuori formato: deve iniziare con le prime 4 lettere del codice utente. 4.4 GET La funzione esposta realizza il download di un file di risposta o di esito secondo quanto richiesto dall utente.? Input: Stringa contenente il nome del file da scaricare.? Output: Il file richiesto in formato array di byte. 4.5 GETLOG La funzione consente di effettuare il download del file di log degli errori delle operazioni effettuate in un determinato intervallo di tempo. Esempio di contenuto del file di log: Pagina 14 di 21

[06/12/2010 12:26:20] 000010.13.CD2.p7m : Nome file fuori formato: la lunghezza è errata [06/12/2010 09:48:13] 00000126.HAA : Il file non appartiene ad una tipologia abilitata [06/12/2010 13:49:27] 057R1209.I0B.p7m : Nome file fuori formato: deve iniziare con le prime 4 lettere del codice utente [07/12/2010 15:33:26] 00001122.I05 : Verificare che il file sia stato firmato [07/12/2010 15:35:52] 0103.Ra11 : Nome file fuori formato: la lunghezza è errata Pagina 15 di 21

5 Sicurezza L accesso ai Web Services è regolato da un autenticazione di tipo BASIC per il passaggio delle credenziali che saranno verificate dal sistema LDAP attualmente esistente. In fase di realizzazione dell applicazione client sarà dunque necessario definire, secondo lo standard JAXWS, le policy di accesso al Web service. L utente deve cioè indicare username e password di accesso al momento della chiamata ai diversi servizi. Di seguito forniamo un esempio di una chiamata dell operazione DIR realizzata in linguaggio java: TelematicoFtpWsBindingImplProxy service = new TelematicoFtpWsBindingImplProxy(); BindingProvider bp = (BindingProvider) service._getdescriptor().getproxy(); bp.getrequestcontext().put(bindingprovider.username_property, "USERNAME"); bp.getrequestcontext().put(bindingprovider.password_property, "PASSWORD"); String result = service.dir(pattern); Pagina 16 di 21

6 WSDL Servizio Telematico Dogane <?xmlversion="1.0" encoding="utf-8"?> -<wsdl:definitions targetnamespace="http://webservices.ftp.telematico.dogana.dogane.ag _dogane.finanze.it" xmlns:impl="http://webservices.ftp.telematico.dogana.dogane.ag_dogane.finanze.it " xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/ " xmlns:intf="http://webservices.ftp.telematico.dogana.dogane.ag_dogane.finanze.it" xmlns:xsd="http://www.w3.org/2001/xm LSchema" xmlns:wsi="http://wsi.org/profiles/basic/1.1/xsd" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/ "> -<wsdl:types> -<schema targetnamespace="http://webservices.ftp.telematico.dogana.dogane.ag_dogane.finanze.it " xmlns="http://www.w3.org/2001/xm LSchema"> -<element name="lsresponse"> <element name="lsreturn" nilable="true" type="xsd:string" /> -<element name="dir"> <element name="pattern" nilable="true" type="xsd:string" /> -<element name="dirresponse"> <element name="dirreturn" nilable="true" type="xsd:string" /> -<element name="getlog"> <sequence /> -<element name="getlogresponse"> <element name="getlogreturn" type="xsd:base64binary" /> Pagina 17 di 21

-<element name="get"> <element name="filename" nilable="true" type="xsd:string" /> -<element name="getresponse"> <element name="getreturn" type="xsd:base64binary" /> -<element name="put"> <element name="filem sg_content" type="xsd:base64binary" /> <element name="filem sg_n ome" nilable="true" type="xsd:string" /> -<element name="putresponse"> <element name="putreturn" nilable="true" type="xsd:string" /> -<element name="mget"> <element name="mgetinput_n ome" nilable="true" type="xsd:string" /> <element name="mgetinput_prog" nilable="true" type="xsd:string" /> -<element name="mgetresponse"> <element name="mgetreturn" type="xsd:base64binary" /> -<element name="ls"> Pagina 18 di 21

<element name="pattern" nilable="true" type="xsd:string" /> </schema> </wsdl:types> -<wsdl:message name="putrequest"> <wsdl:part name="parameters" element="impl:put" /> -<wsdl:message name="putresponse"> <wsdl:part name="parameters" element="impl:putresponse" /> -<wsdl:message name="getlogrequest"> <wsdl:part name="parameters" element="impl:getlog" /> -<wsdl:message name="dirrequest"> <wsdl:part name="parameters" element="impl:dir" /> -<wsdl:message name="mgetrequest"> <wsdl:part name="parameters" element="impl:mget" /> -<wsdl:message name="getresponse"> <wsdl:part name="parameters" element="impl:getresponse" /> -<wsdl:message name="lsrequest"> <wsdl:part name="parameters" element="impl:ls" /> -<wsdl:message name="lsresponse"> <wsdl:part name="parameters" element="impl:lsresponse" /> -<wsdl:message name="getrequest"> <wsdl:part name="parameters" element="impl:get" /> -<wsdl:message name="mgetresponse"> <wsdl:part name="parameters" element="impl:mgetresponse" /> -<wsdl:message name="dirresponse"> <wsdl:part name="parameters" element="impl:dirresponse" /> -<wsdl:message name="getlogresponse"> <wsdl:part name="parameters" element="impl:getlogresponse" /> -<wsdl:porttype name="telematicoftpw sbindingimpl"> -<wsdl:operation name="ls"> <wsdl:input name="lsrequest" message="impl:lsrequest" /> <wsdl:output name="lsresponse" message="impl:lsresponse" /> -<wsdl:operation name="dir"> Pagina 19 di 21

<wsdl:input name="dirrequest" message="impl:dirrequest" /> <wsdl:output name="dirresponse" message="impl:dirresponse" /> -<wsdl:operation name="getlog"> <wsdl:input name="getlogrequest" message="impl:getlogrequest" /> <wsdl:output name="getlogresponse" message="impl:getlogresponse" /> -<wsdl:operation name="get"> <wsdl:input name="getrequest" message="impl:getrequest" /> <wsdl:output name="getresponse" message="impl:getresponse" /> -<wsdl:operation name="put"> <wsdl:input name="putrequest" message="impl:putrequest" /> <wsdl:output name="putresponse" message="impl:putresponse" /> -<wsdl:operation name="mget"> <wsdl:input name="mgetrequest" message="impl:mgetrequest" /> <wsdl:output name="mgetresponse" message="impl:mgetresponse" /> </wsdl:porttype> -<wsdl:binding name="telematicoftpw sbindingimplsoapbinding " type="impl:telematicoftpw sbindingimpl"> <wsaw:usingaddressing wsdl:required="false" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" /> <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http " /> -<wsdl:operation name="ls"> <wsdlsoap:operation soapaction="ls" /> -<wsdl:input name="lsrequest"> </wsdl:input> -<wsdl:output name="lsresponse"> </wsdl:output> -<wsdl:operation name="dir"> <wsdlsoap:operation soapaction="dir" /> -<wsdl:input name="dirrequest"> </wsdl:input> -<wsdl:output name="dirresponse"> </wsdl:output> -<wsdl:operation name="getlog"> <wsdlsoap:operation soapaction="getlog" /> -<wsdl:input name="getlogrequest"> </wsdl:input> Pagina 20 di 21

-<wsdl:output name="getlogresponse"> </wsdl:output> -<wsdl:operation name="get"> <wsdlsoap:operation soapaction="get" /> -<wsdl:input name="getrequest"> </wsdl:input> -<wsdl:output name="getresponse"> </wsdl:output> -<wsdl:operation name="put"> <wsdlsoap:operation soapaction="put" /> -<wsdl:input name="putrequest"> </wsdl:input> -<wsdl:output name="putresponse"> </wsdl:output> -<wsdl:operation name="mget"> <wsdlsoap:operation soapaction="mget" /> -<wsdl:input name="mgetrequest"> </wsdl:input> -<wsdl:output name="mgetresponse"> </wsdl:output> </wsdl:binding> -<wsdl:service name="telematicoftpw sbindingimplservice "> <wsdl:port name="telematicoftpw sbindingimpl" binding="impl:telematicoftpw sbindingimplsoapbinding " /> </wsdl:service> </wsdl:definitions> Pagina 21 di 21