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
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 | _count | 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ää. |
| queryId | Jatkohaussa pakollinen |
Sivutetun vastauksen jatkohaussa käytettävä parametri. Käytössä vain jatkohaussa. Jatkohaussa on käytettävä vastauksessa jatkohakua varten palautuneita parametreja muuttumattomina seuraavaa sivua haettaessa. Jatkohaun hakuparametrit on välitettävä POST-pyynnön body-osassa, koska kysely sisältää henkilötunnuksen. Ks. sivulta Haun vastaus osio "Sivutettu vastaus". |
Sallitut hakuparametriyhdistelmät
Seuraavassa taulukossa on kuvattu sallitut hakuparametriyhdistelmät. Jokaiseen yhdistelmään voi lisätä optionaalisesti sivukokoa ohjaavan _count-parametrin.
Huom. Esimerkissä 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 |