MANUALE PER L'UTENTE Web Services Servizio Telematico Dogane - Web Services Servizio Telematico Dogane - Manuale per l'utente
←
→
Trascrizione del contenuto della pagina
Se il tuo browser non visualizza correttamente la pagina, ti preghiamo di leggere il contenuto della pagina quaggiù
Web Services Servizio Telematico Dogane – Manuale per l’utente
Web Services
Servizio Telematico Dogane
MANUALE PER L'UTENTE
Versione del 04 Aprile 2012
Pagina 1 di 21
Web Services Servizio Telematico Dogane – Manuale per l’utente
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
Versione del 04 Aprile 2012
Pagina 2 di 21
Web Services Servizio Telematico Dogane – Manuale per l’utente
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:
?
definisce i tipi di dati utilizzati nel servizio;
?
contiene le definizioni dei messaggi di scambio del servizio utilizzando parti definite come tipi
nella sezione types;
?
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;
?
definisce la porta di accesso al servizio .Un servizio può avere anche più porte ciascuna con un
nome e un protocollo di binding;
?
contiene la definizione del servizio in termini della sua descrizione e della posizione fisica del
servizio (tipicamente il suo URL) – definiti endpoint.
Versione del 04 Aprile 2012
Pagina 3 di 21
Web Services Servizio Telematico Dogane – Manuale per l’utente
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".
Versione del 04 Aprile 2012
Pagina 4 di 21
Web Services Servizio Telematico Dogane – Manuale per l’utente
Una volta effettuato l’accesso con utente e password, il sistema fornisce in risposta il WSDL
dell’applicazione:
Versione del 04 Aprile 2012
Pagina 5 di 21
Web Services Servizio Telematico Dogane – Manuale per l’utente
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.
Versione del 04 Aprile 2012
Pagina 6 di 21
Web Services Servizio Telematico Dogane – Manuale per l’utente
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.
Versione del 04 Aprile 2012
Pagina 7 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
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
Versione del 04 Aprile 2012
Pagina 8 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
selezionando la freccia verde in alto a destra otteniamo la risposta SOAP del server.
In basso ci sono i vari log relativi alla chiamata.
Versione del 04 Aprile 2012
Pagina 9 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
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®
Versione del 04 Aprile 2012
Pagina 10 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
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
Versione del 04 Aprile 2012
Pagina 11 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
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à.
Versione del 04 Aprile 2012
Pagina 12 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
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
Versione del 04 Aprile 2012
Pagina 13 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
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: C:\Programmi\FirmaVerifica2.1\firmati\00001122.I08.p7m
Output : 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: C:\Programmi\FirmaVerifica2.1\firmati\057R1209.I0B.p7m
Output : 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:
Versione del 04 Aprile 2012
Pagina 14 di 21Web 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 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
Versione del 04 Aprile 2012
Pagina 15 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
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);
Versione del 04 Aprile 2012
Pagina 16 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
6 WSDL – Servizio Telematico Dogane
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Versione del 04 Aprile 2012
Pagina 17 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Versione del 04 Aprile 2012
Pagina 18 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Versione del 04 Aprile 2012
Pagina 19 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
-
-
-
-
-
-
-
-
-
-
-
-
-
Versione del 04 Aprile 2012
Pagina 20 di 21Web Services Servizio Telematico Dogane – Manuale per l’utente
-
-
-
-
-
-
-
-
-
-
-
Versione del 04 Aprile 2012
Pagina 21 di 21Puoi anche leggere
