4.1 X-tee nimeruum

Alljärgnevas peatükis on lühidalt kirjeldatud XML nimeruumi ja XML-skeemi ülevaade. Sellele järgnevad X-tee enda nimeruumide ja X-tee versiooni 6 päiseväljade kirjeldused. Kõige lõpus on toodud ka nimekiri päiseväljadest, mis kehtisid varasemates versioonides, kuna paljud teenused on siiski veel varasema versiooni järgi kirjeldatud.


4.1.1  XML nimeruumi mõiste

Nimeruum (namespace) on elementide komplekt või rühm, mis on defineeritud mingi kindla nimetamiskokkuleppe alusel.

XML nimeruum on kogum XML elementide tüüpe ja atribuutide nimesid, nimeruumil on unikaalne nimi, mis on URI viide. Nõnda on iga elemendi tüüp ja atribuudi nimi XML nimeruumis unikaalselt määratletud kahe  komponendiga: XML nimeruumi nimega ja oma kohaliku nimega.

XML nimeruum pakub elementide tüüpide ja atribuutide nimetamiseks kaheosalist süsteemi. Esimene osa on URI viide, mis identifitseerib nimeruumi ehk nimeruumi nimetuse (namespace name), teine osa on elemendi või atribuudi nimi (local name).

Nimeruumi võib deklareerida XML sees kahel viisil:

Nimeruumi aliase defineerimisel tuleks alati eelistada üldkasutatavaid lühendeid. Näiteks:


4.1.2  XML-skeem (Schema)

XML nimeruumi (URI) ja selles sisalduvate elementide ja atribuutide defineerimiseks kasutatakse enamasti XSD Schema standardit. Nimeruumi XSD definitsioon on metaandmete kollektsioon, milles kirjeldatakse elementide tüübid (string, dateTime), struktuur ja järgnevus (kas element asub teise elemendi sees või järel) ning reeglid (kas element on kohustuslik). Aga samuti elemendi sisulist olemust kirjeldavad kommentaarid (annotation, documentation).

XSD Näide (http://x-road.eu/xsd/identifiers):

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema elementFormDefault="qualified"

        targetNamespace="http://x-road.eu/xsd/identifiers"

        xmlns="http://x-road.eu/xsd/identifiers"

        xmlns:xs="http://www.w3.org/2001/XMLSchema">

    <xs:complexType name="XRoadIdentifierType">

        <xs:annotation>

            <xs:documentation>Globally unique identifier in the X-Road system.

                Identifier consists of object type specifier and list of

                hierarchical codes (starting with code that identifiers

                the X-Road instance).</xs:documentation>

        </xs:annotation>

        <xs:sequence>

            <xs:element minOccurs="0" ref="xRoadInstance"/>

            <xs:element minOccurs="0" ref="memberClass"/>

            <xs:element minOccurs="0" ref="memberCode"/>

            <xs:element minOccurs="0" ref="subsystemCode"/>

            <xs:element minOccurs="0" ref="groupCode"/>

            <xs:element minOccurs="0" ref="serviceCode"/>

            <xs:element minOccurs="0" ref="serviceVersion"/>

            <xs:element minOccurs="0" ref="securityCategoryCode"/>

            <xs:element minOccurs="0" ref="serverCode"/>

        </xs:sequence>

        <xs:attribute ref="objectType" use="required"/>

    </xs:complexType>

 

<xs:schema> elementide kirjeldused:

  • elementFormDefault=“qualified“
Qualified – määrab, et selles nimeruumis defineeritud elemente peab XML-i sees kasutama nimeruumi prefiksiga (<ns-prefix:element-name>). See tagab, et XML-i lugemisel on selgesti arusaadav, mis nimeruumis antud element defineeriti. Üldjuhul on soovitav kasutada väärtust „qualified“.
  • attributeFormDefault=“unqualified“
Unqualified – määrab, et selles nimeruumis defineeritud atribuudid ei pea XML-i sees omama nimeruumi prefiksit (<ns-prefix:element-name attribute1=“123“>). Ülaltoodud näites on see puudu, see tähendab, et kasutatakse vaikimisi väärtust „unqualified“
  •  targetNamespace="http://x-road.eu/xsd/identifiers"
Määrab nimeruumi (URI), mille antud XSD defineerib.
  • xmlns="http://x-road.eu/xsd/identifiers"

Määrab vaikimisi nimeruumi (default namespace). Ehk antud XSD sees võime teistele selles nimeruumis defineeritud elementidele viidata ilma prefiksita (ehk Unqualified) kujul. Näiteks: „objectType“ definitsioon viitab eelnevalt defineeritud „XRoadObjectType“ tüübile ilma prefiksita (Prefiksiga viide oleks näiteks type=„id:XRoadObjectType“)
<xs:attribute name="objectType" type="XRoadObjectType"/>


4.1.3   X-tee nimeruumide üldkirjeldus

X-tee enda poolt pakutavad nimeruumid on kirjeldatud järgnevate URI aadressidega:

Tähelepanekud X-tee versiooni 6 nimeruumide kohta:

  • X-tee versiooni 6 nimeruumis (http://x-road.eu/xsd/xroad.xsd) on kirjeldatud standardsed päiseväljad (SOAP Header elemendid);
  • ühtegi sõnumi keha (SOAP Body) elementi X-tee versioon 6 nimeruum ei defineeri;
  •  lisaks on X-tee versiooni 6 nimeruumis (http://x-road.eu/xsd/xroad.xsd) kirjeldatud WSDL operatsioonide dokumenteerimiseks kasutatavad elemendid (version, title, notes, techNotes);
  • teenuste defineerimise nimeruumi ei normeerita X-tee protokolli tasandil. See tähendab, et teenuseid võib kirjeldada ka protokolli versiooni 3.1 normeeritud nimeruumides;
  • X-tee sõnumi protokolli 4.0 kirjeldus spetsifitseerib ainult päises kasutatavate X-tee väljade definitsioonid ja reeglid;
  • X-tee teenuste loomisel  (WSDL kirjeldamisel) tuleb kasutada Document/Literal-Wrapped SOAP kodeerimise stiili ja päise kirjeldamisel tuleb lähtuda
X-tee elementide nimeruumist http://x-road.ee/xsd/xroad.xsd. Nii päringu kui ka vastuse keha peab olema mähitud ühe juurelemendi sisse.


4.1.4  X-tee versiooni 6 nimeruumi päiseväljad

X-tee versioon 6 ei erista X-tee liikmeid andmeteenuste kasutamise ja osutamise mõttes, seega X-tee andmeteenused ja kliendid (nii andmeteenuse osutajad kui ka andmeteenuse kasutajad) on kirjeldatud komplekstüüpidena.

X-tee päise elemendid on vajalikud selleks, et üheselt identifitseerida kasutajad (client) ja teenuse osutajad (service).

Turvaserver kasutab päisevälju:

  • päringute ja vastuste ruutimiseks ehk edastamiseks X-tee taristu sees õigele „füüsilisele“ adressaadile;
  • õiguste kontrolliks – kas kasutajal on õigus antud teenust kasutada;
  • autentsuse tagamiseks – automaatselt genereeritav requestHash on kasutusel selleks, et teenusekasutaja saaks kontrollida, kas teenuseosutaja turvaserver sai tema sõnumi muutmata kujul ning selle abil on lisaks võimalik siduda päringu ja vastuse ASiC-E konteinerid;  
  • logimiseks.


Lisaks on päise elemendid vajalikud andmeteenuse osutajatele ja kasutajatele endile, näiteks et:

  • teostada täiendavat kliendispetsiifilist õiguste kontrolli;
  • rakendada kliendispetsiifilisi äriloogikalisi arvutusi või filtreid. Näiteks teatud kliendile väljastatakse suurem andmete hulk kui teisele;
  • logimiseks.

X-tee nimeruumis kirjeldatud päiseväljad on kirjeldatud punktis 3.3, kuid punktis 4.1.4.1 on nad näite jaoks veelkord lahti kirjutatud.


  • xRoadInstance  - X-tee infrastruktuuri eksemplari identifikaator.  Riigi kood. Sõltub, millises X-tee keskkonnas teenus asub. Kui tõsta teenus ühest keskkonnast teise, tuleb teenuse identifikaator ära muuta. Eesti X-tee liikmete jaoks on selle väärtus:
    • EE (toodangukeskkonnas);
    • ee-test (testkeskkonnas);
    • ee-dev arenduskeskkonnas.
  • memberClass – klassifitseerib x-tee liikmeid. Eristab avaliku ja erasektori asutusi.
    • GOV (Juriidiline isik, kes on registreeritud Eesti Riigi ja kohaliku omavalitsuse asutuste registris);
    • COM (Juriidiline isik, kes on registreeritud Eesti Äriregistris);
    • NGO (Juriidiline isik, kes on registreeritud Eesti Mittetulundusühingute ja sihtasutuste registris) ja
    • NEE (Juriidiline isik, kes on registreeritud mõnes muus registris kui liikmeklassides gov, com või ngo nimetatud registris) ehk teiste riikide asutused/ettevõtted.
  • memberCode - asutuse registrikood;
  • subsystemCode – X-tee liikme alamsüsteemi unikaalne nimetus. Kuna X-tee versioonis 6 andmekogu mõiste kadus, siis seda asendab alamsüsteemi mõiste. Selle kasutamise ja defineerimise võimalused on liikmete jaoks laiemad. Alamsüsteemid on andmekogudest sõltumatud. Nad võivad kattuda andmekoguga, eksisteerida andmekogust sõltumatult või moodustada osa andmekogust. Iga liige võib dekomponeerida oma alamsüsteemid enda vajadusest lähtuvalt ja sõltumatult andmekogudest. X-tee liikmete (andmeteenuse kasutaja ja/või osutaja) vaheline teenuste päringute vahendamine toimub alamsüsteemide (subsystem) kaudu;
  •  serviceCode – andmeteenuse kood/nimetus
  • serviceVersion – andmeteenuse versioon


Näide päiseväljade elementide kasutamisest:

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"

xmlns:id="http://x-road.eu/xsd/identifiers">

<SOAP-ENV:Header>

<xrd:client id:objectType="SUBSYSTEM">

<id:xRoadInstance>EE</id:xRoadInstance>

<id:memberClass>GOV</id:memberClass>

<id:memberCode>12345678</id:memberCode>

<id:subsystemCode>alamsysteemi nimetus</id:subsystemCode>

</xrd:client>

<xrd:service id:objectType="SERVICE">

<id:xRoadInstance>EE</id:xRoadInstance>

<id:memberClass>COM</id:memberClass>

<id:memberCode>87654321</id:memberCode>

<id:subsystemCode>alamsüsteem</id:subsystemCode>

<id:serviceCode> teenuse nimetus</id:serviceCode>

<id:serviceVersion>v1</id:serviceVersion>

</xrd:service>

<xrd:userId>EE12345678</xrd:userId>

<xrd:id>11111aaaa2222</xrd:id>

<xrd:protocolVersion>4.0</xrd:protocolVersion>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

                               ….

</SOAP-ENV:Body>

</SOAP-ENV:Envelope> 


4.1.5 Muudatused versioonile 6 üleminekul 

Varasemates versioonides (versioon 5 ja varem) ei olnud X-tee liikmed hierarhiliselt kirjeldatud ja siis olid X-tee nimeruumis kirjeldatud järgmised päiseelemendid: consumer, producer, userId, id, service, issue, unit, position, userName, async, authentication, paid, encrypt, encryptCert, encrypted, encryptedCert.

Ühtlasi ei ole X-tee sõnumiprotokollis 4.0, mis versiooniga 6 kasutusele võeti, enam kirjeldatud järgmiseid päisevälju: position; userName; authenticator.

X-tee versioon 6 funktsionaalsus ei võimalda järgmiste X-tee sõnumiprotokolli versiooni 3.1 päiseväljade kasutamist:

  • async, kuna asünkroonsed päringud pole enam toetatud;
  • paid, kuna tasulised päringud pole enam toetatud;
  • encrypt, encryptCert, encrypted, encryptedCert, kuna krüpteerimise süsteem töötab automaatselt.

Kuna X-tee versioon 6 ei erista X-tee liikmeid osutamise ja kasutamise mõttes, aga X-tee versioonis 6 on liikmelisus hierarhiline, siis liikus protokolli versioonis 3.1 kasutatud päiseväli „consumer“ protokolli versioonis 4.0 päisevälja „client“ komplekstüübi sisse ning on kirjeldatud elementidega: xRoadInstance, memberClass, memberCode, subsystemCode.

Päiseelement „producer“ liikus komplekstüüpide „service“ ja „centralService“ komplekstüüpide sisse, ning on kirjeldatud elementidega xRoadInstance, memberClass, memberCode ja subsystemCode. Protokolli versioonis 3.1 kasutatud "service" liikus protokolli versioonis 4.0 "service" ja "centralService" komplekstüüpide sisse, ning on kirjeldatud elementidega xRoadInstance, serviceCode, serviceVersion (vt. ülevalpool).


Last modified: Thursday, 16 February 2017, 6:20 PM