Tämä artikkeli kuvaa teknisiä tietoja, joita tarvitaan asennettaessa ulkoinen REST API -palvelu vastaanottamaan henkilötietoja Neptonista ajastetun henkilöviennin kautta. Tietoja ajastetun viennin asentamiseksi henkilövientiä varten, myös REST API -asetuksista, löydät Henkilötietojen ajastettu vienti -sivulta sekä tietomuotokohtaisilta CSV- ja JSON-sivuilta.
Pyyntöviesti
Tämä osio kuvaa ne HTTP-pyynnöt, joita Nepton-palvelu lähettää ottaessaan yhteyttä ulkoiseen REST API -palveluun viedäkseen henkilötietoja. Lähetettävän sisällön tietomuoto – valitun tietomuodon mukaan – on kuvattu sivuilla Vie henkilöt - Oletusarvoinen CSV-tietomuoto ja Vie henkilöt - JSON-tietomuoto.
Vastaanottavan palvelun osoite
Ajastettu henkilövienti käyttää HTTP PUT -metodia ottaessaan yhteyttä REST API -palveluun. Palvelun on tuettava TLS-protokollaa (osoite on määriteltävä https://-etuliitteellä).
Autentikaatiotyyppi
Ei autentikointia
Jos "Ei autentikointia" on valittuna autentikaatiotyypiksi, tiedot lähetetään palveluun odottamatta mitään tunnistautumisvalintoja.
Perus-HTTP-autentikointi
Perus-HTTP-autentikointi lisää Authorization-otsikon arvolla "Basic", jonka jälkeen seuraavat välilyönti ja "username"- ja "password"-parametrien arvot kaksoispisteellä eroteltuina – muodossa username:password - UTF-8-koodauksella konvertoituna Base64-merkkijonoksi.
Esimerkki:
Authorization: Basic c2FtcGxldXNlcm5hbWU6YW0jbWFhNmZtMjh2bWYmR2xo
jossa c2FtcGxldXNlcm5hbWU6YW0jbWFhNmZtMjh2bWYmR2xo on sampleusername:am#maa6fm28vm&Glh (username- ja password-parametrien arvot ajastetun tehtävän asetuksista yhdistettyinä kaksoispisteellä) muunnettuna Base64-merkkijonoksi.
OAuth 2.0 (perus-HTTP-autentikointi)
OAuth 2.0 -tunnistautuminen ottaa ensin yhteyttä annettuun valtuutuspalveluun HTTP POST -metodilla käyttäen Authorization-otsikkoa, joka on samankaltainen kuin Perus-HTTP-autentikoinnissa. Valtuutuspalvelimen on tuettava TLS-protokollaa (osoite on määriteltävä https://-etuliitteellä).
Onnistuneessa vastauksessa valtuutuspalvelimelta tulee olla sisältönä JSON-objekti, jossa on ainakin access_token-kenttä määriteltynä. Vastausviestin muoto (viestissä voi olla enemmän HTTP-otsikkorivejä):
HTTP/1.1 200 OK Content-Type: application/json;charset=utf-8 Content-Length: 119 { "access_token": "secret_access_token_value", "token_type": "token_type", "expires_in": 999999, "scope": "scope" }
Kentän access_token arvo välitetään sitten annetulle REST API -palvelulle Authorization-otsikossa:
Authorization: Bearer secret_access_token_value
jossa secret_access_token_value on valtuutuspalvelimelta saadun vastauksen access_token-kentän arvo.
Tunnussanavaltuutus
Tunnussanavaltuutus lisää apikey-parametrin arvon Authorization-otsikkoon TOKEN-etuliitteellä.
Esimerkki Authorization-otsikosta:
Authorization: TOKEN salainen_api-avain
jossa salainen_api-avain on apikey-parametrin arvo ajastetun tehtävän asetuksista.
Turvallisuusprotokollat
Palvelun ja mahdollisen OAuth 2.0 -valtuutuspalvelun on tuettava TLS-protokollaa ja niiden osoitteet on määriteltävä https://-etuliitteellä. Tällä hetkellä tuemme TLS 1.2 ja TLS 1.1 -turvallisuusprotokollia.
100-Continue -toiminto
Ennen tietojen lähettämistä tehdään HTTP PUT-metodilla pyyntö Expect-otsikolla, jonka arvona on "100-continue" (jatka). Viestissä ovat mukana kaikki muut pyynnön otsikot, mutta viestissä ei ole mukana tietosisältöä:
Content-Length: 25959 Expect: 100-continue
Vastauksen odotetaan olevan HTTP-vastaus 100 (continue – jatka) merkiksi onnistuneesta tunnistautumisesta ja muiden otsikkotietojen hyväksynnästä ennen kuin lähetetään varsinainen data:
HTTP/1.1 100 Continue
Jos palvelin ei voi hyväksyä viestiä, se voi vastata HTTP-vastauksella 417 (expectation failed – odotuksiin ei voida vastata):
HTTP/1.1 417 Expectation Failed
tai muulla sopivalla vastauksella, esim. HTTP-vastauksella 401 (unauthorized – ei valtuutusta):
HTTP/1.1 401 Unauthorized
Sisällön tyyppi
Pyynnön sisällön tyyppi lähetetään Content-Type-otsikon arvona: lähetettävän sisällön mediatyyppi ("application/json" JSON-muodolle, "text/csv" CSV-muodolle), jota seuraa ";charset=" ja sisällön merkistökoodaus ("utf-8" UTF-8-merkistökoodaukselle (Unicode-merkistö) tai "iso-8859-1" ISO-8859-1-merkistökoodaukselle ("Latin 1" -merkistö)).
Esimerkkejä:
Content-Type: application/json;charset=utf-8
Content-Type: text/csv;charset=iso-8859-1
Sisällön pituus
Viennissä siirrettävän henkilötietosisällön pituus tavuina lähetetään Content-Length-otsikon arvona.
Esimerkki:
Content-Length: 3909
Vastausviesti
Tämä osio kuvaa ne HTTP-vastausviestien sisällöt, joita Nepton-palvelu odottaa vastauksena ulkoiselta REST API -palvelulta vietyään henkilötietoja.
Vastausviestit JSON-tiedoston lähetykseen
Siirto onnistui – raportit yksittäisistä henkilötiedoista
Nepton-palvelu odottaa HTTP-vastausta onnistuneella tilakoodilla (tilakoodi välillä 200–299, esim. tilakoodi 200: OK), jos ulkoinen palvelu otti siirretyn viestin onnistuneesti vastaan.
Vastauksen on oltava JSON-objekti, ja objektin on sisällettävä vientiviestissä olleiden yksittäisten henkilöiden tietojen tilat. JSON-objektivastauksessa tulee olla seuraavat avainnimet:
- "Status"-avain (tila). Sen arvona tulisi olla teksti: "Success" (onnistui). Tämä tarkoittaa, että vientiviesti saatiin käsiteltyä – yksittäisten henkilötietojen käsittelyssä on silti voinut olla ongelmia. Jos Status-kentän arvo on: "Error" (virhe) – tai mikä tahansa muu arvo kuin "Success" – palveluun raportoidaan, ettei mitään tietoa saatu käsiteltyä.
- "StatusByEmployee"-avain (työntekijätiedon tila) JSON-objektien taulukkona. JSON-objekteja tulee olla kutakin yksittäistä henkilövientitiedostossa olevaa henkilöä kohden. Jokaisessa JSON-henkilöobjektissa tulee olla seuraavat avaimet:
- "EmployeeNeptonId" (työntekijän Nepton-tunniste) – pakollinen avain, jota vastaa Nepton-tunnisteen sisältävä merkkijonoarvo, NeptonPersonGUID-kentän arvo henkilövientitiedostosta.
- Jos yksittäisen henkilön tietojen käsittely onnistui, StatusByEmployee-objektissa pitäisi olla yksi tai useampia seuraavista avaimista, jotta yksittäisen henkilön tietojen viennin katsottaisiin onnistuneen. Näitä avaimia vastaavien arvojen tulisi olla JSON-objekteja, joilla on ainakin yksi avain. Arvojen tietomuotoa ei tällä hetkellä ole rajoitettu:
- Added (lisätty)
- Modified (muokattu)
- NoChanges (ei muutoksia)
- RemovedInfo (poistetut tiedot)
- Jos yksittäisen henkilön tietojen käsittelyssä tapahtui virhe tai siihen liittyi mitä tahansa varoituksia, yksi tai molemmat seuraavista avaimista pitää lisätä. Niiden arvot tallennetaan palvelulokiin varoitusviestinä, ja yksittäisen henkilön tietojen viennin katsotaan epäonnistuneen:
- FatalError (virheet, jotka estivät koko käsittelyn)
- Warnings (varoitukset)
- Sekä pääobjektissa että yksittäisissä StatusByEmployee-objekteissa voi olla muitakin avaimia. Niiden tietoja ei tällä hetkellä käsitellä, mutta kaikki tiedot vastauksessa saattavat päätyä vastaavaan palvelulokimerkintään.
Esimerkki (viestissä voi olla enemmän HTTP-otsikkorivejä):
HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Content-Length: 905 { "Status": "Success", "StatusByEmployee": [ { "EmployeeNeptonId": "206894AF-E2E6-5F11-B988-DD9E52BD067A", "Added": { "Field1": "Success", "Field2": "Success", "Field3": "Success" }, "Modified": { "Field4": "Success" }, "NoChanges": { "Field5": "Success" }, "RemovedInfo": { "Field6": "Success" }, "Mikä tahansa tieto": "Ylimääräisiä avaimia voi olla mukana – ne eivät vaikuta tuloksen tulkintaan" }, { "EmployeeNeptonId": "D9D6AA30-58A9-43E4-A66A-12193A71C25E", "Modified": { "Field1": "Success" }, }, { "EmployeeNeptonId": "2CA5D9DF-5B57-446A-879B-FC8F704FA0F7", "FatalError": "Pakollinen kenttä puuttuu: XX-järjestelmä vaatii \"Henkilötunnus\"-kentän", }, { "EmployeeNeptonId": "FEE31CF4-B4BF-4DDF-ADAD-5ACB1B8CD130", "Warnings": "Virheellinen arvo: \"Hallinnon lisätieto\" (\"1CC\")" } ] }
Siirto epäonnistui
On suositeltavaa lähettää vastauksessa onnistumisen HTTP-tilakoodi (tilakoodi välillä 200–299), jos mitään siirtoon liittyvää virhettä ei tapahtunut. Tarkemmat yksityiskohdat voidaan ilmoittaa alla kuvatulla muodolla. Jos palvelimen on vain ilmoitettava, että vastaanotto epäonnistui tai palvelu ei voinut käsitellä tietoja lainkaan, se voi vaihtoehtoisesti lähettää virhevastauksen – HTTP-asiakkaan virhevastauksen (tilakoodi välillä 400–499), HTTP-palvelimen virhevastauksen (välillä 500–599) tai minkä tahansa muun virheeksi luokiteltavan vastauksen – ja se lisätään palvelulokin virheraporttiin.
Jos vastauksen sisältönä on JSON-objekti, jonka "Status"-avainta (tila) vastaavana arvona on "Error" (virhe) – tai mikä tahansa muu arvo kuin "Success" (onnistui) – tai jos "ErrorMessage"-avainta (virheilmoitus) vastaavana arvona on jokin viesti, koko viennin katsotaan epäonnistuneen. Mikä hyvänsä virheviesti "ErrorMessage"-avaimen arvona kirjataan palvelulokin virheilmoitukseen.
Esimerkki (viestissä voi olla enemmän HTTP-otsikkorivejä):
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Content-Length: 74 { "Status": "Error", "ErrorMessage": "Lokiin kirjattava virheilmoitus" }
Virheitä ja varoituksia yksittäisten henkilöiden tiedoista henkilövientitiedostossa ei pidä raportoida yleisinä virheinä, vaan käyttäen "FatalError"- ja "Warnings"-avaimia "StatusByEmployee"-taulukon objekteissa, katso Siirto onnistui – raportit yksittäisistä henkilötiedoista.
Vastausviestit CSV-tiedoston lähetykseen
Siirto ja käsittely onnistui
Jos ulkoinen REST API -palvelu vastaanotti ja pystyi käsittelemään sisällön odotetulla tavalla, sen odotetaan vastaavan onnistuneella HTTP-tilakoodilla (tilakoodi välillä 200–299), esim. tilakoodilla 200: OK. Mitään muuta tietoa kuin onnistunut HTTP-tilakoodi ei vaadita onnistuneeksi vastaukseksi, kun sisältö lähetettiin CSV-muodossa. Jos viestin sisältönä on tietoa, se kirjataan tietona palvelulokiin onnistuneen suorituksen merkintään.
Esimerkki (viestissä voi olla enemmän HTTP-otsikkorivejä):
HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Content-Length: 2 OK
Siirto tai käsittely epäonnistui
Jos ulkoiseen REST API -palveluun siirrossa tai tietojen käsittelyssä palvelussa oli ongelmia, palvelun odotetaan vastaavan epäonnistumista osoittavalla HTTP-tilakoodilla. Koodi voi HTTP-asiakkaan virhevastaus (tilakoodi välillä 400– 499), HTTP-palvelimen virhevastaus (välillä 500–599) tai mikä tahansa muu virheeksi luokiteltava vastaus. Vastauskoodi ja kaikki tiedot vastausviestin sisällössä tallennetaan palvelulokiin virheilmoituksena.
Esimerkki (viestissä voi olla enemmän HTTP-otsikkorivejä):
HTTP/1.1 500 Internal Server Error Content-Type: text/plain; charset=utf-8 Content-Length: 41 Odottamaton virhe tietojen käsittelyssä