Siirry suoraan sisältöön.
Suomi.fi-palveluväylä

Metapalvelut

Tässä artikkelissa kerrotaan liityntäpalvelimen tarjoamista metapalveluista. Niiden avulla on mahdollista saada tietoja Suomi.fi-palveluväylään liittyneistä organisaatioista ja niiden tarjoamista palveluista.

Metapalveluiden tarkoituksena on parantaa Palveluväylään liitettyjen palveluiden löydettävyyttä ja helpottaa niiden käyttöönottoa. Metapalveluiden kautta on mahdollista saada seuraavat tiedot:

  • listClients: listaus Palveluväylään liitetyistä organisaatioista (member) ja organisaatioiden alijärjestelmistä (subsystem)
  • listCentralServices: listaus keskuspalvelimen liityntäpalvelimen tarjoamista keskuspalveluista (central services)
  • listMethods: listaus tietyn organisaation tarjoamista palveluista
  • allowedMethods: listaus sellaisista tietyn organisaation tarjoamista palveluista, joihin kyselyn lähettäjällä on käyttöoikeus
  • getWsdl: palveluiden WSDL-rajapintakuvaukset.

Tutustu tarkemmin metapalveluiden protokollakuvaukseen (englanniksi).Avautuu uuteen ikkunaan.

Palveluväylään liittyneet organisaatiot ja niiden alijärjestelmät – listClients

listClients-metapalvelu palauttaa listauksen Palveluväylään liitetyistä organisaatioista (member) ja organisaatioiden alijärjestelmistä (subsystem).

Metapalvelun kutsuminen tapahtuu tekemällä HTTP GET -pyyntö liityntäpalvelimelle:

[GET] https://{SECURITYSERVER}/listClients

Liityntäpalvelin palauttaa vastauksena kaikkien Palveluväylään liitettyjen organisaatioiden ja alijärjestelmien tiedot sisältävän XML-sanoman:

Liityntäpalvelin palauttaa vastauksena kaikkien Palveluväylään liitettyjen organisaatioiden ja alijärjestelmien tiedot sisältävän XML-sanoman:

<ns2:clientList xmlns:ns1="http://x-road.eu/xsd/identifiers"xmlns:ns2="http://x-
road.eu/xsd/xroad.xsd">
    <ns2:member>
        <ns2:id ns1:objectType="MEMBER">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0920632-0</ns1:memberCode>
        </ns2:id>
        <ns2:name>CSC</ns2:name>
    </ns2:member>
    <ns2:member>
        <ns2:id ns1:objectType="MEMBER">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0245437-2</ns1:memberCode>
        </ns2:id>
        <ns2:name>VRK</ns2:name>
    </ns2:member>
    <ns2:member>
        <ns2:id ns1:objectType="SUBSYSTEM">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0245437-2</ns1:memberCode>
            <ns1:subsystemCode>TestClient</ns1:subsystemCode>
        </ns2:id>
        <ns2:name>VRK</ns2:name>
    </ns2:member>
    <ns2:member>
        <ns2:id ns1:objectType="SUBSYSTEM">
            <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
            <ns1:memberClass>GOV</ns1:memberClass>
            <ns1:memberCode>0245437-2</ns1:memberCode>
            <ns1:subsystemCode>TestService</ns1:subsystemCode>
        </ns2:id>
        <ns2:name>VRK</ns2:name>
    </ns2:member>
</ns2:clientList>

Keskuspalvelimen tarjoamat palvelut – listCentralServices

listCentralServices-metapalvelu palauttaa listauksen keskuspalvelimen liityntäpalvelimen tarjoamista keskuspalveluista (central services).

Metapalvelun kutsuminen tapahtuu tekemällä HTTP GET -pyyntö liityntäpalvelimelle:

[GET] https://{SECURITYSERVER}/listCentralServices

Liityntäpalvelin palauttaa vastauksena keskuspalveluiden tiedot sisältävän XML-sanoman:

<ns2:centralServiceList
        xmlns:ns1="http://x-road.eu/xsd/identifiers"
        xmlns:ns2="http://x-road.eu/xsd/xroad.xsd">
    <ns2:centralService ns1:objectType="CENTRALSERVICE">
        <ns1:xRoadInstance>FI-DEV</ns1:xRoadInstance>
        <ns1:serviceCode>random</ns1:serviceCode>
    </ns2:centralService>
</ns2:centralServiceList>

Organisaation tarjoamat palvelut – listMethods

listMethods-metapalvelu palauttaa listauksen tietyn organisaation tarjoamista palveluista.

Metapalvelun kutsuminen tapahtuu tekemällä Palveluväylän tiedonsiirtoprotokollan mukainen SOAP-kutsu liityntäpalvelimelle. Service-elementissä on yksilöitävä alijärjestelmä (subsystem), jolle kutsu kohdistetaan.

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>listMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:listMethods/>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Liityntäpalvelin palauttaa vastauksena listauksen kutsussa yksilöidyn alijärjestelmän (subsystem) alle liitetyistä palveluista:

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>listMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
        <xrd:requestHash
algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">kXIWpudDipT1nlID9CvINYGJZwIxcZ0dn4LkWO9Y141M+1nJ5pDzmtR5ul+PxJnR2xDdOQBEXBgEMrodomEwfQ==
</xrd:requestHash>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:listMethodsResponse>
            <xrd:service id:objectType="SERVICE">
                <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                <id:memberClass>GOV</id:memberClass>
                <id:memberCode>0245437-2</id:memberCode>
                <id:subsystemCode>TestService</id:subsystemCode>
                <id:serviceCode>helloService</id:serviceCode>
                <id:serviceVersion>v1</id:serviceVersion>
            </xrd:service>
            <xrd:service id:objectType="SERVICE">
                <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                <id:memberClass>GOV</id:memberClass>
                <id:memberCode>0245437-2</id:memberCode>
                <id:subsystemCode>TestService</id:subsystemCode>
                <id:serviceCode>getRandom</id:serviceCode>
                <id:serviceVersion>v1</id:serviceVersion>
            </xrd:service>
        </xrd:listMethodsResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Organisaation tarjoamat palvelut, joihin kysyjällä on käyttöoikeus – allowedMethods

allowedMethods-metapalvelu palauttaa listauksen sellaisista tietyn organisaation tarjoamista palveluista, joihin kyselyn lähettäjällä on käyttöoikeus.

Metapalvelun kutsuminen tapahtuu tekemällä Palveluväylän tiedonsiirtoprotokollan mukainen SOAP-kutsu liityntäpalvelimelle. Service-elementissä on yksilöitävä alijärjestelmä (subsystem), jolle kutsu kohdistetaan.

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>allowedMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:allowedMethods/>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Liityntäpalvelin palauttaa vastauksena listauksen kutsussa yksilöidyn alijärjestelmän (subsystem) alle liitetyistä palveluista, joihin kyselyn lähettäjällä on käyttöoikeus:

<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:id="http://x-
road.eu/xsd/identifiers"xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
    <SOAP-ENV:Header>
        <xrd:client id:objectType="SUBSYSTEM">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestClient</id:subsystemCode>
        </xrd:client>
        <xrd:service id:objectType="SERVICE">
            <id:xRoadInstance>FI-DEV</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>0245437-2</id:memberCode>
            <id:subsystemCode>TestService</id:subsystemCode>
            <id:serviceCode>allowedMethods</id:serviceCode>
        </xrd:service>
        <xrd:userId>tuser</xrd:userId>
        <xrd:id>ID11234</xrd:id>
        <xrd:protocolVersion>4.0</xrd:protocolVersion>
        <xrd:requestHash
algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">DBtjBqBKhtoOLWzw7KeaySlNtxZ3eI9x5LR7c9974+CYdVGkPj5nqLWkcLOlwHZPlguJUeMB2sLg0URxvgaIpw==
</xrd:requestHash>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <xrd:allowedMethodsResponse>
            <xrd:service id:objectType="SERVICE">
                <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                <id:memberClass>GOV</id:memberClass>
                <id:memberCode>0245437-2</id:memberCode>
                <id:subsystemCode>TestService</id:subsystemCode>
                <id:serviceCode>getRandom</id:serviceCode>
                <id:serviceVersion>v1</id:serviceVersion>
            </xrd:service>
        </xrd:allowedMethodsResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Palveluiden rajapintakuvaukset – getWsdl

getWsdl-metapalvelu palauttaa kutsussa yksilöidyn palvelun WSDL-kuvauksen. Tutustu tarkemmin X-Roadissa käytettävään WSDL-kuvaukseen artikkelin X-Road-tiedonsiirtoprotokolla kohdassa Rajapintakuvaukset.

HTTP POST -metodia käytettäessä metapalvelun kutsuissa käytetään samoja yhteysasetuksia kuin palveluja kutsuvalle alijärjestelmälle on määritetty. HTTP POST -metodia käyttämällä SOAP-sanomat lähetetään siis liityntäpalvelimen välityksellä Palveluväylään käytännössä aivan samalla tavalla kuin muutenkin.

Seuraavassa on esitetty getWsdl-metapalvelun kutsu.

HTTP POST

<soapenv:Envelope 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xro="http://x-road.eu/xsd/xroad.xsd"
xmlns:iden="http://x-road.eu/xsd/identifiers">
    <soapenv:Header>
        <xro:protocolVersion>4.x</xro:protocolVersion>
        <xro:issue>123</xro:issue>
        <xro:id>123</xro:id>
        <xro:userId>123</xro:userId>
        <xro:service iden:objectType="SERVICE">
            <iden:xRoadInstance>FI</iden:xRoadInstance>
            <iden:memberClass>COM</iden:memberClass>
            <iden:memberCode>111</iden:memberCode>
            <iden:subsystemCode>SUB</iden:subsystemCode>
            <iden:serviceCode>getWsdl</iden:serviceCode>
            <iden:serviceVersion>v1</iden:serviceVersion>
        </xro:service>
        <xro:client iden:objectType="SUBSYSTEM">
            <iden:xRoadInstance>FI</iden:xRoadInstance>
            <iden:memberClass>COM</iden:memberClass>
            <iden:memberCode>111</iden:memberCode>
            <iden:subsystemCode>SUB</iden:subsystemCode>
        </xro:client>
    </soapenv:Header>
    <soapenv:Body>
        <xro:getWsdl>
            <xro:serviceCode>getRandom</xro:serviceCode>
            <xro:serviceVersion>v1</xro:serviceVersion>
        </xro:getWsdl>
    </soapenv:Body>
</soapenv:Envelope>

getWsdl-metapalvelun vastaus

Liityntäpalvelin palauttaa vastauksena kutsussa yksilöidyn palvelun WSDL-kuvauksen, joka sisältää myös kaikkien muiden samassa WSDL:ssä kuvattujen palveluiden kuvaukset. Yllä olevassa esimerkkikyselyssä on yksilöity getRandom-palvelu. Samassa WSDL-kuvauksessa on kuvattu myös helloService-palvelu. Siksi myös helloService-palvelun kuvaus sisältyy vastaukseen. HTTP POST -metodia käytettäessä vastaus eli halutun palvelun WSDL-kuvaus palautuu SOAP-vastaussanoman liitteenä.

Tutustu tarkemmin vastaussanomiin ja esimerkkivastauksiin (englanniksi)Avautuu uuteen ikkunaan..

Päivitetty: 25.10.2024

Oletko tyytyväinen tämän sivun sisältöön?