WSDL

Page last edited 2 037 giorni 15 ore fa
Da wiki.betaingegneria.it.

WSDL (Web Services Description Language)[modifica]

Sommario[modifica]

WSDL è un formato XML per descrivere i servizi di rete come un insieme di terminali (ports) che si scambiano messaggi contenenti informazioni di tipo orientato ai documenti o alle procedure. Cioè possono riguardare lo scambio di informazioni/documento o l'invocazione di funzionalità remote.

Le funzioni e i messaggi sono descritti in astratto, e quindi, successivamente, associati ad un protocollo di rete e ad un formato di messaggio reali per definire un terminale.

Gli oggetti fondamentali sono descritti più avanti, ma dal più elementare al più complesso sono:

  • i tipi (generalmente definiti come schemi XML o XSD) che rappresentano tipi di dato semplice o strutturato,
  • i messaggi (che istanziano i tipi precedentemente definiti), assimilabili alle variabili di una classe,
  • i tipi di terminale o portType, che definiscono una o più operazioni atomiche (li possiamo associare ai metodi di una classe) ognuna delle quali è costituita da più messaggi da scambiare tra client e server,
  • gli accessi o bindings che in sostanza sono l'associazione tra la definizione dell'operazione eseguibile via HTTP -- chje è l'oggetto del WSDL! -- (costituita da un input e un output) ed un tipo di terminale
  • infine i servizi sono l'esposizione di un accesso su un indirizzo internet HTTP

Ciascuno degli elementi listati sopra riutilizza uno o più degli elementi che lo precedono. Ad esempio

  • il portType comprende i messages definiti prima;
  • gli accessi (binding) definiscono come utilizzare i portType definiti precedentemente;
  • e così via.

Un esempio di documento WSDL[modifica]

L'esempio seguente rappresenta un servizio che accetta un nome in input (ad esempio Marco) e ritorna un saluto (Ciao Marco) nell'output.

Listato 1. Una descrizione WSDL per l'invio di un saluto[modifica]
<?xml version="1.0"?>
<definitions name="HelloService"
   targetNamespace="http://www.examples.com/wsdl/HelloService.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.examples.com/wsdl/HelloService.wsdl"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
   <message name="SayHelloRequest">
      <part name="firstName" type="xsd:string"/>
   </message>
   <message name="SayHelloResponse">
      <part name="greeting" type="xsd:string"/>
   </message>

   <portType name="Hello_PortType">
      <operation name="sayHello">
         <input message="tns:SayHelloRequest"/>
         <output message="tns:SayHelloResponse"/>
      </operation>
   </portType>

   <binding name="Hello_Binding" type="tns:Hello_PortType">
   <soap:binding style="rpc"
      transport="http://schemas.xmlsoap.org/soap/http"/>
   <operation name="sayHello">
      <soap:operation soapAction="sayHello"/>
      <input>
         <soap:body
            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            namespace="urn:examples:helloservice"
            use="encoded"/>
      </input>
      <output>
         <soap:body
            encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            namespace="urn:examples:helloservice"
            use="encoded"/>
      </output>
   </operation>
   </binding>

   <service name="Hello_Service">
      <documentation>WSDL File for HelloService</documentation>
      <port binding="tns:Hello_Binding" name="Hello_Port">
         <soap:address
            location="http://www.examples.com/SayHello/">
      </port>
   </service>
</definitions>

Il messaggio WSDL descritto[1] è composto di 5 sezioni:

  • types : in questo caso è un elenco di elementi che definiscono il tipo per:
    • la richiesta (request)
    • la risposta (response)
    • l'evenutale messaggio di errore
  • uno più nodi message che descrivono la struttura dei messaggi per la richiesta, la risposta e l'errore;
  • un nodo PortType che costituisce l'interfaccia (l'equivalente di una API): la traduciamo con tipo di terminale. Questa è la parte più interessante: il WSDL può funzionare in quattro modi (diversamente dallo standard HTTP che è sempre e solo Request-Reponse):
    • One-way (il client invia un messaggio al server e stop: Client →)
    • Request-Response (funzionamento tipico di HTTP: Client → Server <-)
    • Solicit Response (il server sollecita il client ad inviare un dato! e il client risponde. Server <- Client →)
    • Notification (il server notifica un messaggio al client senza attendere risposta: Server <-)
  • un nodo binding che definisce come i servizi definiti nella sezione portType vengono effettivamente inviati in rete. Traduciamo una volta per tutte il termine binding con accessi[2].
    • Gli accessi possono essere resi disponibili tramite mezzi di trasporto diversi, tra cui HTTP GET, POST HTTP o SOAP.
    • Gli accessi forniscono informazioni concrete su quale protocollo verrà utilizzato per il trasferimento delle operazioni definite in 'portType'
    • Gli accessi forniscono informazioni su dove si trova il servizio.
    • Per il protocollo SOAP, L'accesso si descrive con il tag <soap:binding>, e il livello di trasporto dei messaggi è SOAP, sopra il protocollo HTTP.
    • È possibile specificare più accessi per un unico tipo di terminale.
  • un nodo service che definisce il servizio nel suo complesso, fornendo la documentazione sul servizio, definendo la porta (nel senso della funzione definita dal port_type) nn ché l'URI al quale è invocabile il servizio.

In questo caso non viene utilizzato l'elemento types: ciò accade se lavoriamo con strutture dati fondamentali, come stringhe e numeri; se i dati hanno forma più complesse (strutture, oggetti etc.), allora si specificano i types.

Scheletro di un messaggio WSDL[modifica]

<definitions /> <= contiene i riferimenti alle definizioni dei namespace

<types /> <= un file XML (eventualmente riutilizzabile se salvato com namespace esterno) che definisce il typo di dati da scambiare; non serve se i dati sono di tipo semplice (numeri e stringhe). 

<messages /> <= uno o più messaggi contenenti il nome ed il tipo

<portTypes /> <= elenco della sequenza dei messaggi: viene specificato il messaggio di input, di output ed il messaggio di errore, nell'eventualità qualcosa non andasse bene 
(ad esempio il tipo di dato di ingresso non è giusto, si aspetta un intero e gli scrivo una stringa. In generale contiene uno o più nodi <operation> ciascuno dei quali è 
una sequenza <input> <output> e <fault>.

<bindings /> <= accesso: associazione tra l'interfaccia di I/O e tipo di terminale.

<service /> <= esposizione di un accesso su un indirizzo internet.

Esempio più cicciotto[modifica]

Questo esempio è la descrizione del web service InvioCertificato messo a punto dall'INPS che consente di inviare un certificato di malattia da parte di una azienda verso l'INPS nel caso in cui il dipendente debba assentarsi dal lavoro per malattia.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:requestns="http://inviocertificatorequest.xsd.cert.mirsac.sanita.finanze.it"
	xmlns:responsens="http://inviocertificatoresponse.xsd.cert.mirsac.sanita.finanze.it"
	xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:tns="http://inviocertificato.wsdl.cert.mir.sanita.finanze.it/wsdl/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	targetNamespace="http://inviocertificato.wsdl.cert.mir.sanita.finanze.it/wsdl/">
<!-- ===============================================================================
		DOCUMENTATION
     =============================================================================== -->
	<wsdl:documentation>
		Invio del certificato di malattia
		Versione 0.4
	</wsdl:documentation>
<!-- ===============================================================================
		TYPES
     =============================================================================== -->
	<wsdl:types>
		<xsd:schema elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
			<xsd:import
				namespace="http://inviocertificatorequest.xsd.cert.mirsac.sanita.finanze.it"
				schemaLocation="InvioCertificatoRequest.xsd"/>
		</xsd:schema>
		<xsd:schema elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
			<xsd:import
				namespace="http://inviocertificatoresponse.xsd.cert.mirsac.sanita.finanze.it"
				schemaLocation="InvioCertificatoResponse.xsd"/>
		</xsd:schema>
	</wsdl:types>
<!-- ===============================================================================
		MESSAGES
     =============================================================================== -->
	<wsdl:message name="invioCertificatoRequest">
		<wsdl:part element="requestns:InvioCertificato" name="invioCertificatoRequest"/>
	</wsdl:message>
	<wsdl:message name="invioCertificatoResponse">
		<wsdl:part element="responsens:RicevutaCertificato"	name="invioCertificatoResponse"/>
	</wsdl:message>
<!-- ===============================================================================
		PORT TYPES
     =============================================================================== -->
	<wsdl:portType name="invioCertificatoPT">
		<wsdl:operation name="invioCertificato">
			<wsdl:input message="tns:invioCertificatoRequest"/>
			<wsdl:output message="tns:invioCertificatoResponse"/>
		</wsdl:operation>
	</wsdl:portType>
<!-- ===============================================================================
		BINDINGS
     =============================================================================== -->
	<wsdl:binding name="invioCertificatoBinding" type="tns:invioCertificatoPT">
		<soap:binding style="document"
			transport="http://schemas.xmlsoap.org/soap/http"/>
			<wsdl:operation name="invioCertificato">
				<soap:operation soapAction="http://inviocertificato.wsdl.cert.mir.sanita.finanze.it/wsdl/InvioCertificato"/>
				<wsdl:input>
					<soap:body use="literal"/>
				</wsdl:input>
				<wsdl:output>
					<soap:body use="literal"/>
				</wsdl:output>
			</wsdl:operation>
	</wsdl:binding>
<!-- ===============================================================================
		SERVICE
     =============================================================================== -->
	<wsdl:service name="InvioCertificato">
		<wsdl:port binding="tns:invioCertificatoBinding" name="InvioCertificato">
			<soap:address
			location="https://mirservicetest.sanita.finanze.it/TrasmissioneCertificatiWeb/services/InvioCertificato"/>
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>

Studio analitico del descrittore[modifica]

Studiamolo un pezzo alla volta

Documentation[modifica]

Nel tag è scritta la descrizione del servizio, in italiano.

Types[modifica]

Sono previsti messaggi strutturati (non tipi semplici come stringhe o numeri) quindi il tipo dei messaggi va definito con precisione in questa sezione per mezzo di appositi file XSD. Occorre fornire, per ogni tipo, il namespace (URL base dei descrittori XML):

e la posizione dello schema (schemaLocation) che è il nome della risorsa XSD che descrive il tipo. In questo caso ci sono due tipi: uno per i messaggi da client a server (request) e uno per i messaggi da server a client (response):

  • InvioCertificatoRequest.xsd
  • InvioCertificatoResponse.xsd
Messages[modifica]

Ci sono due messaggi da scambiare, uno per ciascuno dei due tipi definiti prima:

  • invioCertificatoRequest composto di una sola parte:
    • requestns:InvioCertificato / invioCertificatoRequest
  • invioCertificatoResponse composto di una sola parte:
    • responsens:RicevutaCertificato / invioCertificatoResponse
Port Types[modifica]

Questa è la parte nevralgica che definisce il tipo di terminale, il come si succedono temporalmente le comunicazioni tra client e server:

Il tipo di terminale è definito con una solo operazione che si struttura in quest'ordine:

  • input: tns:invioCertificatoRequest
  • output: tns:invioCertificatoResponse

Qui tns è un indirizzo definito nel preambolo del WDSL tns sta per

  xmlns:tns="http://inviocertificato.wsdl.cert.mir.sanita.finanze.it/wsdl/"

in input, dunque il client comunica al server il messaggio invioCertificatoRequest definito prima; in output il server risponde con invioCertificatoResponse

Bindings[modifica]

L'accesso (binding) ha un nome (invioCertificatoBinding) ed in tipo (tns:invioCertificatoPT) che è il tipo di terminale definito nella sezione precedente.

La funzionalità cui si accede è un'operazione SOAP <soap:operation il cui URI è

 http://inviocertificato.wsdl.cert.mir.sanita.finanze.it/wsdl/InvioCertificato

Inoltre, l'interfaccia prevede un input e un output, ciascuno dei quali consiste in un struttura soap:body.

Service[modifica]

Infine si può definire il servizio che è definito da un nome (name) e da un terminale (port) specificato nel tag wsdl:port, e da un indirizzo al quale è possibile accedere al servizio

<soap:address location="https://mirservicetest.sanita.finanze.it/TrasmissioneCertificatiWeb/services/InvioCertificato"/>

Il software che dobbiamo sviluppare per accedere a quel servizio punterà a quell'URI.

Notes[modifica]

  1. WSDL Document Example
  2. Si potrebbero anche definire come "vie di accesso al servizio" o "associazioni".