Suomi.fi-palvelutietovaranto Kaikki oleellinen julkishallinnon palveluista yhdessä paikassa

Transkriptio

1 Suomi.fi-palvelutietovaranto Kaikki oleellinen julkishallinnon palveluista yhdessä paikassa PTV-rajapinnat ja integraatiot teemakoulutus Teema: PTV-rajapinta versio 4 / metodien rakenne

2 Tavoitteet ja sisältö Tavoitteet Tiedottaa PTV:n IN-rajapinnan toteutetuista ja seuraavaan versioon suunnitelluista muutoksista Tiedon elinkaari ja tiedon tilan hallinta PTV:ssä Esitellä IN-rajapinnan teknistä aineistoa Vastata käyttäjien kysymyksiin

3 PTV API-version 4 muutoksia PTV API-versiossa 5 tulevat muutokset Rajapinnan versiointi

4 PTV versio 1.4 API versio 4 - muutokset Tilatieto päivittyy: draft, published, archived delete poistuu. Pohjakuvaukset/ Palvelut Pohjakuvausten uudet kentät: laki (legislation), linkki lakiin (linktolegislation) Pohjakuvauksen maksullisuus ja palvelutyyppi tiedot ylikirjoittavat käyttäjän antamat maksullisuus ja palvelutyyppi tiedot. Puhelin numerot: Maakoodia ei ole pakko antaa, kun numero on kansallinen palvelunumero 0800-alkuiset Organisaation ja palvelupiste metodeille lisätty ordernumber, jonka perusteella verkkosivuille voi määrittää järjestyksen, jossa ne halutaan esitettävän.

5 PTV versio 1.45 API versio 5 - muutokset POST, PUT ja GET metodit organisaation ja palvelupisteen käyntiosoite Lisätty karttakoordinaatit käytetty standardi ETRS-TM 35FIN Osoite tietojen tarkistus: osoite tai karttakoordinaatit kentässä tulee olla tietoa PUT metodi liitostiedoille Liitostietojen muokkaus Palvelut ja kanavat: Tekstimuokkaus mahdollista (rivinvaihto, luettelomerkit (bullet-list), numerointi (numero-lista) GET-metodit Tietojen palauttaminen XML-muodossa Organisaation GET metodi palauttaa palvelun nimikentän Palveluja voi hakea palveluluokka rajauksella paramerina Finton uri POST ja PUT asiointikanavan ja palvelun liitos voidaan lähettää asiointikanavan tiedoissa POST ja PUT metodit: vaihtoehtoiselle nimelle voi määrittää kieliparametrin

6 IN-rajapinta sääntöjä ja linjauksia Rajapintaversioiden ja tietokannan yhteensopivuus: 1. Uusi Open API rajapintaversio on yhteensopiva samanaikaisesti julkaistun tietokannan kanssa 2. Vanha Open API rajapintaversio on yhteensopiva samanaikaisesti julkaistun sekä kahden seuraavan tietokannan kanssa 3. Vanha tai uusi Open API rajapintaversio ei ole yhteensopiva vanhemman tietokantaversion kanssa. Yhteensopivuustaulukko (Open API vs PTV versio): Interface V1 yes yes yes Interface V2 yes yes yes Interface V3 yes yes yes Interface V4 yes yes yes Interface V5 yes yes 6

7 Tiedon elinkaari ja tiedon tilan hallinta Tietojen versiointi ja metodit Draft (luonnos) Published (julkaistu) Modified (päivitetty) Archived (arkistoitu) POST Ei sallittu Ei sallittu PUT Draft Modified Published Archived Draft 0.2, Modified (* Published 1.1, 1.2, 2.1 *( 2.0, 3.0 Versio säilyy Archived Erikoissääntö (* Yleinen sääntö 2.0, 3.0 Jos tiedon tila PTV:ssä on modified, sitä ei voi päivittää rajapinnan kautta Samanaikainen päivitys ei ole mahdollinen, jos tietue on muokkaustilassa, vaan UI tietue täytyy tallentaa ensin, ennen kuin päivitys rajapinnan kautta on mahdollista

8 PTV rajapinnat Rajapinnan tekninen dokumentaatio

9 IN-rajapinnan metodit: Open API rajapintakuvaus Mitä tietoa löydät Open API rajapintakuvaus asiakirjasta. Yleistä tietoa 1. Rajapinnan URL:sta 2. Autentikointi url:sta ja token:sta 3. Kutsuparametreista 4. PostManin käytöstä 5. Swagger:stä 6. Metodeista sisältäen kenttien listauksen ja niiden pakollisuudet

10 Open API rajapintakuvaus asiakirja sisältää yksityiskohtaisen mallin ensimmäisen metodin POST kutsuille. 1. Yhteyden muodostaminen 2. Rajapinnan token URL:it 3. Kutsuparametrit 4. Malli JSON tiedoston kuvan. 10

11 Open API rajapintametodit excel tiedosto Organization Service Service Channel Create new organization (POST) Update organization by using ID or by using Source ID (PUT) Create new service (POST) Update Service by using ID or Source ID (PUT) Create relationship between service and service channel (POST) Create new EChannel (POST) Change EChannel information by using ID or Source ID (PUT) Create new Phone channel (POST) Change Phone channel information by using ID or Source ID (PUT) Create new webpage channel (POST) Change Webpage channel information by using ID or Source ID (PUT) Create new printable form channel (POST) Change printable form channel information by using ID or Source ID (PUT) Create new Service Location channel (POST) Change Service Location channel information by using ID or Source ID (PUT) 11

12 Open API rajapintametodit excel tiedosto Open API kentän nimi Name of Interface Sourceid, oid, munincipality Tietotyyppi Type of field String, boolean, array Pakollisuus Defines if then field is mandatory or optional Optional/mandatory Ei näy käyttöliittymässä, organisaatiotunniste, kuntanimi Käyttöliittymän kenttä Name of UI Kentän kuvaus Field description 3rd party id, munincipality name Sallitut arvot What values are allowed to use True, false, arvolista Säännöt Special rules for current content Can contain letters and numbers Esimerkki Example value 491, Mikkeli Muutokset Change log Lisätty api versioon 3 12

13 Aukioloaikojen lisääminen ja päivittäminen Aukioloaika - tyyppi validfrom validto dayfrom dayto boolean Normaalit palveluajat Toistaiseksi voimassa oleva x x x Toistaiseksi voimassa oleva 24/7 validfornow Voimassa ajanjaksolla x x x x Voimassa ajanjaksolla 24/7 x x Vuorokauden yli menevät palveluajat Toistaiseksi voimassa oleva x x x Voimassa ajanjaksolla x x x x Poikkeavat palveluajat Päivä x x x Ajanjakso x x x x Päivä + Suljettu koko päivän X isclosed Ajanjakso + Suljettu ajanjaksolla x X isclosed

14 IN-rajapinnan metodit Läpikäytyjen tiedostojen sijainnit esuomi:ssä API versio Lisätietoja PTV:n usein kysytyt kysymykset sekä PTV:n arkkitehtuurikoulutukset

15 Miten pääsen käyttämään PTV:n IN-rajapintaa Organisaatio on hyväksynyt käyttöehdot ja liittyminen PTV-tietojen tuottajaksi on tehty Organisaatio on nimennyt teknisen yhteyshenkilön ja tietoturvayhteyshenkilön varahenkilöineen Hakenut API-tunnusta IN-rajapintaa varten. Tunnista voit hakea täältä löytyvällä lomakkeella Hakemuksen perusteella VRK tuottaa organisaatiolle API-tunnuksen, joka on muotoa ja lähettää asiakkaalle API-tunnuksen, salasanan sekä URLn koulutusympäristöön, jossa IN-rajapinnan testaaminen tapahtuu Tuotantoon organisaatio voi IN-rajapinnan kautta tuottaa tietoja sen jälkeen, kun testaus on suoritettu hyväksytysti

16 PTV OUT rajapinta

17 OUT rajapinta pilottitoteutus Kunta API on keskusrajapintapalvelu, jonka avulla samaan rajapintaan voidaan koostaa informaatiota useasta eri lähteestä. Mikkelin toteutus ja kunta API Perustiedot haetaan PTV:stä Tietoja voidaan rikastaa hallintaliittymällä esimerkiksi lisäämällä kuvia, tai videoita Tulossa: PTV IN-rajapinta integrointi 17

18 WordPress pilotti projekti Asiointipalvelu Kunta.fi Janakkala, Hausjärvi, Loppi. Loviisa, Rauma, Riihimäki Suomi.fi-verkkopalvelu Janakkalan kunnan vetämämä pilottihankke. OUT rajapinta Yhteistyökunnat: Hausjärvi, Loppi, Loviisa, Rauma ja Riihimäki. Suomi.fipalvelutietovaranto WordPress-integraatio PTVjärjestelmään WP-PTV -lisäosa WordPressiä käyttävien kuntien saataville. PTV Sisältöjen ylläpitäjät Lisäosan lähdekoodi julkaistaan GitHubissa heinäkuussa IN rajapinta

19 Lisätietoja esuomi.fi ja PTV-in rajapinta materiaalia löytyy esuomi.fistä Rajapinnan versiotiedote: IN-rajapinnan testausohje löytyy esuomi.fin ladattavista aineistoista täältä: IN-rajapinta Apin kuvaukset löytyvät osoitteesta PTV-rajapintojen skeemat ovat saatavilla swaggerissa osoitteessa HUOM! Swaggerissa on valittava haluttu versio erikseen. Pohjakuvausten tiedot ja tuotantoympäristön ID:t löytyvät: 19

20 Liitemateriaalia 1 Esimerkkejä PTV-tiedoista beta.suomi.fissä

21 PTV-tiedot beta.suomi.fissä. Esimerkkinä kunnallinen päiväkotihoito. Service/serviceNames[type:Name] Service/serviceOrganizations[ type:responsible] Pohjakuvaus Tuotetaan ja ylläpidetään suomi.fipalvelun verkkotoimituksessa Palvelun tarkenne Kunta / muu toimija tarkentaa ja kertoo, miten palvelu on järjestetty Maksullisuus Kielet, joilla palvelu on saatavilla Service/statutoryServiceGeneralDesc riptionid Service/serviceDescriptions[ type: Description] Service/serviceChargeType Service/languages Service/serviceAndChannel [serviceid,channelid]

22 PTV-tiedot beta.suomi.fissä. Esimerkkinä kunnallinen päiväkotihoito Palvelupisteitä näytetään ensimmäiset. Loput saa näkymiin avaamalla. ServiceChannelLocation/serviceChannelN ames [value] ServiceChannelLocation/serviceChannel Descriptions[ type: shortdescription] Kunta tai muu toimija kuvaa toimintaohjeet, miten palveluun hakeudutaan Service/serviceDescriptions[ type: serviceuserinstruction]

23 PTV-tiedot beta.suomi.fissä. Esimerkkinä kunnallinen päiväkotihoito. ServiceChannelLocation/a ddresses[ type: Visiting]

24 Käyttöliittymässä 1/2 Superuser (Eeva) PTV pääkäyttäjä (Pete) PTV ylläpitäjä (Shirley) API käyttäjä Pääorganisaation luonti Sallittu Ei sallittu Ei sallittu Ei sallittu Lisätietoa Pääorganisaation arkistointi* Sallittu Ei sallittu Ei sallittu Ei sallittu * Arkistointi poistaa organisaation suomi.fi verkkopalvelusta Pääorganisaation tietojen muokkaus (lisäys/muutos/poisto) Organisaatiorakenteen (puun) muutokset Sallittu Sallittu* Sallittu* Ei sallittu *Nimen muutos ei sallittu (05/2017 hoidetaan Palvelunhallinnan kautta) Sallittu (09/2017) Sallittu (09/2017) Ei sallittu Ei sallittu Ei tuettu vielä, tulossa 09/2017 Alaorganisaation luonti Sallittu Sallittu Ei sallittu Ei sallittu Alaorganisaation arkistointi Sallittu Sallittu Ei sallittu Ei sallittu Alaorganisaation tietojen muokkaus (lisäys/muutos/poisto) Palvelujen tai asiointikanavien luonti Palvelujen tai asiointikanavien arkistointi Palvelu tai asiointikanavien tietojen muokkaus (lisäys/muutos/poisto) Sallittu Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu

25 Käyttöliittymässä 2/2 Superuser (Eeva) PTV pääkäyttäjä (Pete) PTV ylläpitäjä (Shirley) API käyttäjä Liitosten luonti Sallittu Sallittu Sallittu Ei sallittu Lisätietoa Liitosten poisto Sallittu Sallittu Sallittu Ei sallittu Liitosten lisätietojen muokkaus (lisäys/muutos/poisto) Sallittu Sallittu Sallittu Ei sallittu Pohjakuvausten luonti Sallittu Ei sallittu Ei sallittu Ei sallittu Pohjakuvausten poisto Sallittu Ei sallittu Ei sallittu Ei sallittu Pohjakuvausten tietojen muutokset Sallittu Ei Sallittu Ei sallittu Ei sallittu Pohjakuvausten käyttö palveluissa Sallittu Sallittu Sallittu Ei sallittu

26 IN API rajapinnassa 1/2 Superuser (Eeva) PTV pääkäyttäjä (Pete) PTV ylläpitäjä (Shirley) API käyttäjä Lisätietoa Pääorganisaation luonti Ei sallittu Ei sallittu Ei sallittu Ei sallittu Vain Palvelunhallinnan kautta (05/2017) Pääorganisaation arkistointi* Sallittu Ei sallittu Ei sallittu Ei sallittu * Arkistointi poistaa organisaation suomi.fi verkkopalvelusta Pääorganisaation tietojen muokkaus (lisäys/muutos/poisto) Organisaatiorakenteen (puun) muutokset Sallittu Sallittu Ei sallittu Sallittu *Nimen muutos ei sallittu (05/2017 hoidetaan Palvelunhallinnan kautta) Ei sallittu Ei sallittu Ei sallittu Ei sallittu Alaorganisaation luonti Sallittu Sallittu Ei sallittu Sallittu Alaorganisaation arkistointi Sallittu Sallittu Ei sallittu Sallittu Alaorganisaation tietojen muokkaus (lisäys/muutos/poisto) Palvelujen tai asiointikanavien luonti Palvelujen tai asiointikanavien arkistointi Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu Sallittu Sallittu Ei sallittu Sallittu

27 IN API rajapinnassa 2/2 Palvelu tai asiointikanavien tietojen muokkaus (lisäys/muutos/poisto) Superuser (Eeva) PTV pääkäyttäjä (Pete) PTV ylläpitäjä (Shirley) API käyttäjä Sallittu Sallittu Ei sallittu Sallittu Liitosten luonti Sallittu Sallittu Ei sallittu Sallittu Lisätietoa Liitosten poisto Sallittu Sallittu Ei sallittu Sallittu * Tulossa 05/2017 Liitosten lisätietojen muokkaus (lisäys/muutos/poisto) Sallittu Sallittu Ei sallittu Sallittu * Tulossa 05/2017 Pohjakuvausten luonti Sallittu Ei sallittu Ei sallittu Ei sallittu Pohjakuvausten poisto Sallittu * Ei sallittu Ei sallittu Ei sallittu * Tulossa 05/2017 Pohjakuvausten tietojen muutokset Sallittu * Ei Sallittu Ei sallittu Ei sallittu * Tulossa 05/2017 Pohjakuvausten käyttö palveluissa Sallittu Sallittu Ei sallittu Sallittu

28 Kiitos! Yhteydenotot: Lisätietoja: PTV-video: 28