Web Services Servizio Telematico Dogane MANUALE PER L'UTENTE

Web Services Servizio Telematico Dogane – Manuale per l’utenteWeb ServicesServizio Telematico DoganeMANUALE PER L'UTENTEPagina 1 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente1 IntroduzioneUn Web Service è per definizione un servizio descritto dal fornitore (provider) in modo standard eindipendente dal linguaggio di programmazione in cui è stato sviluppato.Per usufruire dei Web Services forniti dal provider (servizio telematico doganale) occorre creare unclient di Web Services.Ciò è possibile attraverso il file WSDL (Web Services Description Language) che definiscel’interfaccia del servizio, cioè l’elenco delle operazioni fornite, i vari parametri che ogni operazione siaspetta 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) attraversoprogrammi applicativi e basandosi su un protocollo di chiamata remota, indipendente dalla rete e dailinguaggi di programmazione, detto SOAP (Simple Object Access Protocol).Un documento WSDL è un documento XML che contiene un insieme di definizioni per descrivere ilservizio (Web Service). Gli elementi più importanti utilizzati da WSDL sono i seguenti:? definisce i tipi di dati utilizzati nel servizio;? contiene le definizioni dei messaggi di scambio del servizio utilizzando parti definite come tipinella sezione types;? descrive il servizio, le operazioni che possono essere eseguite e i messaggi che sono coinvoltiin queste operazioni. Per ogni metodo viene definito il messaggio di input ed il messaggio dioutput. L’elemento porType può essere paragonato ad una libreria di funzioni in untradizionale linguaggio di programmazione;? < binding>contiene il collegamento tra il portType (cioè la definizione astratta del servizio) e l’end-pointfisico. Questa informazione indica il protocollo da utilizzare e come ricondurre i messaggi diinput ed output al protocollo utilizzato;? definisce la porta di accesso al servizio .Un servizio può avere anche più porte ciascuna con unnome e un protocollo di binding;? contiene la definizione del servizio in termini della sua descrizione e della posizione fisica delservizio (tipicamente il suo URL) – definiti endpoint.Pagina 3 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utenteIl 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.wsdlambiente reale:https://ws-telematico.agenziadogane.it/TelematicoFtpEjbHttpRouter/TelematicoFtpWsBindingImplService/META-INF/wsdl/TelematicoFtp.wsdled è 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 lapassword. 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 telematicoseguito dal segno "-" e dal progressivo sede.La password è la "Password di accesso all'applicazione", relativa al codice fiscale prima indicato, chesi trova indicata nella stampa fornita dal "Primo accesso".Pagina 4 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utenteUna volta effettuato l’accesso con utente e password, il sistema fornisce in risposta il WSDLdell’applicazione:Pagina 5 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente2 Test funzionale dei web servicesSi consiglia di effettuare un test sui Web Services esposti prima della creazione del client vero eproprio.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 eutilizzabile su qualsiasi piattaforma (Windows/Unix/Linux).SoapUI è destinato a sviluppatori e collaudatori di servizi web in quanto consente di ispezionare iservizi web, richiamarli, realizzarli e fare delle prove di carico.I test funzionali e di caricamento possono essere fatti sia interattivamente, usando una comodainterfaccia 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 adisposizione:? 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 chele prove di carico. In questo caso è possibile avere report dettagliati, statistiche varie, log completi eanalisi sulle prestazioni.L’interfaccia dell’applicazione è intuitiva e facile da utilizzare come mostrato nella figura riportata diseguito.Pagina 6 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utentePer effettuare i test di un web service è sufficiente creare un nuovo progetto specificando il nome ed ilfile 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 allarichiesta.Pagina 7 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utentePer i web services esposti dal servizio telematico tali proprietà consentono di specificare il Nomeutente e la Password per accedere al servizio.Nella finestra centrale è possibile visualizzare la richiesta SOAP. Mentre nella combo in alto bisognaspecificare per ogni richiesta l’endpoint del servizio:https://ws-telematicoprova.agenziadogane.it/TelematicoFtpEjbHttpRouter/TelematicoFtpWsBindingImplServicePagina 8 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utenteselezionando 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 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente3 Creazione del clientEsistono diversi framework, Axis ne è un esempio, che a partire da un file WSDL creano il codiceJava sia lato client che lato server.Questi framework possono essere integrati negli ambienti di sviluppo e quindi consentono di usufruiredelle 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 DevelopmentEnvironment) sia nell’ambito open source che in quello commerciale.3.1 Soluzioni Open SourceGli IDE più conosciuti in ambito open source sono:? Eclipse? NetbeansEssi rendono molto più agevole l’approccio top-down in quanto permettono di creare facilmente ilclient 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 applicatione 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 dauna comunità strutturata sullo stile dell'open source. Uno dei componenti più utili, per lo sviluppo diapplicazioni 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 chepossono 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 programmatoredurante 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 dallaSun Microsystems come IDE ufficiale. Possiede numerosi plug-in ed interessanti wizard persviluppare Web Services con facilità. L’application server che normalmente utilizza è Glassfish, cherappresenta senza dubbio un’ottima soluzione.3.2 Soluzioni ProprietarieOltre alle soluzioni open source descritte in precedenza ci sono diverse soluzioni proprietarie per lacreazione di un client di servizi web tra cui ad esempio:? RAD (Rational® Application Developer) di IBM.? Microsoft Visual Studio®Pagina 10 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utenteIn RAD la creazione delle classi java utili alla generazione del client è facile ed intuitiva. Bastainserire nel progetto il file WSDL, cliccando poi col tasto destro selezionare “Servizi Web” e diseguito “Genera Client”, apparirà la seguente finestra:Qui lo sviluppatore potrà selezionare le varie opzioni di configurazione tra cui ad esempio il runtimedel servizio (JAX-WS nel nostro esempio).Visual studio è un ambiente di sviluppo integrato sviluppato da Microsoft, che supporta attualmentediversi tipi di linguaggio. Visual studio permette di creare client di web services grazieall’integrazione del framework .NET. Dato il file WSDL del servizio Web, possiamo creare una classeche faccia da proxy per una nostra futura pagina in ASP.NET, ovvero un componente che ci permettadi accedere in modo trasparente al Web Service, senza preoccuparci delle modalità con le quali questoviene chiamato ed utilizzato. La classe proxy metterà quindi a disposizione il servizio esattamentecome 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?WSDLIl 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 dellaclasse 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.dllPagina 11 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utenteAbbiamo cioè compilato la classe come libreria di classi (/t:library) indicando come risultato dellacompilazione 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 loutilizzerà.Pagina 12 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente4 Funzionalità di base4.1 LSLa funzione consente di estrarre e fornire la lista dei file di risposta ed esito disponibili per l’utenteautorizzato al servizio, effettuando la ricerca in base ad uno specifico pattern e limitatamente ad undeterminato 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 dellarichiestaDi seguito un esempio dell’output opportunamente rivisitato nell’applicazione client a fronte delpattern di input: 00001209.*00001209.B9900001209.UYY.p7m00001209.UXX.p7m00001209.UCC.p7m00001209.UBB.p7m00001209.UAA.p7m00001209.UB2.p7m00001209.UB1.p7m00001209.P994.2 DIRLa funzione fornisce la lista dei file di risposta ed esito corredata con la relativa data dell’operazionedi 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’operazioneDi seguito un esempio dell’output opportunamente rivisitato da una possibile applicazione client afronte del pattern di input: 00001209.*14076171,00001209.B99,RISPOSTA,Dec 28 19:18,11214076157,00001209.UYY.p7m,RISPOSTA,Dec 09 17:05,189014076156,00001209.UXX.p7m,RISPOSTA,Dec 09 16:42,189014076155,00001209.UCC.p7m,RISPOSTA,Dec 09 16:13,189014076154,00001209.UBB.p7m,RISPOSTA,Dec 09 16:12,189014076153,00001209.UAA.p7m,RISPOSTA,Dec 09 13:32,189014076152,00001209.UB2.p7m,RISPOSTA,Dec 09 13:19,189014076171,00001209.P99,ESITO,Dec 09 19:22,330Pagina 13 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utenteNell’ordine i dati riportati sono: codice file, nome file ricevuta, tipo ricevuta, data, dimensioniricevuta.4.3 PUTLa 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 sivuole trasmettere al servizio telematico doganale, la lettura iniziale del file e la successivatrasformazione 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.p7mCaricato con successo.Di seguito un esempio dell’output per esito negativo, dovuto al fatto che l’utente collegato ha codiceutente abilitato 0000 mentre ha trasmesso un file il cui nome presenta i primi 4 caratteri diversi da talecodice:Upload del file:Output :C:\Programmi\FirmaVerifica2.1\firmati\057R1209.I0B.p7mNome file fuori formato: deve iniziare con le prime 4 lettere del codiceutente.4.4 GETLa funzione esposta realizza il download di un file di risposta o di esito secondo quanto richiestodall’utente.? Input: Stringa contenente il nome del file da scaricare.? Output: Il file richiesto in formato array di byte.4.5 GETLOGLa funzione consente di effettuare il download del file di log degli errori delle operazioni effettuate inun determinato intervallo di tempo.Esempio di contenuto del file di log:Pagina 14 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente[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 delcodice 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 è errataPagina 15 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente5 SicurezzaL’accesso ai Web Services è regolato da un’autenticazione di tipo BASIC per il passaggio dellecredenziali che saranno verificate dal sistema LDAP attualmente esistente.In fase di realizzazione dell’applicazione client sarà dunque necessario definire, secondo lo standardJAXWS, le policy di accesso al Web service.L’utente deve cioè indicare username e password di accesso al momento della chiamata ai diversiservizi.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 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente6 WSDL – Servizio Telematico Dogane-----------------Pagina 17 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente---------------------Pagina 18 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente---------------Pagina 19 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente-------------Pagina 20 di 21Versione del 04 Aprile 2012

Web Services Servizio Telematico Dogane – Manuale per l’utente-----------Pagina 21 di 21Versione del 04 Aprile 2012