3.7 X-tee andmeteenuste WSDL

X-tee andmeteenuste kirjeldamiseks kasutatakse WSDL 1.1 dokumente, millele on rakendatud teatud kitsendusi ning mille kirjeldustes peavad olema X-tee andmeteenuste jaoks kohustuslikud elemendid. Andmeteenuste sisend- ja väljundparameetrid kirjeldatakse XML-skeemina.

Andmeteenuste defineerimise nimeruum ei ole normeeritud X-tee protokolli tasandil. Nimeruumide andmise ja võtmise reeglid peavad liikmed/arendajad, vastavalt XML/XSD/SOAP/WSDL-standarditele, ise läbi mõtlema. Nimeruumist räägime moodulis 4.

3.7.1  WSDL-vormingu kirjeldus

WSDL kirjeldab XML-formaadis ära andmeteenused, nende andmeteenuste sisend-ja väljundsõnumid ning milliste protokollidega ja mis aadressil andmeteenuseid välja kutsutakse.

Joonisel 14 on esitatud WSDL-kirjelduse struktuur ning selle all struktuur XML-formaadis. Pärast üldist struktuuri vaatame konkreetseid plokke – types, message, portType, binding ja service – eraldi.

Joonis 14 WSDL 1.1 struktuur

 

<wsdl:definitions name=”person_register” targetNamespace=”http://persons_register.x-road.ee”>

<wsdl:import namespace=”http://x-road.eu/xsd/xroad.xsd” location=”http://x-road.eu/xsd/xroad.xsd"/>

  <wsdl:types>

    <xsd:schema> … </xsd:schema>

  </wsdl:types>

  <wsdl:message> … </wsdl:message>

  <wsdl:portType>

    <wsdl:operation>

      <wsdl:input> … </wsdl:input>

      <wsdl:output> … </wsdl:output>

    </wsdl:operation>

  </wsdl:portType>

  <wsdl:binding> … </wsdl:binding>

  <wsdl:service>

    <wsdl:port> … </wsdl:port>

  </wsdl:service>

</wsdl:definitions>

3.7.2  types

WSDL-kirjelduse <types> plokis on XML-skeemina kirjeldatud andmetüüpide ja elementide definitsioonid. Skeemid võivad paikneda WSDL dokumendi sees, aga neid saab ka väljastpoolt importida. Skeemide importimisest räägitakse põhjalikumalt punktis 3.9.

XML-skeemi näide:

<xsd:schema targetNamespace="http://persons_register.x-road.ee">

  <xsd:element name="personList">

    <xsd:complexType>

      <xsd:sequence>

        <xsd:element name="firstName" type="xsd:string">

          <xsd:annotation>

            <xsd:appinfo>

              <xrd:title xml:lang="et">Eesnimi</xrd:title>

            </xsd:appinfo>

          </xsd:annotation>

        </xsd:element>

        <xsd:element name="lastName" type="xsd:string">

          <xsd:annotation>

            <xsd:appinfo>

              <xrd:title xml:lang="et">Perenimi</xrd:title>

            </xsd:appinfo>

          </xsd:annotation>

        </xsd:element>

      </xsd:sequence>

    </xsd:complexType>

  </xsd:element>

  <xsd:element name="personListResponse">

    <xsd:complexType>

      <xsd:sequence>

        <xsd:element name="person" type="tns:person" />

      </xsd:sequence>

    </xsd:complexType>

  </xsd:element>

  <xsd:complexType name="contact">

    <xsd:sequence>

      <xsd:element name="phone" type="xsd:string" maxOccurs="unbounded" minOccurs="0" />

      <xsd:element name="e-mail" type="xsd:string" maxOccurs="unbounded" minOccurs="0" />

      <xsd:element name="address" type="xsd:string" maxOccurs="1" minOccurs="0" />

    </xsd:sequence>

  </xsd:complexType>

  <xsd:complexType name="person">

    <xsd:sequence>

      <xsd:element name="personId" type="xsd:string" />

      <xsd:element name="firstName" type="xsd:string" />

      <xsd:element name="lastName" type="xsd:string" />

      <xsd:element name="birthDate" type="xsd:date" />

      <xsd:element name="personContact" type="tns:contact" />

    </xsd:sequence>

  </xsd:complexType>

</xsd:schema>

Komplekstüüpi element personList koosneb kahest alamelemendist firstName ja lastName, mis on annoteeritud xrd:title dokumentatsioonielemendiga. Struktuuri selgema edastamise eesmärgil oleme jätnud siinkohal ülejäänud elementidel xrd:title dokumentatsioonielemendi kirjeldamata. Komplekstüüpi element personListResonse alamelement on person, mille tüüp on samas skeemis defineeritud komplekselement person, alamelementidega personId, firstName, lastName, birthDate, personContact. Neist viimase – personContact – tüüp on omakorda samas skeemis kirjeldatud contact alamelementidega phone, e-mail ja address.

3.7.3  message

WSDL-kirjelduse <message> plokkidega on kirjeldatud sõnumite tüübid, mis on koostatud <types> plokis kirjeldatud XML-skeemi elementidest. X-teel defineeritakse ka sõnum päiseväljade kirjeldamiseks.

<wsdl:message name="xrdheader">

                <wsdl:part name="client" element="xrd:client"/>

                <wsdl:part name="service" element="xrd:service"/>

                <wsdl:part name="userId" element="xrd:userId"/>

                <wsdl:part name="id" element="xrd:id"/>

                <wsdl:part name="protocolVersion" element="xrd:protocolVersion"/>

</wsdl:message>

<wsdl:message name="personListRequest">

                <wsdl:part element="tns:personList" name="parameters"/>

</wsdl:message>

<wsdl:message name="personListResponse">

                <wsdl:part element="tns:personListResponse" name="parameters"/>

</wsdl:message>

3.7.4  portType

WSDL-kirjelduse <portType > plokk kirjeldab ära X-tee andmeteenuste <operation> nimed ning seob andmeteenuse sisendi ja väljundi <message> plokkides kirjeldatud sõnumitüüpidega. personList on andmeteenuse nimi ning  personListRequest ja personListResponse andmeteenusele vastavad sisend- ja väljundsõnumid.

<wsdl:portType name="person_register">

                <wsdl:operation name="personList">

                               <wsdl:documentation>

                                               <xrd:title xml:lang="et">Isikute nimekirja küsimine nime järgi</xrd:title>

                               </wsdl:documentation>

                               <wsdl:input message="tns:personListRequest"/>

                               <wsdl:output message="tns:personListResponse"/>

                </wsdl:operation>

</wsdl:portType>

3.7.5 binding (andmeteenuse ja sõnumiprotokolli sidumine)

WSDL dokumendi <binding> osa kirjeldab kuidas siduda andmeteenus sõnumiprotokolliga. X-teel kasutatakse andmeteenuse ja sõnumiprotokolli sidumiseks Document/literal wrapped stiili. Document/literal wrapped stiili määramiseks peab WSDL dokumendi <binding> osas määrama stiili style=”document” ja literaalkasutuse use=”literal”, nagu on näidatud järgnevas WSDL dokumendi fragmendis. <binding> osas määratakse ka transpordiprotokoll (HTTP) ning SOAP-sõnumi päiseväljad.

<wsdl:binding name="person_registerSOAP" type="tns:person_register">

  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

  <wsdl:operation name="personList">

    <soap:operation soapAction=""/>

      <xrd:version>v1</xrd:version>

        <wsdl:input name=”personList”>

          <soap:body use="literal"/>

          <soap:header message="tns:xrdheader" part="client" use="literal"/>

          <soap:header message="tns:xrdheader" part="service" use="literal"/>

          <soap:header message="tns:xrdheader" part="userId" use="literal"/>

          <soap:header message="tns:xrdheader" part="id" use="literal"/>

          <soap:header message="tns:xrdheader" part="protocolVersion" use="literal"/>

        </wsdl:input>

        <wsdl:output name=”personListResponse”>

          <soap:body use="literal"/>

          <soap:header message="tns:xrdheader" part="client" use="literal"/>

          <soap:header message="tns:xrdheader" part="service" use="literal"/>

          <soap:header message="tns:xrdheader" part="userId" use="literal"/>

          <soap:header message="tns:xrdheader" part="id" use="literal"/>

          <soap:header message="tns:xrdheader" part="protocolVersion" use="literal"/>

        </wsdl:output>

    </wsdl:operation>

</wsdl:binding>

 

Erinevalt RPC stiilist ei sisalda Document stiili puhul SOAP keha WSDL operatsiooni nime vaid ainult päringu sisu. Dokumendistiili (Document style) literaalkasutus (literal use) tähendab seda, et elementide tüübid on tuletatavad XML skeemist ning tüüpide kodeerimisinfot ei korrata SOAP-protokolli kehas.

Document/literal wrapped stiili puhul on sõnumi parameetritele XML-skeemis tekitatud mähkurelemendid (wrappers). Kusjuures sõnumi sisendparameetrite mähkurelement kannab sama nime WSDL operatsiooniga ning väljundparameetrite mähkurelement saadakse operatsiooni nimele “Response” lisamisega. X-tee spetsiifikast tulenevalt peab SOAP päisevälja serviceCode väärtus kattuma sõnumi sisendparameetrite mähkurelemendi nimega. Wrapped stiili eelis mitte-wrapped stiili ees on see, et SOAP-protokolli kehast on võimalik välja lugeda väljakutsutava operatsiooni nimi.

Alates 6.18.0 X-tee versioonist kontrollib ja edastab turvaserver rakenduse poolt talle edastatud HTTP päringu päises olevat SOAPAction välja edasi teise osapoole turvaserverile. Varasemates versioonides eemaldati SOAPAction väli enne edastamist HTTP päisest. Seega nüüd on oluline antud väli korrektselt kirjeldada vastavalt standardile punkt 6.1.1 

Juhime tähelepanu, et SOAPAction välja väärtus on kas tühi või ümbritsetud jutumärkidega. Muul juhul tagastab turvaserver veateate The given SOAPAction ... does not match an operation ja Malformed SOAPAction header.
Kui üle X-tee päritava teenuse rakendus ei nõua SOAPAction välja, siis lihtsam lahendus on eemaldada enda päringut tegevas rakenduses üldse HTTP POST päringu päisest SOAPAction väli. Varuvariandina võib ka kaaluda turvaserveri uuendamiseelse seisu taastamist varukoopiast.

Kui puutute X-tee andmeteenuste kirjelduste juures kokku näiteks teenustega siilis rpc/encoded, siis on tegemist X-tee vanema versiooni andmeteenusega ja see kirjeldus tuleb versioon 6 jaoks ringi teha stiili document/literal wrapped.

Vaata rohkem aadressilt: https://www.ibm.com/developerworks/library/ws-whichwsdl/

3.7.6   service

WSDL kirjelduse <service> plokis defineeritakse andmeteenuse konkreetne URL.

<wsdl:service name="person_register">

  <wsdl:port binding="tns:person_registerSOAP" name="person_registerSOAP">

    <soap:address location="http://localhost:8080/person_register/services/person_registerSOAP"/>

  </wsdl:port>

</wsdl:service>

Viimati muudetud: teisipäev, 21. august 2018, 17.14