Suomi.fi-palvelutietovaranto PTV-rajapinnat ja integraatiot teemakoulutus Teema: Teema: PTV:n versio 1.3 IN-rajapinta / metodien rakenne 15.12.2016
Tavoitteet ja sisältö Tavoitteet Tiedottaa PTV:n IN-rajapinnan toteutetuista ja seuraavaan versioon suunnitelluista toiminnallisuuksista Esitellä IN-rajapinnan teknistä aineistoa Kuvata pohjakuvauksen liittämistä palvelun tietoihin Vastata käyttäjien kysymyksiin Sisältö IN-rajapinnan metodit ja kenttien sisältö PTV:n IN-rajapinnan aineisto Osallistujien kysymyksiä
PTV:n toiminnallisuudet
Versiossa 1.3 tulevat uudet toiminnallisuudet Palveluiden ja asiointikanavien yhteen liittäminen käyttöliittymän kautta uudella tavalla sekä lisätietojen antaminen liitoksille º Palveluiden ja kanavien liitoksen yhteydessä käyttäjä voi lisätä liitokselle kuvaustekstin sekä maksullisuuden tiedot. Karttakoordinaatit º Organisaation ja palvelupisteen käyntiosoitteen perusteella PTV käy hakemassa osoitetta vastaavat koordinaatit. Puhelinnumero-, sähköposti- ja verkko-osoitekenttiä on yhdenmukaistettu Palvelutietovarannon sisältöjen kuvaaminen mahdollista myös ruotsiksi ja englanniksi OPEN API -rajapinnan versioituminen Palvelutietovarannon lähdekoodin avoimeksi 4
PTV tulevat versiot (alustava suunnitelma) Versio 1.35 Julkaisupäivä Tammikuu 2017 Palvelutyyppi tietojen muutos: Lupa, Ilmoitus ja rekisteröinti tyyppiset palvelut yhdistetään yhden palvelutyypin alle. Digital Authorizations / Asiointivaltuudet käyttäjä määrittelee voiko kyseisen palvelun yhteydessä käyttää sähköistä asiointivaltuutusta käyttäjä tekee määrittelyn palvelukanavien kautta (esim. puhelinasiointi) käyttäjä kirjaa palveluun liitetyn palvelukanavan lisätietokenttään tiedon sähköisestä asiointivaltuutuksesta. Versio 1.4 Maaliskuu 2017 Käyttäjien roolit ja organisaatio mukaiset näkyvyydet listat aakkoselliseen järjestykseen Automaattinen annotointi Versio 1.5 Toukokuu 2017 Linkkivalidaattori Palvelukokonaisuus (Palvelutarjoama)
PTV rajapinnat Rajapinnan versionti Rajapinnan tekninen dokumentaatio
IN-rajapinta sääntöjä ja linjauksia Rajapintaversioiden ja tietokannan yhteensopivuus (rel 1.3:ssa): 1.Uusi Open API rajapintaversio on yhteensopiva samanaikaisesti julkaistun tietokannan kanssa 2.Vanha Open API rajapintaversio on yhteensopiva samanaikaisesti julkaistun sekä seuraavan uudemman tietokannan kanssa 3.Vanha tai uusi Open API rajapintaversio ei ole yhteensopiva vanhemman tietokantaversion kanssa. Yhteensopivuustaulukko (Open API vs DB): DB V1 DB V2 DB V3 DB V4 Interface V1 yes yes Interface V2 yes yes Interface V3 yes yes 7
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
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. 9
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) 10
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 11
PTV OUT rajapinta
OUT-rajapinta Tietojen hyödyntäminen Koko Suomi taskussa Koko Suomi kartalla AVOIN RAJAPINTA NÄKYMÄ KAIKKEEN
OUT rajapinta pilottitoteutus Mikkelin toteutus ja kunta API Perustiedot haetaan PTV:stä Tietoja voidaan rikastaa hallintaliittymällä esimerkiksi lisäämällä kuvia, tai videoita 14
Etukäteen saatuja kysymyksiä Onko verkkosivuille tehty millaisia integrointeja out-rajapinnan kautta? Meillä on käytössä drupal verkkosivujen alustana ja tarkoituksena hyödyntää ptv:n tietoja kaupungin sivuilla. 15
PTV:n pohjakuvauksen liittäminen palvelun tietoihin
Pohjakuvauksen liittäminen palveluun Pohjakuvauksen metatiedot CreateService Tiedot tuotetaan INrajapinnan kautta Tiedoissa mukana omat metatiedot ja pohjakuvauksen ID Palvelun metatiedot Palvelun pohjakuvaus Kunnan palvelukuvaus Pohjakuvaus ID
Pohjakuvauksen lisääminen palveluun UpdateService Tiedot päivitetään INrajapinnan kautta. Tiedoissa mukana PalveluID PohjakuvausID Kunnan palvelu-kuvaus Palvelun pohjakuvaus Palvelukuvauksen päivitetty versio
Pohjakuvauksen lisääminen palveluun Käyttöliittymän kautta Kunnan palvelukuvaus Palvelun pohja-kuvaus
IN-rajapinnan metodit Läpikäytyjen tiedostojen sijainnit esuomi:ssä API versio 2 º https://esuomi.fi/mdocsposts/finnish_service_catalogue_operative_description-api2/ º https://esuomi.fi/mdocs-posts/open-api-metodit-versio-2/ Lisätietoja PTV:n usein kysytyt kysymykset sekä PTV:n arkkitehtuurikoulutukset
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 https://response.questback.com/vestrekisterikeskus/apitunnus. Hakemuksen perusteella VRK tuottaa organisaatiolle API-tunnuksen, joka on muotoa api@organisaationnimi.fi 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
Lisätietoja esuomi.fi ja PTV-tuki@vrk.fi PTV-in rajapinta materiaalia löytyy esuomi.fistä https://esuomi.fi/palveluntarjoajille/palvelutietovaranto/ptv-arkkitehtuuri/ IN-rajapinnan testausohje löytyy esuomi.fin ladattavista aineistoista täältä: https://esuomi.fi/mdocs-posts/in-rajapinnan-testausohje/ IN-rajapinta Apin kuvaukset löytyvät osoitteesta https://esuomi.fi/aineisto/suomi-fi-palvelutietovaranto/?mdocs-cat=mdocs-cat- 19&att=Suomi.fi-palvelutietovaranto PTV-rajapintojen skeemat ovat saatavilla swaggerissa osoitteessa https://api.palvelutietovaranto.suomi.fi/swagger/ui/index.html HUOM! Swaggerissa on valittava haluttu versio erikseen. Pohjakuvausten tiedot ja tuotantoympäristön ID:t löytyvät: https://esuomi.fi/mdocs-posts/pohjakuvaukset-ja-idt-tuotantoymparistossa/ 22
Kiitos! Yhteydenotot: ptv-tuki@vrk.fi Lisätietoja: http://esuomi.fi/palveluntarjoajille/palvelutietovaranto/ PTV-video: https://www.youtube.com/watch?v=2vhqaxbqnws 23