Suomi.fi-palveluväylä –
X-Road-tiedonsiirtoprotokolla

Print Friendly, PDF & Email
 

1 Johdanto

 1.1 X-Road-tiedonsiirtoprotokolla

Tässä dokumentissa kuvataan Suomi.fi-palveluväylän  X-Road-tiedonsiirtoprotokolla.

Palveluväylään liittyminen edellyttää, että liitettävä järjestelmä pystyy lähettämään ja vastaanottamaan SOAP-sanomia X-Roadin edellyttämässä muodossa. Käytännössä tämä tarkoittaa sitä, että SOAP-sanomien on sisällettävä tietyt X-Road-tiedonsiirtoprotokollan määrittelemät otsikkotiedot. Lisäksi kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan X-Road-protokollan määrittelemällä tavalla. X-Roadin versio 6 käyttää SOAP versiota 1.1. Protokollakuvaus löytyy kokonaisuudessaan täältä.

1.1 Käsitteet

Kansallinen palveluväylä (en = National Data Exchange Layer) on Suomessa käyttöönotettava Viron X-Road-ratkaisuun perustuva standardi tapa siirtää tietoa tietovarantojen ja niitä hyödyntävien tietojärjestelmien välillä.

Liityntäpalvelin (en = Security Server) on X-Road-ratkaisun keskeinen komponentti, jonka kautta tietolähteiden ja tietojärjestelmien liittäminen palveluväylään tapahtuu. Jokaisella palveluväylään liitetyllä järjestelmällä on oltava käytössään liityntäpalvelin, jonka kautta kaikki palveluväylään lähetettävät tai sieltä vastaanotettavat sanomat kulkevat. Liityntäpalvelin vastaa mm. palvelukutsujen välittämisestä järjestelmien välillä, palvelukutsujen varmennekättelystä, tietoliikenteen ja sanomien salauksesta, lokituksesta ja käyttöoikeuksien hallinnasta. Liityntäpalvelin voi olla organisaatiokohtainen tai monen organisaation kesken yhteinen.

Kaikki palveluväylän viestiliikenne on suoraan liityntäpalvelinten välistä, eivätkä palveluväylän kautta lähetetyt sanomat näin ollen kulje minkään yhden keskitetyn pisteen kautta. Myös lokitiedot ovat liityntäpalvelinkohtaisia, eikä niitä kerätä keskitetysti yhteen yksittäiseen paikkaan

SOAP (en = Simple Object Access Protocol) on XML-kieleen pohjautuva tietoliikenneprotokolla, jota X-Road-ratkaisun liityntäpalvelimen rajapintatoteutuksessa käytetään. SOAP toimii useiden eri protokollien yli, mutta X-Roadin tapauksessa sitä käytetään vain HTTP-protokollan yli.

X-Road on Virossa kehitetty ja käytössä oleva ohjelmisto, joka toimii osana Suomi-fi-palveluväylän teknistä ydintä.

2 HTTP-otsikkotiedot

X-Road edellyttää taulukossa 1 esitettyjen HTTP-otsikkotietojen käyttöä sen kautta lähetetyissä sanomissa. Liitteitä sisältävissä sanomissa Content-Type otsikkotiedon on oltava multipart/related, muutoin on käytetävä arvoa text/xml. SOAPAction-otsikkotieto kentän voi jättää tyhjäksi tai sen voi määritellä osoittamaan haluttuun URI-määritykseen.

HTTP-otsikkotieto
Arvo
Content-Type text/xml tai multipart/related
SOAPAction Validi URI tai tyhjä *)

Taulukko 1. HTTP-otsikkotiedot

*) Liityntäpalvelin säilyttää ja välittää SOAPAction -otsikkotietueen palvelulle X-Road versiosta 6.16.0 lähtien. Validi URI tarkoittaa, että URI on määritelty heittomerkkien sisään (liityntäpalvelin ohjelmisto tarkistaa tämän). Esimerkki oikein määritellystä SOAPAction -otsikkotiedosta:

SOAPAction: "http://x-road.eu/app#MyMessage"

Esimerkki oikein määritellystä tyhjästä arvosta SOAPAction-otsikkotiedossa:

SOAPAction: ""

3 Rajapintakuvaukset

X-Road edellyttää siihen liitettävien palveluiden kuvaamista WSDL-kielellä. Kysely- ja vastaussanomien rakenteen kuvaavat XML-skeemat voidaan joko sisällyttää suoraan WSDL-kuvaukseen tai vaihtoehtoisesti kuvata erillisissä tiedostoissa eli niin sanotuissa XML Schema Definition (XSD) tiedostoissa. Näihin XSD-tiedostoihin viitataan sitten WSDL-kuvauksessa import-määrityksen avulla.

Käytettäessä XSD-tiedostoja pitää huomioida, että xml:include ei toimi koska käyttäjällä ei ole pääsyä WSDL:n tarjoajan tietojärjestelmään. Sen sijaan xml:import toimii, mutta XSD-tiedosto pitää tarjota julkiseen internettiin ja absoluuttinen osoite pitää olla annettu importissa eikä vain relatiivista osoitetta.

Esimerkiksi tämä on oikea tapa:

<xsd:import namespace="xyz" schemaLocation="http://palvelu-x.yritys.com/model.xsd"/>

ja tämä on väärä tapa:

<xsd:import namespace="xyz" schemaLocation="model.xsd/>

Skeemoissa tulee käyttää nimiavaruuksia sekä yksiselitteisiä nimiä elementeille. On huomioitava, että WSDL-kuvauksessa käytetyt datatyypit täytyy löytyä nimiavaruuksien määrittämistä verkkosijainneista, muuten WSDL:n importtaus epäonnistuu liityntäpalvelimella. Erityisesti tämä on huomioitava siinä tapauksessa, että käytettävät nimiavaruudet eivät ole yleisesti julki-internetissä saatavilla olevia vaan ne on tehty esimerkiksi vain tiettyä suljettua tarkoitusta varten. Tällöin nimiavaruus pitää tarjota julkiseen internettiin jotta sen käyttö on mahdollista.

Skeemoissa on myös suositeltavaa käyttää elementFormDefault=”qualified” -määritystä (kts. lisätietoja), jonka mukaan kaikkien kyseiseen XML-skeemaan perustuvissa sanomissa käytettävien elementtien tulee täyttää skeemassa määritellyissä nimiavaruuksissa asetetut vaatimukset. Käytännössä sanomissa ei saa siis olla elementtejä, joita ei ole määritelty skeemassa tai skeeman käyttämissä nimiavaruuksissa. Tällä tavoin ehkäistään nimikonfliktien syntyminen sekä varmistetaan, että jokainen elementti on yksilöitävissä yksiselitteisesti.

WSDL-dokumentissa on käytettävä document/literal-sidontaa (binding style=”document”; use=”literal”). Palvelukutsujen sidontatyylin (binding style) on oltava document. Use-attribuutin arvon on puolestaan oltava literal. Esimerkki 1 ilman request/response-kääreitä, esimerkki 2 request/response-kääreitä käytettäessä.

Esimerkki WSDL-tiedosto, jossa esitellään getRandom-palvelu:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://test.x-road.fi/producer"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:id="http://x-road.eu/xsd/identifiers"
                  name="testService" targetNamespace="http://test.x-road.fi/producer">
    <wsdl:types>
        <xsd:schema elementFormDefault="qualified" targetNamespace="http://test.x-road.fi/producer">
            <!-- Import X-Road schema -->
            <xsd:import id="xrd" namespace="http://x-road.eu/xsd/xroad.xsd" schemaLocation="http://x-road.eu/xsd/xroad.xsd"/>
            <xsd:element name="getRandom" nillable="true">
                <xsd:complexType />
            </xsd:element>
            <xsd:element name="getRandomResponse">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="data" type="xsd:string">
                            <xsd:annotation>
                                <xsd:documentation>
                                    Service response
                                </xsd:documentation>
                            </xsd:annotation>
                        </xsd:element>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:schema>
    </wsdl:types>
    <wsdl:message name="requestheader">
        <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="issue" element="xrd:issue"/>
        <wsdl:part name="protocolVersion" element="xrd:protocolVersion" />
    </wsdl:message>
    <wsdl:message name="getRandom">
        <wsdl:part name="body" element="tns:getRandom"/>
    </wsdl:message>
    <wsdl:message name="getRandomResponse">
        <wsdl:part name="body" element="tns:getRandomResponse"/>
    </wsdl:message>
    <wsdl:portType name="testServicePortType">
        <wsdl:operation name="getRandom">
            <wsdl:input message="tns:getRandom"/>
            <wsdl:output message="tns:getRandomResponse"/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="testServiceBinding" type="tns:testServicePortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="getRandom">
            <soap:operation soapAction="" style="document" />
            <xrd:version>v1</xrd:version>
            <wsdl:input>
                <soap:body parts="body" use="literal"/>
                <soap:header message="tns:requestheader" part="client" use="literal"/>
                <soap:header message="tns:requestheader" part="service" use="literal"/>
                <soap:header message="tns:requestheader" part="userId" use="literal"/>
                <soap:header message="tns:requestheader" part="id" use="literal"/>
                <soap:header message="tns:requestheader" part="issue" use="literal"/>
                <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body parts="body" use="literal"/>
                <soap:header message="tns:requestheader" part="client" use="literal"/>
                <soap:header message="tns:requestheader" part="service" use="literal"/>
                <soap:header message="tns:requestheader" part="userId" use="literal"/>
                <soap:header message="tns:requestheader" part="id" use="literal"/>
                <soap:header message="tns:requestheader" part="issue" use="literal"/>
                <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="testService">
        <wsdl:port binding="tns:testServiceBinding" name="testServicePort">
            <soap:address location="http://example.com/Endpoint"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

WSDL:n alussa esitellään tarvittavat namespacet. HUOM! PITÄÄ käyttää absoluuttista osoitetta:

<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://test.x-road.fi/producer"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:id="http://x-road.eu/xsd/identifiers"
                  name="testService" targetNamespace="http://test.x-road.fi/producer">

Tarjottujen operaatioiden tietotyypit:

<wsdl:types>
    <xsd:schema elementFormDefault="qualified" targetNamespace="http://test.x-road.fi/producer">
        <!-- Import X-Road schema -->
        <xsd:import id="xrd" namespace="http://x-road.eu/xsd/xroad.xsd" schemaLocation="http://x-road.eu/xsd/xroad.xsd"/>
       <xsd:element name="getRandom" nillable="true">
       <xsd:complexType />
            </xsd:element>
            <xsd:element name="getRandomResponse">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="data" type="xsd:string">
                            <xsd:annotation>
                                <xsd:documentation>
                                    Service response
                                </xsd:documentation>
                            </xsd:annotation>
                        </xsd:element>
                    </xsd:sequence>
                </xsd:complexType>
        </xsd:element>
    </xsd:schema>
</wsdl:types>

X-Road -parametrit pyynnön otsikko-osaan:

<wsdl:message name="requestheader">
    <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="issue" element="xrd:issue"/>
    <wsdl:part name="protocolVersion" element="xrd:protocolVersion" />
</wsdl:message>

Tarjottavan palvelun sisältö. Rakenne pitää olla aina alla olevan mukainen:

<wsdl:message name="getRandom">
    <wsdl:part name="body" element="tns:getRandom"/>
</wsdl:message>
<wsdl:message name="getRandomResponse">
    <wsdl:part name="body" element="tns:getRandomResponse"/>
</wsdl:message>

Tarjottava operaatio:

<wsdl:portType name="testServicePortType">
    <wsdl:operation name="getRandom">
        <wsdl:input message="tns:getRandom"/>
        <wsdl:output message="tns:getRandomResponse"/>
    </wsdl:operation>
</wsdl:portType>

Tarjottavan operaation esittely. Input body sisältää itse kyselyn operaatiolle ja headerit ohjaavat kyselyn oikealle servicelle. Output bodyssä on operaation vastaus ja edelleen service, jolle kysely oli tullut.

<wsdl:binding name="testServiceBinding" type="tns:testServicePortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
    <wsdl:operation name="getRandom">
        <soap:operation soapAction="" style="document" />
        <xrd:version>v1</xrd:version>
        <wsdl:input>
            <soap:body parts="body" use="literal"/>
            <soap:header message="tns:requestheader" part="client" use="literal"/>
            <soap:header message="tns:requestheader" part="service" use="literal"/>
            <soap:header message="tns:requestheader" part="userId" use="literal"/>
            <soap:header message="tns:requestheader" part="id" use="literal"/>
            <soap:header message="tns:requestheader" part="issue" use="literal"/>
            <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
        </wsdl:input>
        <wsdl:output>
            <soap:body parts="body" use="literal"/>
            <soap:header message="tns:requestheader" part="client" use="literal"/>
            <soap:header message="tns:requestheader" part="service" use="literal"/>
            <soap:header message="tns:requestheader" part="userId" use="literal"/>
            <soap:header message="tns:requestheader" part="id" use="literal"/>
            <soap:header message="tns:requestheader" part="issue" use="literal"/>
            <soap:header message="tns:requestheader" part="protocolVersion" use="literal"/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

Koko servicen nimi, joka tarjoaa yllä mainitut operaatiot:

<wsdl:service name="testService">
    <wsdl:port binding="tns:testServiceBinding" name="testServicePort">
        <soap:address location="http://example.com/Endpoint"/>
    </wsdl:port>
</wsdl:service>

 

4 SOAP-otsikkotiedot

X-Roadin edellyttämät SOAP-otsikkotiedot on esitettu taulukossa 2.

Kenttä
Pakollinen
 Lisätietoja
service x  Kts. taulukko 3
client x  Kt.s taulukko 3
userId  Kutsun generoineen loppukäyttäjän käyttäjätunnus asiakasjärjestelmässä. Mikäli kutsu on asiakasjärjestelmän automaattisesti generoima, voidaan käyttää myös asiakasjärjestelmän nimeä. Huom! Henkilötunnusta ei tule lähettää tässä kentässä, koska kentän sisältö tallentuu salaamattomana liityntäpalvelimen sanomalokiin.
id x  Kutsu- ja vastaussanoman yksilöivä uniikki tunniste. Tunnisteen generointi on kutsun lähettäjän vastuulla.
issue  Kentässä voidaan välittää muuta kutsuun liittyvää vapaamuotoista tietoa.
requestHash Vain SOAP response -sanomissa. Tuottajan (producer) liityntäpalvelin lisää.
requestHash@algorithmId Vain SOAP response -sanomissa. Tuottajan (producer) liityntäpalvelin lisää.
protocolVersion x Sanomassa käytettävä X-Road-tiedonsiirtoprotokollan versionumero. X-Road versiossa >= 6.4 tiedonsiirtoprotokollan versionumero on 4.0.

Taulukko 2. SOAP-otsikkotiedot

Vastaussanoman on sisällettävä täsmälleen samat otsikkotiedot kuin kyselysanomassakin on.

Palvelun hyödyntäjän (consumer) ilmaisemiseen käytetään client-elementtiä ja tuottajan (producer) ilmaisemiseen service-elementtiä. Molemmat elementit koostuvat useista alielementteistä, joiden sisällöistä hyödyntäjän ja tuottajan yksilöivät tunnisteet muodostuvat. Organisaatiokohtaiset tunnisteet muodostuvat kolmesta (sdsbInstance, memberClass, memberCode), järjestelmäkohtaiset neljästä (xRoadInstance, memberClass, memberCode, subsystemCode) ja palvelukohtaiset kuudesta  (xRoadInstance, memberClass, memberCode, subsystemCode, getRandom, serviceVersion) erillisestä osasta. Alla olevan esimerkkisanoman tapauksessa hyödyntäjän tunniste on ”FI.GOV.12345-6.ConsumerService” ja tuottajan tunniste ”FI.GOV.65432-1.DemoService.getRandom.v1”.

Otsikkotiedot versiossa 6:
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
  <soapenv:Header> 
    <xrd:client id:objectType="SUBSYSTEM">
      <id:xRoadInstance>FI</id:xRoadInstance>
      <id:memberClass>GOV</id:memberClass>
      <id:memberCode>12345-6</id:memberCode>
      <id:subsystemCode>ConsumerService</id:subsystemCode>
    </xrd:client>
    <xrd:service id:objectType="SERVICE">
      <id:xRoadInstance>FI</id:xRoadInstance>
      <id:memberClass>GOV</id:memberClass>
      <id:memberCode>65432-1</id:memberCode>
      <id:subsystemCode>DemoService</id:subsystemCode>
      <id:serviceCode>getRandom</id:serviceCode>
      <id:serviceVersion>v1</id:serviceVersion>
    </xrd:service>
    <xrd:userId>mvirtanen</xrd:userId>
    <xrd:id>1234567890</xrd:id>      
    <xrd:protocolVersion>4.0</xrd:protocolVersion>
  </soapenv:Header>
  <soapenv:Body>
    .
    .
    .
  </soapenv:Body>
</soapenv:Envelope>

Taulukossa 3 on esitetty lyhyet kuvaukset client- ja service-elementtien alielementtien sisällöistä.

 

 Elementti
Kuvaus
 xRoadInstance  X-Road-instanssin yksilöivä tunnus. Tunnus koostuu ISO-standardin mukaisesta maakoodista sekä teknisen ympäristön (kehitysympäristö, testiympäristö, tuotantoympäristö) yksilöivästä liitteestä.
 memberClass Organisaation tyypin ilmaiseva yksittäisen instanssin sisällä uniikki tunnus.  Esim. valtionhallinnon organisaatio (GOV), kunta (MUN), yksityinen yritys (COM), säätiö (ORG) jne.
 memberCode Yksittäisen organisaation yksilöivä tunnus, jonka on oltava uniikki vähintään valitun organisaatiotyypin sisällä. Y-tunnus.
 subsystemCode Palveluväylään liitettävän yksittäisen tietojärjestelmen tai loogisen palvelu-/järjestelmäkokonaisuuden tunnus.
 serviceCode Palveluväylään julkaistun yksittäisen SOAP-palvelun nimi/tunnus.
 serviceVersion SOAP-palvelun versio. Esim. v1, v2 jne.

Taulukko 3. Client- ja service-elementit

Lisätietoja X-Roadin käyttämistä tunnisteista löytyy täältä.

5 SOAP Body

Palveluväylään liitettävän tietojärjestelmän käyttämät kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan X-Road-protokollan määrittelemällä tavalla. X-Roadin versiossa 5 oli pakollista ympäröidä kysely- ja vastaussanoma request/response XML-elementtiin eli request/response-kääreisiin, mutta X-Roadin versiossa 6 request/response-kääreiden käyttö ei ole enää pakollista.

Palveluväylään liittyvät organisaatiot saavat itse päättää request/response-kääreiden käytöstä omien palveluidensa palveluväyläliitosten toteutuksissa. Kääreiden käyttö on kuitenkin oltava yhdenmukaista yksittäisen palvelun kohdalla eli kääreitä tulee käyttää sekä kysely- että vastaussanomissa tai ei kummassakaan.

5.1 Kyselysanoma

X-Roadin kautta lähettävien kyselysanomien (request) on oltava alla esitettyä muotoa, kun request/response-kääreitä ei käytetä (katso esimerkki):

<SOAP-ENV:Envelope  xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:service xmlns:m="URI">
        Request content
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>

Request/response-kääreitä käytettäessä kyselysanoman pitää puolestaan olla alla nähtävän vastaussanoman mukainen (katso esimerkki):

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:service xmlns:m="URI">
      <m:request>
        Request content
      </m:request>
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>
Kyselysanoman hyötykuorma
Kyselysanoman hyötykuorman sisältävä XML-elementti on nimettävä palvelun mukaan.

Kyselysanoman hyötykuorma (payload) tulee sijoittaa SOAP-sanoman Body-osaan. Hyötykuorman sisältävä XML-elementti on nimettävä palvelun mukaan. Palvelun nimi on määritelty SOAP-sanoman otsikkotiedoissa service-elementin alla sijaitsevassa serviceCode-elementissä. Alla olevassa esimerkissä helloService-palvelun kutsu ilman request-käärettä, josta on selkeyden vuoksi jätetty kaikki ylimääräiset elementit pois (katso esimerkki). Request-käärettä käytettäessä kyselysanoma näyttää puolestaan tältä.

<SOAP-ENV:Envelope> 
  <soapenv:Header> 
    <sdsb:service id:objectType="SERVICE">
      <id:serviceCode>helloService</id:serviceCode>
    </sdsb:service>     
  </soapenv:Header>
  <soapenv:Body>
    <m:helloService xmlns:m="URI">
        Request content
    </m:helloService>
  </soapenv:Body>
</soapenv:Envelope>

5.2 Vastaussanoma

X-Roadin kautta lähetettävien vastaussanomien on aina sisällettävä samat otsikkotiedot kuin kyselysanomassakin on.

X-Roadin kautta lähetettävien vastaussanomien (response) on oltava alla esitettyä muotoa, kun request/response-kääreitä ei käytetä (katso esimerkki).

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:serviceResponse xmlns:m="URI">
        Response content
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>
Request/response-kääreitä käytettäessä vastaussanoman pitää puolestaan olla alla nähtävän vastaussanoman mukainen (katso esimerkki).
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
  <soapenv:Header> 
    Header content    
  </soapenv:Header>
  <soapenv:Body>
    <m:serviceResponse xmlns:m="URI">
      <m:request>
        Request content
      </m:request>
      <m:response>
        Response content
      </m:response>
    </m:service>
  </soapenv:Body>
</soapenv:Envelope>

Vastaussanoman hyötykuorma

Vastaussanoman hyötykuorman sisältävä XML-elementti on nimettävä siten, että elementin nimi muodustuupalvelun nimestä ja nimen perään lisättävästä ”Response”-liitteestä.

Vastaussanoman hyötykuorma (payload) tulee sijoittaa SOAP-sanoman Body-osaan. Hyötykuorman sisältävä XML-elementti on nimettävä siten, että elementin nimi muodustuu palvelun nimestä ja nimen perään lisättävästä ”Response”-liitteestä. Palvelun nimi on määritelty SOAP-sanoman otsikkotiedoissa service-elementin alla sijaitsevassa serviceCode-elementissä. Alla olevassa esimerkissä helloService-palvelun palauttama vastaussanoma, josta on selkeyden vuoksi jätetty kaikki ylimääräiset elementit pois (katso esimerkki ilman request/response-kääreitä ja esimerkki request/response-kääreiden kanssa).

Esimerkki ilman request/response-kääreitä:

<SOAP-ENV:Envelope>
  <soapenv:Header> 
    <sdsb:service id:objectType="SERVICE">
      <id:serviceCode>helloService</id:serviceCode>
    </sdsb:service>     
  </soapenv:Header>
  <soapenv:Body>
    <m:helloServiceResponse xmlns:m="URI">
        Response content
    </m:helloServiceResponse>
  </soapenv:Body>
</soapenv:Envelope>

Esimerkki request/response-kääreitä käytettäessä:

<SOAP-ENV:Envelope>
  <soapenv:Header> 
    <sdsb:service id:objectType="SERVICE">
      <id:serviceCode>helloService</id:serviceCode>
    </sdsb:service>     
  </soapenv:Header>
  <soapenv:Body>
    <m:helloServiceResponse xmlns:m="URI">
      <m:request>
        Request content
      </m:request>
      <m:response>
        Response content
      </m:response>
    </m:helloServiceResponse>
  </soapenv:Body>
</soapenv:Envelope>

5.3 Virhesanomat

X-Road mahdollistaa kahden tyyppisten virhesanomien palauttamisen: standard SOAP error ja non-technical SOAP error.

Standard SOAP error

SOAP-otsikkotietojen sisällyttäminen Standard SOAP error -virhesanomaan ei ole pakollista, mutta kuitenkin suositeltavaa. Virhekoodeissa (fault code) tulee käyttää SOAP-määritysten mukaisia virhekoodeja (kts. alla). SOAP-virhekoodien tarkemmat määritykset löytyvät täältä.

  • VersionMismatch
    • SOAP viestissä on käytetty virheellistä nimiavaruutta ja tästä syystä SOAP käsittelijä generoi virhekoodin versioiden yhteensopimattomuudesta. Nimiavaruuden pitää olla määritetty kuten täällä: http://schemas.xmlsoap.org/soap/envelope/
  • MustUnderstand
    • SOAP otsikkoelementin lapsielementti sisälsi ’MustUnderstand’ -attribuutin arvolla ’TRUE’ tai ’1’ mutta viestin vastaanottajan SOAP käsittelijä ei pystynyt tunnistamaan elementtiä tai ei pystynyt käsittelemään sitä.
  • Client
    • Client-virhekoodilla viitataan kutsusanoman virheelliseen sisältöön eli asiakaspään muodostama kutsusanoma on virheellinen.
  • Server
    • Server-virhekoodilla viitataan palvelun puolella tapahtuneisiin muihin kuin kutsusanoman sisällön aiheuttamiin virhetilanteisiin. Tarkoittaa siis sitä, että palvelun puolella tapahtui virhe kutsun käsittelyssä.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        Header content
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>fault code</faultcode>
            <faultstring>fault string</faultstring>
            <faultactor>fault actor</faultactor>
            <detail>fault details</detail>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Non-technical  SOAP error

Non-technical SOAP error -virhesanoma on sovelluskohtainen virhesanoma, jonka tulisi sisältää sovelluskohtaisen virhekoodiin (fault code) ja virhekuvauksen (fault string). SOAP-otsikkotiedot tulee sisällyttää sanomaan.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        Header content
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <m:serviceResponse xmlns:m="URI">
            <faultCode>fault code</faultCode>
            <faultString>fault string</faultString>
        </m:serviceResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Non-technical SOAP error –virhesanomassa voidaan käyttää request/response-kääreitä tavallisen vastaussanoman tapaan. Jos kääreet ovat käytössä kysely- ja vastaussanomissa, niin tulisi niitä käyttää myös Non-technical SOAP error –virhesanomassa.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        Header content
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <m:serviceResponse xmlns:m="URI">
            <m:request>
                Request content
            </m:request>
            <m:response>
                <faultCode>fault code</faultCode>
                <faultString>fault string</faultString>
            </m:response>
        </m:serviceResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

5.4 Esimerkkipalvelu

Esimerkki ilman request/response-kääreitä:

Esimerkkinä toimikoon yksinkertainen helloService-palvelu, jolle annetaan kyselysanoman parametrinä käyttäjän nimi ja palautetaan vastaussanomassa kyseiselle käyttäjälle osoitettu tervehdys.

Esimerkki request/response-kääreiden kanssa:

Esimerkkinä toimikoon yksinkertainen helloService-palvelu, jolle annetaan kyselysanoman parametrinä käyttäjän nimi ja palautetaan vastaussanomassa kyseiselle käyttäjälle osoitettu tervehdys.


 Dokumentin tiedot

Versionro Mitä tehty Pvm/henkilö
 1.1 Dokumentti luotu 10.04.15/PK
 1.2 Sisältöä lisätty  02.08.15 / PK
 1.3 Muokattu julkaistavaksi  07.10.15 / PK, NP
 1.4 Luvut 3 ja 5 päivitetty. Esimerkkejä lisätty WSDL-kuvauksista ja SOAP-viesteistä.  07.07.16 / HH
 1.5 Lukua 3 tarkennettu: WSDL-kuvausta ja nimiavaruuksia koskevaa tietoa päivitetty.  10.05.17 / HH
 1.6 Luvun 1.1 linkki protokollakuvaukseen päivitetty osoittamaan virallisen X-Road repositorion dokumenttiin.  23.11.17 / HH
 1.7 Korjattu WSDL-esimerkin nimiavaruus oikeaksi:

<id:version>v1</id:version> => <xrd:version>v1</xrd:version>

Päivitetty lukua ’2 HTTP-otsikkotiedot’ niin, että SOAPAction -otsikkotietoa voi käyttää URI:n määritykseen.

 8.12.17 / HH

Yksilöintitunnus: JTO101