Haku
Auktorisointi
Hyvinvointisovellusten rajapinnassa potilastietoihin käytetään OAuth 2.0 auktorisointia. Auktorisointi on kuvattu Kanta-auktorisointioppaassa.
Haun HTTP pyyntö (request)
Haku välitetään palvelulle HTTP POST-pyyntönä (request).
Pyynnön URL:in muoto noudattaa FHIR määrittelyjä (Style Guide). Eri ympäristöissä käytettävien URL:ien juuret ilmoitetaan erikseen eikä niitä julkisteta tässä implementointioppaassa. Implementointioppaan esimerkeissä URL:in juureen viitataan merkinnällä [base].
URL:in juuren lisäksi pyynnöissä tarvitaan palvelun API-osoitetta, joka on /api/v1/documentReference/_search. Tähän viitataan implementointioppaan esimerkeissä merkinnällä [api].
Hakuparametreja ei saa lisätä pyynnön URLiin. Perusteena on, että URLin osana hakuparametrien arvot voivat jäädä esimerkiksi verkkolaitteiden lokitietoihin.
HTTP pyynnön header
HTTP-pyynnön header-tiedot on kuvattu Kanta-palvelujen yhteisessä FHIR- ja REST-soveltamisoppaassa sivulla Kanta HTTP header-tiedot FHIR-rajapinnassa.
Kannattaa kuitenkin huomioida erityisesti headerin kenttä X-Request-Id, jonka arvo on oltava yksilöllinen jokaiselle http-pyynnölle.
Pyynnön HTTP header esimerkki
POST [base][api] HTTP/1.1
Accept: application/fhir+json;charset=UTF-8
Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJhMTcxYjFmNC04ZDkwLT...
X-Request-Id: 1.2.246.10.1.20241208102307.93.2023.11023072024880604629
Content-Type: application/x-www-form-urlencoded
HTTP pyynnön body
Haussa käytettävät hakuparametrit välitetään HTTP pyynnön body-osuudessa. Parametrien kuvaus: search.html.
- Parametrien toistuvuus:
- AND toistetaan koko parametria, parametrit erotetaan &-merkillä, esim. xxxx=103&xxxx=104 (103 AND 104)
- OR toistetaan parametrin arvoja, parametrit erotetaan pilkulla esim. xxxx=103,104 (103 OR 104)
- Seuraavien taulukoiden toistuvuus-sarakkeessa on kuvattu parametrikohtaisesti, onko parametria mahdollista toistaa, ja kumpi toistuvuustapa on käytössä.
- Aika-parametrit:
- Sallitut aikamuodot päivän tarkkuus (2013-01-14) ja sekunnin tarkkuus (2013-01-14T10:00:00+02:00) FHIR-formaatin yyyy-mm-ddThh:mm:ss+zz:zz mukaisesti tai ilman aikavyöhykettä. Ilman aikavyöhykettä annettu arvo käsitellään Helsingin aikavyöhykkeenä.
- Aika-parametrissa toistumatyyppi on AND, jolloin kyseessä on aikaväli.
- Käytössä prefiksit le, lt, ge, gt: aikavälin alarajalla tulee olla ge tai gt ja ylärajalla le tai lt, myös silloin kun annetaan vain ala- tai yläraja.
Asiakirjahaku
Palvelutapahtuma- ja hoitoasiakirjojen haussa on käytettävisssä seuraavassa taulukossa kuvatut hakuparametrit.
Taulukossa Sallitut hakuparametriyhdistelmät (tämän sivun lopussa) on kuvattu esimerkkejä parametrien käytöstä.
| FHIR-hakuparametri | Hakuparametrin tyyppi | Pakollisuus | Toistuvuus | Kuvaus |
|---|---|---|---|---|
| patient:identifier | Reference | Pakollinen | 1..1 | Potilaan virallinen henkilötunnus. Sekä system että code on annettava: patient:identifier=urn:oid:{system|code}. (system = virallisen henkilötunnuksen OID-juuri, '1.2.246.21', code = henkilötunnus) |
| effective-time | Date/DateTime | Vapaaehtoinen | 0..2, eli ala-yläraja; AND | Asiakirjan luontiaika. Huom. effective-time ja period -hakuparametreja ei saa käyttää samassa haussa. |
| period | Date/DateTime | Vapaaehtoinen | 0..2, AND | Palvelutapahtuman ajankohta. Huom. effective-time ja period -hakuparametreja ei saa käyttää samassa haussa. |
| category | Token | Vapaaehtoinen | 0..n, n = koodistosta käytettävissä olevien näkymäkoodien lukumäärä; OR |
Asiakirjan näkymäkoodi, ValueSet fihrp-vs-documentreferencecategory. Käytössä Kansallisen koodistopalvelun koodiston AR/YDIN - Näkymät (1.2.246.537.6.12.2002) mukaiset arvot pois lukien koostenäkymien koodit. Ks. sivu ValueSet. |
| type | Token | Pakollinen | 1..1 | Haettavan sisällön tyyppi, ValueSet fihrp-vs-searchtype. Palvelutapahtuma- ja hoitoasiakirjojen haussa arvo 1, Palvelutapahtuma- ja hoitoasiakirjojen haku. Ks. sivu ValueSet. |
| author:identifier | Reference | Vapaaehtoinen | 0..1 | Asiakirjan laatineen organisaation OID-tunniste. Organisaation tunnisteena käytetään Kansallisen koodistopalvelun organisaatiokoodistojen THL - SOTE-organisaatiorekisteri (1.2.246.537.6.202.2008) ja Valvira - Terveydenhuollon itsenäiset ammatinharjoittajat (1.2.246.537.6.203.2014) mukaisia arvoja. Annetaan muodossa: author:identifier=urn:oid:{code}. (code = OID-tunniste) |
Koostehaku
Koostehaussa on käytettävisssä seuraavassa taulukossa kuvatut hakuparametrit.
Taulukossa Sallitut hakuparametriyhdistelmät (tämän sivun lopussa) on kuvattu esimerkkejä parametrien käytöstä.
| FHIR-hakuparametri | Hakuparametrin tyyppi | Pakollisuus | Toistuvuus | Kuvaus |
|---|---|---|---|---|
| patient:identifier | Reference | Pakollinen | 1..1 | Potilaan virallinen henkilötunnus. Sekä system että code on annettava: patient:identifier=urn:oid:{system|code}. (system = virallisen henkilötunnuksen OID-juuri, '1.2.246.21', code = henkilötunnus) |
| effective-time | Date/DateTime | Pakollinen | 1..2, AND | Merkinnän tekoaika. |
| period | Date/DateTime | - | - | Ei käytössä koostehaussa |
| category | Token | Pakollinen | 1..7, OR | Asiakirjan näkymäkoodi, ValueSet fihrp-vs-documentreferencecategory. Koostehaussa käytössä Kansallisen koodistopalvelun koodistosta AR/YDIN - Näkymät (1.2.246.537.6.12.2002) vain koostenäkymät 333, 334, 335, 336, 341, 342, 343. Ks. sivu ValueSet. |
| type | Token | Pakollinen | 1..1 | Haettavan sisällön tyyppi, ValueSet fihrp-vs-searchtype. Koostehaussa arvo 2, Keskeisten terveystietojen koosteasiakirjojen haku. Ks. sivu ValueSet. |
| author:identifier | Reference | - | - | Ei käytössä koostehaussa |
Hakua ohjaavat parametrit
| Parametri | Tyyppi | Pakollisuus | Toistuvuus | Kuvaus |
|---|---|---|---|---|
| _count | number | Vapaaehtoinen | 0..1 | Parametri kertoo kuinka monta hakutulosta halutaan palautettavaksi yhdellä sivulla. Jos parametria ei ole annettu, käytetään oletussivukokoa. Saa käyttää kaikkien parametriyhdistelmien kanssa. Hoitoasiakirjojen haku: Oletussivukoko 10 CDA R2 asiakirjaa. Sivukoon yläraja on 25 CDA R2 asiakirjaa. Koostehaku: Oletussivukoko 50 koostemerkintää. Sivukoon yläraja on 100 koostemerkintää. |
| representative | Special | Puolesta asioinnissa pakollinen | 0..1 | Puolesta asioijan virallinen henkilötunnus. Sekä system että code on annettava: representative=urn:oid:{system|code}. (system = virallisen henkilötunnuksen OID-juuri, '1.2.246.21', code = henkilötunnus) Käytössä vain puolesta asioinnin tilanteessa. |
Sallitut hakuparametriyhdistelmät
Seuraavassa taulukossa on kuvattu sallitut hakuparametriyhdistelmät. Jokaiseen yhdistelmään voi lisätä optionaalisesti sivukokoa ohjaavan _count-parametrin. Lisäksi kaikkiin yhdistelmiin on mahdollista lisätä puolesta asioijan henkilötunnus, mikäli on kyse puolesta asioinnin tilanteesta. Esimerkkejä puolesta asioijan henkilötunnuksen käytöstä hakuparametreissa löytyy sivulta Hakuparametrien käyttö.
Huom. Alla olevissa esimerkeissä parametrit on rivitetty taulukon luettavuuden parantamiseksi.
| Parametriyhdistelmä | Kuvaus | Esimerkki |
|---|---|---|
| patient+type | Palautetaan kaikki potilaan palvelutapahtuma- ja hoitoasiakirjat. | patient:identifier=urn:oid:1.2.246.21|041222A953N&type=1 |
| patient+type+category | Palautetaan potilaan tietyn näkymän asiakirjat. Näkymärajauksen käyttö rajaa haun aina hoitoasiakirjoihin. | patient:identifier=urn:oid:1.2.246.21|041222A953N&type=1 &category=urn:oid:1.2.246.537.6.12.2002|102,urn:oid:1.2.246.537.6.12.2002|103 |
| patient+type+period | Palautetaan potilaan palvelutapahtuma- ja hoitoasiakirjat palvelutapahtuman ajankohdalla rajaten. | patient:identifier=urn:oid:1.2.246.21|041222A953N&type=1 &period=ge2024-02-25&period=le2024-03-06 |
| patient+type+category+period | Palautetaan potilaan tietyn näkymän asiakirjat palvelutapahtuman ajankohdalla rajaten. Näkymärajaus rajaa haun hoitoasiakirjoihin. | |
| patient+type+effectiveTime | Palautetaan potilaan tiettynä ajankohtana luodut palvelutapahtuma- ja hoitoasiakirjat. | patient:identifier=urn:oid:1.2.246.21|041222A953N&type=1 &effective-time=ge2023-02-25&effective-time=le2023-03-06 |
| patient+type+category+effectiveTime | Palautetaan potilaan tiettynä ajankohtana luodut tietyn näkymän asiakirjat, esim. "vuoden 2008 YLE-näkymän asiakirjat". | |
| patient+type+author | Palautetaan potilaan asiakirjat, joissa author löytyy asiakirjan palvelun tuottajana. | patient:identifier=urn:oid:1.2.246.21|041222A953N&type=1 &author:identifier=urn:oid:1.2.246.10.1234567 |
| patient+type+author+effectiveTime | Palautetaan potilaan tiettynä ajankohtana luodut asiakirjat, joissa author löytyy asiakirjan palvelun tuottajana. | |
| patient+type+author+period | Palautetaan potilaan asiakirjat, joissa author löytyy asiakirjan palvelun tuottajana palvelutapahtuman ajankohdalla rajaten. | |
| patient+type+author+category | Palautetaan potilaan tietyn näkymän asiakirjat, joissa author löytyy asiakirjan palvelun tuottajana. Näkymärajaus rajaa haun hoitoasiakirjoihin. | |
| patient+type+author+category+effectiveTime | Palautetaan potilaan tietyn näkymän tiettynä ajankohtana luodut asiakirjat, joissa author löytyy asiakirjan palvelun tuottajana. Näkymärajaus rajaa haun hoitoasiakirjoihin. | |
| patient+type+author+category+period | Palautetaan potilaan tietyn näkymän asiakirjat, joissa author löytyy asiakirjan palvelun tuottajana palvelutapahtuman ajankohdalla rajaten. Näkymärajaus rajaa haun hoitoasiakirjoihin. | |
| patient+type+category+effectiveTime | Koostehaku, palautetaan potilaan koostenäkymän mukaiset koosteet merkinnän tekoajalla rajattuna, esim. "vuoden 2008 diagnoosikooste" | patient:identifier=urn:oid:1.2.246.21|041222A953N&type=2 &category=urn:oid:1.2.246.537.6.12.2002|333 &effective-time=ge2023-02-25&effective-time=le2023-03-06 |