Tievelhon rajapinnat

Swagger-dokumentaatioissa tietokokonaisuuksista käytetään termiä nimiavaruus. Rajapintakutsuissa kohdeluokkien tekniset nimet muodostuvat aina rakenteella: nimiavaruus/kohdeluokka. Kohdeluokkien tekniset nimet näkyvät rekistereiden swagger-dokumentaatioissa.

Esimerkki: Rakennerekisteriin kuuluvan ”Jakava kerros” -kohdeluokan tekninen nimi on paallysrakennekerrokset/jakavat-kerrokset.

Jokainen kohdeluokka on joko versioituva tai ei-versioituva. Tämä vaikuttaa suoraan rajapintojen käyttöön ja kohteiden elinkaaren hallintaan, erityisesti tietojen päivitysvaiheessa.

Latauspalvelu tarjoaa rajapinnat saatavilla olevien kohdeluokkakohtaisten sisältöjen luettelointiin (rajapinta /kohdeluokat), yksittäisen kohdeluokan sisältökuvauksen hakemiseksi (rajapinta /kohdeluokka) sekä kohdeluokkakohtaisen, elinvoimakeskuskohtaisen lataustiedoston hakemiseksi. Huom! Latauspalveluun tuotetaan tietosisällöt kerran vuorokaudessa klo 20 alkaen. Kaikki kohdeluokat on ladattu Latauspalveluun klo 24 mennessä.

• /kohdeluokat: Listaa latauspalvelussa saatavilla olevat kohdeluokat.
• /kohdeluokka: Palauttaa kuvauksen kohdeluokan ladattavissa olevasta tietosisällöstä. Kuvaus sisältää tiedon kohteiden jaottelusta elinvoimakeskusten aluejaon mukaisesti, kohteiden lukumäärästä kussakin lataustiedostossa sekä ajanhetkestä, jolloin sisältö on tuotettu latauspalveluun.
• Lataustiedoston haku (/kohdeluokat): Palauttaa annetun kohdeluokan kohteet NDJSON-muodossa siten, että tiedoston jokainen rivi on itsenäinen, validi JSON-objekti. Jaotteluna on elinvoimakeskusten aluejako.
• Elinvoimakeskusten aluejako: Kukin kohdeluokka on rajattu elinvoimakeskusten aluejaon mukaisesti. Kohteen tieosoite määrittää, minkä elinvoimakeskuksen alueelle kohde kuuluu. Mikäli tieosoite (tai sijaintikokoelmallisilla kohteilla tieosoitteet) osuu useammalle alueelle, kohde tuotetaan kaikkien kyseenomaisten alueiden lataustiedostoihin. Mittaustietoja lukuun ottamatta kaikkien kohdeluokkien tiedot löytyvät myös maankattavasti lataustiedostosta "koko_maa". Elinvoimakeskusten alueiden yksilöintiin käytetään nimikkeistöä, joka on saatavilla metatietopalvelusta (alueet/hallinnolliset-alueet). Katso aluejako kartalta: Elinvoimakeskukset kartta ↗.
• Ajantasaisuus ja voimassaolo: Latauspalveluun tuotetaan tietosisällöt kerran vuorokaudessa klo 20 alkaen. Kaikki kohdeluokat on ladattu Latauspalveluun klo 24 mennessä. Latauspalvelusta on toistaiseksi ladattavissa ainoastaan latauspäivänä voimassaolevat kohteet. Latauspalvelusta ei voi ladata sellaisia kohteita, joiden voimassaolo on päättynyt (esimerkiksi lakkautetut varusteet) tai jotka eivät vielä ole voimassa (esimerkiksi tulevat urakat).

Hakupalvelu tarjoaa yleiskäyttöiset lausepohjaiset kohdeluokka- ja tieosuushakutoiminnot koko Velhon tietosisällöstä hakemiseen. Kohdeluokkahaku kohdistuu yhteen tai useampaan kohdeluokkaan, ja palauttaa annettuja kriteereitä vastaavat kohteiden tiedot. Haettavien kohdeluokkien rakenne vastaa metatietopalvelussa määriteltyjä kohdeluokkia.

• Kohdeluokkahaku: Hakulausekkeessa on mahdollista rajata haun tuloksiin sisältyviä ominaisuustietoja joko ”palautettavat-kentat” tai ”poistettavat-kentat” -asetuksilla. Tieto toimitetaan yksittäisinä kohteina, joilla on kullakin oma tunnisteensa eli OID. Jos kohde koostuu useasta sijainnista (välisijaintikokoelma), hakutulos pilkkoo sen niin, että jokainen yksittäinen sijainti palautetaan omana JSON-objektinaan. Näiden objektien ominaisuustiedot ovat keskenään identtiset. Kohdeluokkahaku toimii Tievelhon käyttöliittymän tiekohdehaun mukaisesti.
• Tieosuushaku: Tulokset toimitetaan tieosoiteväleinä, joilla hakuehdoissa määritellyt ominaisuustiedot pysyvät muuttumattomina. Tieosuushaku toimii Tievelhon käyttöliittymän tieosuushaun mukaisesti.

Hakupalveluun tehtävä kysely annetaan JSON-objektina. Ohjeet hakulausekkeen muodostamiseen on esitetty hakupalvelun dokumentaatiossa ja rajapintakutsut Swagger-dokumentaatiossa.

Jokainen Velhon perusrekisteri tarjoaa REST-api-rajapinnat, joista pystyy hakemaan Velhon tietosisältöä reaaliaikaisesti. Hakutuloksia ei pysty rajaamaan yhtä monipuolisesti kuin hakupalvelussa. Tulosjoukko on rajattavissa lähinnä aikaperusteisesti joko kohteiden voimassaolotietojen tai niiden tallentamisesta ja päivittämisestä muodostuneiden aikaleimojen perusteella.

• Sijaintiperusteinen haku: Haku on mahdollista niin, että Sijaintipalvelun rajapinnasta haetaan ensin tieosoitetta tai tieosuutta leikkaavien kohdeluokan kohteiden OID-tunnukset, jotka syötetään sen jälkeen perusrekisterin rajapintaan kohdistettuun OID-hakuun.
• Rajoitukset: POST-kyselyn tulee sisältää kohteiden OID-tunnuksista muodostettu yksi JSON-lista, jonka pituus saa olla enintään 1 048 576 merkkiä. Kerralla haettavien kohteiden enimmäismäärä riippuu OID-tunnusten pituudesta, mutta vaihtelee tyypillisesti 15 000 ja 35 000 kohteen välillä.
• Suositus: Jos haku kohdistuu koko tieverkolle, suositellaan haun pilkkomista osiin. Jos käyttäjälle riittää edellisenä päivänä voimassa olleet tiedot koko tieverkolta, suositellaan Latauspalvelun käyttöä.

Keskitetty palvelu muiden palveluiden ja rekisterien hallinnoiman tietosisällön rakenteen ymmärtämiseen ja datan validointiin.

• Muoto: Tarjoaa Velhon tietosisällön kuvauksen OpenAPI 3 -standardimuodossa.
• Ominaisuudet: Mahdollistaa Velhoon tallennettavien JSON-objektien validoinnin ennen niiden oikeaa vientiä rekisterirajapintoihin. Katso tarkemmat ohjeet validoinnista seuraavasta osiosta ja Metatietopalvelun dokumentaatiosta.

Ennen tiedon tallentamista Velhoon kukin lähetettävä JSON-objekti on tärkeää validoida Velhon metatietopalvelun rajapinnassa. Validointi tapahtuu käytännössä kahdessa tasossa:

POST /metatietopalvelu/api/v2/validoi/{nimiavaruus}/{nimi}/{variantti}

Pyyntönä lähetetään validoitava JSON-objekti. Variantti tarkoittaa kohteen muokkausta (=päivitys) tai luontia.

• Onnistunut (200): Palauttaa normalisoidun version (kentät pakotettuina normaalimuotoihin, ylimääräiset poistettuna).
• Virhe (400): Palauttaa HTTPS virhekoodin "spec": "(spec-tools.core/spec {:spec (spec-tools.core/spec, jossa on kerrottu skeeman vastainen virhe JSON-objektissa.

Ei-versioituvien kohteiden tallennus hylätään tyypillisesti (HTTP 400), jos kohteilla on sama sijainti ja uuden kohteen alkupäivämäärä on sama tai aiempi kuin Velhossa jo olevan kohteen. Välimäisissä kohdeluokissa hylkäykseen riittää 1 metrin leikkaus (esim. virhesanoma "Luotavan kohteen sijaintia leikkaa joku toinen voimassaololtaan ongelmallinen kohde 1.2.246.578… …kohteen alkaen xxxx-xx-xx"), jossa xxxx-xx-xx on Tievelhossa olevan kohteen alkupäivämäärä.

Poikkeuksina ovat tietyt kohdeluokat (esim. sidotut päällysrakenteet ja mittaustiedot), joissa päällekkäisyys on luonnollista. Esimerkiksi tien päällystettä edustavassa sidottujen päällysrakenteiden kohdeluokassa sallitaan sama sijainti silloin, kun kohteet edustavat eri päällystekerroksia. Tällöin sidotun päällysrakenteen tyypin on oltava eri. Mittaustiedoille taas on tyypillistä, että samaan sijaintiin samalla sijaintitarkenteella voidaan tallentaa samaan aikaan voimassa olevia tuotanto- ja kontrollimittaustietoja.

{"kasittely":"uusi","validi":true,"rivinumero":2,"tallennus":{"virheviesti":{"virheet":[{"puuttuvat":["puoli"],"sijaintitarkenne":["reuna-alueet"],"virhe":"Kohteelta puuttuu pakollinen sijaintitarkenne","kaikki-oltava":["puoli"]},{"ylimaaraiset":["reuna-alueet"],"sijaintitarkenne":["reuna-alueet"],"virhe":"Kohteella on ylimääräisiä sijaintitarkenteita","vain-yksi-oltava":[],"kaikki-oltava":["puoli"]}],"viesti":"Luotava varuste ei ole validi"},"tulos":"virhe","palvelukutsun-statuskoodi":400}}

{"sijainnit":[{"viittaavan-kohteen-voimaantulopvm":"2021-11-02","alkuosoite":{"tie":17487,"osa":1,"etaisyys":21},"sijaintitarkenne":{"kaistat":["kaista-numerointi/kanu11"]},"viittaava-kohde":"1.2.246.578.4.5.3.3119341326.2007682771","loppuosoite":{"tie":17487,"osa":1,"etaisyys":52}}],"lisatiedot":[{"virhevastauksen-osoite":{"alkuosoite":{"tie":17487,"osa":1,"etaisyys":21},"sijaintitarkenne":{"ajoradat":["ajorata/ajr0"]},"loppuosoite":{"tie":17487,"osa":1,"etaisyys":52}},"kysytty-osoite":{"viittaavan-kohteen-voimaantulopvm":"2021-11-02","alkuosoite":{"tie":17487,"osa":1,"etaisyys":21},"sijaintitarkenne":{"kaistat":["kaista-numerointi/kanu11"]},"tunniste":"1886441217","viittaava-kohde":"1.2.246.578.4.5.3.3119341326.2007682771","loppuosoite":{"tie":17487,"osa":1,"etaisyys":52}},"vkm-virheet":[{"virhekoodi":2,"virheviesti":"Annetuilla parametreilla ei löydy tietoja","yksityiskohdat":"Annetuilla parametreilla löytyi piste mutta tällä ei ole geometriaa (piste/alkupiste). "},{"virhekoodi":2,"virheviesti":"Annetuilla parametreilla ei löydy tietoja","yksityiskohdat":"Annetuilla parametreilla löytyi piste mutta tällä ei ole geometriaa (loppupiste). "}],"kohdepaiva":null,"tilannepaiva":"2021-01-20"}]}

{"sijainnit":[{"viittaavan-kohteen-voimaantulopvm":"2022-05-23","alkuosoite":{"tie":8890,"osa":4,"etaisyys":3137},"sijaintitarkenne":{"pientareet":["piennar-numerointi/pinu08"]},"viittaava-kohde":"1.2.246.578.4.5.3.2384741175.257683542","loppuosoite":{"tie":8890,"osa":4,"etaisyys":3975}}],"lisatiedot":[{"mahdolliset-sijainnit":[{"alkuosoite":{"tie":8890,"osa":4,"etaisyys":3386},"keskilinjageometria":{"coordinates":[lista TM35-koordinaattipareista],"type":"MultiLineString"},"loppuosoite":{"tie":8890,"osa":4,"etaisyys":3985}}],"lakkautetut-sijainnit":[{"alkuosoite":{"tie":8890,"osa":4,"etaisyys":3137},"lakkautuspvm":"2023-11-30","keskilinjageometria":{"coordinates":[lista TM35-koordinaattipareista],"type":"MultiLineString"},"loppuosoite":{"tie":8890,"osa":4,"etaisyys":3376}}],"pyydetty-sijainti":{"viittaavan-kohteen-voimaantulopvm":"2022-05-23","alkuosoite":{"tie":8890,"osa":4,"etaisyys":3137},"sijaintitarkenne":{"pientareet":["piennar-numerointi/pinu08"]},"loppuosoite":{"tie":8890,"osa":4,"etaisyys":3975}}}]}

Uusia kohteita voi luoda kohdeluokkakohtaisten REST-rajapintojen kautta POST-metodilla. Pyyntönä on aina kohteen validi JSON-objekti.

POST /{rekisteri}/api/v1/kohde/{nimiavaruus}/{kohdeluokka}

• Pakolliset vs. Valinnaiset kentät: Kenttien pakollisuuden, sallitut arvot ja tietotyypit näet käyttöliittymän tietokuvauksesta ja kohdeluokkakohtaisilta ohjesivuilta. Pakollisten kenttien on oltava aina mukana (osalle voi antaa arvoksi null). Valinnaisia kenttiä ei tarvitse lähettää JSON-objektissa lainkaan, ellei niille anneta arvoa.
• Versioituvat kohdeluokat: Ensimmäisen version voimassaolon alku on aina sama kuin alkaen ja voimassaolon loppu on paattyen. Velho asettaa nämä automaattisesti luonnissa, eikä niitä tarvitse antaa pyynnössä erikseen.
• Ei-versioituvat kohdeluokat: Kun samassa tieosoitteessa oleva kohde korvataan toisella, Velho päättelee lakkautustarpeen automaattisesti. Se pilkkoo ja historioi mahdollisen alle jäävän tiedon.
• Vastaus: Onnistunut luonti palauttaa kohteen NDJSON-muodossa yhdessä järjestelmän generoiman OID-tunnuksen kanssa.

Lähetyspalvelu on tehokkain tapa siirtää suuria määriä uutta tietoa (esim. inventointiaineistot). Lähetyspalvelua käytetään tietojen päivittämiseen ja nämä tietohuoltoprosessit käydään päivittäjien kanssa erikseen läpi. Huom: Lähetyspalvelu ei ole käytettävissä rakenne- ja toimenpiderekisterille eikä ”hallinnollinen alue” -kohdeluokalle.

Lähetyspalvelun 4 askeleen prosessi:

http https://apiv2stgvelho.testivaylapilvi.fi/lahetyspalvelu/api/v1/laheta kohdeluokka=tiealueen-poikkileikkaus/ojan-pohjat "Authorization: Bearer xxxxx"

curl -X POST https://apiv2stgvelho.testivaylapilvi.fi/lahetyspalvelu/api/v1/laheta -H "Content-Type: application/json" -H "Authorization: Bearer xxxxx" -d "{\"kohdeluokka\":\"tiealueen-poikkileikkaus/ojan-pohjat\"}" --output - --compressed

http --verify=no PUT "https://lahetyspalvelu.testivaylapilvi.fi.s3.eu-west-1.amazonaws.com/zzzzz" < C:/data/ojan_pohjat.ndjson

curl -X PUT -k -T "C:\data\ojan_pohjat.ndjson" "https://lahetyspalvelu.testivaylapilvi.fi.s3.eu-west-1.amazonaws.com/zzzzz"

http -F https://apiv2stgvelho.testivaylapilvi.fi/lahetyspalvelu/api/v1/tila/yyy-yyy-yyy "Authorization: Bearer xxxxx"

curl -X GET "https://apiv2stgvelho.testivaylapilvi.fi/lahetyspalvelu/api/v1/tila/yyy-yyy-yyy" -H "Authorization: Bearer xxxxx" --output - --compressed

http -F https://apiv2stgvelho.testivaylapilvi.fi/lahetyspalvelu/api/v1/raportti/yyy-yyy-yyy "Authorization: Bearer xxxxx"

curl -X GET "https://apiv2stgvelho.testivaylapilvi.fi/lahetyspalvelu/api/v1/raportti/yyy-yyy-yyy" -H "Authorization: Bearer xxxxx" --output - --compressed

Raportin sisältö: Lähetyksen tilan ollessa ”kaikki-tallennettu-onnistuneesti”, ”osa-tallennettu-onnistuneesti” tai ”kaikki-tallennukset-epaonnistuneet”, voit pyytää raportin. Raportti sisältää lähetettyä tiedostoa vastaavat rivinumerot. Onnistuneiden kohdalla saat generoituneen OID-tunnuksen, ja epäonnistuneiden kohdalla tarkemmat tiedot virheistä (vastaa muodoltaan normaalia rekisterirajapinnan virhettä). Suosittelemme aina säästämään OID-tunnukset sisältävän raportin!

Kuivatusinventoinnissa tai kunnostusurakan yhteydessä havaittujen kaistavaurioiden tallentaminen on tyypillinen esimerkki lähetyspalvelun käytöstä. Esimerkissä samaan lähetyspalveluun lähetettävään tiedostoon on sisällytetty kaikki ne kaistavauriot, jotka on havaittu samassa inventointitapahtumassa (tapahtuman OID-tunnus tässä 1.2.246.578.8.4.2529347381.2945883666):

Lataa yllä oleva esimerkki valmiina NDJSON-tiedostona tutustumista varten:
lahetyspalvelu_esimerkki_kaistavaurio.txt ⬇

Versioituvien kohdeluokkien tietoja päivitetään REST-API-rajapinnan kautta PUT-metodilla. Ei-versioituvia kohdeluokkia ei voi päivittää lainkaan, sillä niiden elinkaarta ei hallita versioinneilla.

PUT /{rekisteri}/api/v1/kohde

• Versiointi: Päivitys luo kohteelle uuden version annetulla alkupäivämäärällä ja muuttuneilla tiedoilla. Aikaisempi versio päätetään automaattisesti tähän päivämäärään. Voit myös luoda ”väliversion” asettamalla alkupäivämäärän kahden aiemman version väliin, jolloin Velho hoitaa päättymispäivät automaattisesti.
• Tunnisteet: Päivitettävän kohteen OID-tunnus on välitettävä sekä rajapintakyselyssä että lähetettävässä JSON-objektissa. Pakolliset kentät (nähtävissä käyttöliittymän tietokuvauksesta tai kohdeluokkakohtaisilta ohjesivuilta) on aina oltava mukana, valinnaiset vain tarvittaessa.

Mitatun geometrian osalta päivityssanoma noudattaa seuraavaa logiikkaa:

• Annettu vain mitattugeometria-oid: Asetetaan uuden version mitatun geometrian tunnukseksi. Velho tarkistaa sijaintipalvelusta, että kyseinen geometria löytyy (palauttaa virheen jos ei). Tarkistusta ei tehdä, jos OID on sama kuin edellisessä versiossa.
• Annettu vain mitattugeometria: Tämä tulee uuden version mitatuksi geometriaksi.
• Annettu molemmat: mitattugeometria jätetään huomiotta ja OID-tunnus tallentuu uudelle versiolle. Tuleva muutos: Tulevaisuudessa molempien lähettäminen yhtä aikaa aiheuttaa virheen, ja kohteen päivitys epäonnistuu.
• Ei kumpaakaan: Uudelle versiolle ei aseteta mitattua geometriaa ollenkaan. Käytetään esimerkiksi silloin, kun mitattu geometria on tieosoitemuutoksen vuoksi muuttunut, mutta uutta mitattua geometriaa ei vielä tiedetä.

Kohteen fyysinen poistuminen maastosta (esim. tien piennar puretaan tai varuste poistetaan) on aina lakkautus, ei poisto. Tievelhossa kohdeluokkien kohteiden tietoja voidaan lakkauttaa REST-API-rajapinnan kautta PUT-metodilla.

PUT /{rekisteri}/api/v1/lakkauta

• Pyyntöön annetaan kohteen OID-tunnus ja lakkautuspäivämäärä.
• Lakkautuspäivämäärän tulee olla vähintään kaksi (2) päivää myöhempi kuin olemassa olevan uusimman version alkupäivämäärä. (Esim. jos kannassa uusimman kohteen version alku on 2024-10-01, aikaisin mahdollinen lakkautuspäivämäärä on 2024-10-03).
• Järjestelmä luo automaattisesti uuden version, jossa tiekohteen tila on TT06 (tiekohde purettu maastosta ja poistettu lopullisesti käytöstä). Tämän TT06-version pituus on tasan 1 päivä, eli version voimassaolo alkaa lakkautuspäivämäärästä miinus 1 päivä.
• Valinnaisesti voidaan antaa myös "muutoksen-lahde-oid" sekä sopivat varustetoimenpiteet pistemäisille varusteille.

Lataa JSON-esimerkki:
Liikennemerkin_lakkautus_esimerkki.txt ⬇

Ei-versioituvia kohteita lakkautetaan sijaintiväliä hyödyntäen. Rajapinta etsii sijaintipalvelusta kohdeluokan leikkaavat sijainnit. Jos kohde on kokonaisuudessaan sijaintivälillä, se lakkautetaan. Muutoin se pilkkoutuu automaattisesti useammaksi kohteeksi. Lakkautusta voidaan rajata kohteelle annetun sijaintitarkenteen, tyypin tai numeroinnin avulla. Erikoistapaukset löytyvät rekisterikohtaisista Swaggereista.

{
  // Pakolliset kentät
  "kohdeluokka": "tietokokonaisuus/kohdeluokka",
  "alkuosoite": {
    "tie": 3,
    "osa": 110,
    "etaisyys": 100
  },
  "loppuosoite": {
    "tie": 3,
    "osa": 110,
    "etaisyys": 150
  },
  "lakkautuspaivamaara": "2024-11-10",
  
  // Valinnainen: jos lakkautetaan vain tietty sijaintitarkenne
  "sijaintitarkenne": {} 
}

Joillakin kohdeluokilla on annettava lakkautuksen yhteydessä myös tyyppi tai numerointi, joita käytetään lakkautuksen rajaamiseen (katso rekisterikohtaiset Swaggerit). Esimerkiksi:

• Sijaintipalvelu (poikkileikkaus): Pientareet, kaistat, luiskat, ojan-pohjat, tasanne ja reuna-alueet edellyttävät numerointi-avainta ja arvoa.
• Rakennerekisteri: Sidotut päällysrakenteet vaativat avaimen sidotus-paallysrakenteen-tyyppi. Kantavat kerrokset vaativat avaimen kantavan-kerroksen-tyyppi.

Lataa JSON-esimerkit ei-versioituvien erikoistapauksille:
Sidotut-paallysrakenteet lakkauta-tieosoitevalilla.txt ⬇
Kantavat-kerrokset lakkauta-tieosoitevalilla.txt ⬇
Luiskat lakkauta-tieosoitevalilla.txt ⬇
Pintaukset lakkauta-tieosoitevalilla.txt ⬇
Valaistukset lakkauta-tieosoitevalilla.txt ⬇

Tiedon korjaamiseen ja lopulliseen tietokannasta poistamiseen on syytä ryhtyä vain silloin, kun Velhossa olevan tiedon havaitaan olevan virheellistä (esim. tallennusvirhe).

Tukipyynnön lähettämisen jälkeen Velhon operointipalvelu tarkistaa tilanteen Velhossa, toteuttaa tietokantatason korjaus- tai poistotoimenpiteen manuaalisesti ja vastaa pyynnön lähettäjälle.