Palveluväylässä käytetyt tunnisteet

Tässä artikkelissa kuvataan Suomi.fi-palveluväylässä käytetyt tunnisteet.

X-Roadin versiossa 6 jokaiselle Palveluväylään liittyneelle organisaatiolle sekä sen Palveluväylään liittämälle alijärjestelmälle ja palvelulle annetaan globaalisti uniikki tunniste. Tunnisteen tarkoituksena on tukea X-Roadin federaatio-ominaisuutta, joka mahdollistaa useiden eri X-Road-instanssien liittämisen toisiinsa.

X-Roadin sisäinen viestinvälitys ja käyttöoikeuksien hallinta perustuvat organisaatioiden, alijärjestelmien ja palveluiden uniikkeihin tunnisteisiin sekä yksittäisen X-Road-instanssin että monesta eri instanssista muodostuvan kokonaisuuden sisällä.

Tunnisteiden rakenne

Organisaatiokohtaiset tunnisteet muodostuvat kolmesta, alijärjestelmäkohtaiset neljästä ja palvelukohtaiset kuudesta erillisestä osasta. Tunnisteet ovat hierarkkisia. Alijärjestelmien tunnisteet sisältävät aina ne omistavan organisaation tunnisteen. Palveluiden tunnisteet sisältävät vastaavasti aina sekä alijärjestelmän että organisaation tunnisteet.

Organisaatioiden tunnisteet (member)

X-Roadin versiossa 6 Palveluväylään liittyneiden organisaatioiden tunnisteet rakentuvat kolmesta osasta seuraavasti:

Organisaatio: [X-Road instance]/[member class]/[member code]

• X-Road instance = X-Road-instanssin yksilöivä tunnus. Tunnuksen tulee koostua ISO-standardin mukaisesta maakoodista ja Palveluväylän teknisen ympäristön yksilöivästä liitteestä (FI-DEV, FI-TEST, FI). Palveluväyläoperaattori asettaa ympäristön tunnuksen keskuspalvelimen asennuksen yhteydessä.
• Member class = organisaation tyypin ilmaiseva uniikki tunnus yksittäisen instanssin sisällä. Palveluväylän testi-, tuotanto- ja kehitysympäristöissä organisaatiot luokitellaan seuraavalla tavalla:

GOV: valtionhallinnon laitokset
COM: kaupalliset toimijat
MUN: kunnat
EDU: opetus- ja koulutussektori
ORG: voittoa tavoittelemattomat organisaatiot, esimerkiksi yhdistykset ja säätiöt (vain testi- ja tuotantoympäristössä)
PRI: yksityishenkilöt (vain kehitysympäristössä)

• Member code = yksittäisen organisaation yksilöivä tunnus, jonka on oltava uniikki vähintään valitun organisaatiotyypin sisällä. Selvyyden vuoksi on kuitenkin parempi, että käytettävät tunnukset ovat uniikkeja koko instanssin tasolla. Organisaation yksilöivänä tunnuksena käytetään Y-tunnusta.

Member code -tarkennuksia

Organisaatiot voivat liittyä kaikkiin Palveluväylän ympäristöihin. Organisaatioiden kohdalla Y-tunnus kirjataan Member codeksi ilman FI-etuliitettä eli muodossa 0920632-0. Jos liittyvällä organisaatiolla ei ole Y-tunnusta, Palveluväylän ylläpito antaa organisaatiolle Member codena käytettävän tunnisteen.

Yksityishenkilöt voivat liittyä vain Palveluväylän kehitysympäristöön. Kun haluat liittyä kehitysympäristöön yksityishenkilönä, ota ensin yhteyttä Palveluväylän tukeen palveluvayla@palveluvayla.fi. Palvelun ylläpitäjät antavat sinulle kehitysympäristöön tarvittavat liittymistiedot (member name ja member code). Yksityishenkilöiden kohdalla käytetään Member codena Y-tunnuksen sijaan juoksevaa numerointia 0000001-0, 0000002-0 jne.

Emme suosittele käyttämään omaa nimeä esimerkiksi liityntäpalvelimen tai alijärjestelmien nimissä. Käytä mieluummin keksittyä nimeä ja keskustele nimeämisestä Palveluväylän tuen kanssa.

Esimerkiksi alla oleva tunniste yksilöi FI-DEV-instanssiin eli kehitysympäristöön kuuluvan yksityisen yrityksen, jonka Y-tunnus on 12345:

Organisaatio: FI-DEV/COM/12345

Alijärjestelmien tunnisteet (subsystem)

Palveluväylän kautta tietoja hyödyntävällä alijärjestelmällä (consumer) tulee aina olla subsystem-tason tunniste.

Alijärjestelmällä tarkoitetaan organisaation X-Roadiin liittämää yksittäistä tietojärjestelmää tai loogista palvelu-/järjestelmäkokonaisuutta. Alijärjestelmän tunniste koostuu sen omistavan organisaation tunnisteesta (subsystem owner) ja alijärjestelmän yksilöivästä tunnuksesta organisaation tasolla (subsystem code).

Alijärjestelmille annettavat tunnukset (subsystem code) ovat organisaatioiden itsensä päätettävissä. Suosituksena on kuitenkin käyttää CamelCase-tyyppistä nimeämiskäytäntöä alijärjestelmien nimissä. Käytännössä tämä tarkoittaa useista eri sanoista muodostuvien alijärjestelmien nimien kirjoittamista siten, että sanat on kirjoitettu yhteen isoin alkukirjaimin (esim. TestSystem).

Alijärjestelmä: [subsystem owner]/[subsystem code]

Esimerkiksi alla oleva tunniste yksilöi HighSecurity-nimisen alijärjestelmän, joka kuuluu edellisessä esimerkissä esitetylle organisaatiolle FI-DEV/COM/12345.

Alijärjestelmä: FI-DEV/COM/12345/HighSecurity

Palveluiden tunnisteet (service)

Palveluväylän kautta tietoja tarjoavalla palvelulla (provider) tulee aina olla alijärjestelmän sisältävä service-tason tunniste.

Palvelulla tarkoitetaan alijärjestelmän kautta Palveluväylään julkaistua yksittäistä SOAP-palvelua. Palvelun tunniste koostuu sen julkaisseen alijärjestelmän tunnisteesta, palvelun yksilöivästä tunnuksesta ja palvelun versionumerosta.

Versionumeroa käytetään erottamaan palvelun eri versiot toisistaan. Sen käyttö on pakollista. Palvelun tunnuksen on oltava uniikki sen julkaisseen alijärjestelmän tasolla. Julkaisija voi itse päättää palvelun tunnuksen ja määritellä sen liitettyjen palveluiden rajapintakuvaukset sisältävissä WSDL-kuvauksissa. Versionumero muodostuu v-kirjaimesta ja versionumeron ilmaisevasta kokonaisluvusta.

Palvelu: [service provider]/[service code]/[version]

Esimerkiksi alla oleva tunniste yksilöi getSecureData-palvelun version v1, joka kuuluu edellisessä esimerkissä esitetylle alijärjestelmälle FI-DEV/COM/12345/HighSecurity.

Palvelu: FI-DEV/COM/12345/HighSecurity/getSecureData/v1

Tunnisteiden käyttö

Kaikki Palveluväylään liitettävät tietoa tarjoavat palvelut (provider) ja tietoa hyödyntävät järjestelmät (consumer) tulee liittää Palveluväylään alijärjestelmien kautta. Vaikka palvelujen liittäminen suoraan organisaatioiden alle tai palvelujen kutsuminen organisaationa on teknisesti mahdollista, alijärjestelmien käyttäminen mahdollistaa käyttöoikeuksien hienojakoisemman määrittelyn. Lisäksi alijärjestelmiä käyttämällä varmistetaan mahdollisimman yhtenäinen rakenne Palveluväylään liitettyjen järjestelmien ja palveluiden tunnisteissa.

Palveluväylän kautta tietoja käyttävällä järjestelmällä tulee aina olla subsystem-tason tunniste ja tietoja tarjoavalla palvelulla alijärjestelmän sisältävä service-tason tunniste. Liityntäpalvelimen omistajaksi merkitylle organisaatiolle sen sijaan riittää member-tason tunniste, mikäli organisaatio ei tarjoa tietoja Palveluväylään eikä käytä siellä olevia tietoja. Palveluväylään liittymisen yhteydessä kaikki organisaatiot saavat ensin member-tason tunnisteen, minkä jälkeen uusien alijärjestelmien ja palveluiden lisääminen sekä niiden edellyttämien tunnisteiden luominen on mahdollista.

Tunnisteiden käyttämisestä on kerrottu tarkemmin sivulla X-Road-tiedonsiirtoprotokolla.