Haku
Haun HTTP pyyntö (request)
Haku välitetään palvelulle HTTP POST-pyyntönä (request).
Ajanvarausten viimeisimmät versiot haetaan search-interaktiolla: POST: [base]/Appointment/_search
Esim. POST http://example.org/baseR4/Appointment/_search
Ajanvarausten kaikki versiot haetaan history-interaktiolla: POST: [base]/Appointment/_history
Esim. POST http://example.org/baseR4/Appointment/_history
Pyynnön URL:in muoto noudattaa FHIR määrittelyjä (Style Guide). Eri ympäristöjen käytettävät juuret ilmoitetaan erikseen eikä niitä julkisteta tässä implementointioppaassa.
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
Haun HTTP-pyynnön header-osuus noudattaa Kanta-palveluiden yhteisiä Kanta FHIR HTTP header ja Kanta JSON Web Token määrittelyitä ja näissä kuvattuja tietoja ja tietojen pakollisuuksia.
HTTP pyynnön body
Ajanvarausten haussa käytettävät hakuparametrit välitetään HTTP pyynnön body-osuudessa.
Ajanvarausten haussa on käytettävisssä seuraavat hakuparametrit.
| FHIR-hakuparametri | Hakuparametrin tyyppi | Pakollisuus | FHIR-resurssi ja elementti |
|---|---|---|---|
| identifier | token | Vapaaehtoinen 0..1 | appointment.identifier - Ajanvarauksen tunniste |
| patient:identifier | reference | Pakollinen 1..1 | patient.identifier - Asiakkaan tunniste |
| service-organiser | token | Vapaaehtoinen 0..1 | Provenance.agent.who.identifier - Varatun palvelun palvelunjärjestäjä |
| appointment-service-provider | token | Vapaaehtoinen 0..1 | organization.partOf - Varatun palvelun palveluntuottaja |
| appointment-service-provider-unit | token | Vapaaehtoinen 0..1 | organization.identifier - Varatun palvelun toteuttava yksikkö |
| producing-service-provider-unit | token | Vapaaehtoinen 0..1 | Provenance.agent.who.identifier - Resurssin tallentajan palveluyksikkö. Jos hakuparametri annetaan, annettava aina myös Palveluntuottaja-hakuparametri 'appointment-service-provider' (asiakkaan tunnisteen lisäksi). |
| date | date | Vapaaehtoinen 0..2 | appointment.start - Ajanvarauksen alkuaika ** |
| recorded | date | Vapaaehtoinen 0..2 | provenance.recorded - Ajanvaraustoimenpiteen tekoaika eli ajankohta, jolloin ajanvaraus on suoritettu (Appointment-resurssin luontiaika) ** |
| register-type-code | token | Vapaaehtoinen 0..1 | provenance.extension.RegisterType - Potilasrekisteritunnus |
| service-event | token | Vapaaehtoinen 0..1 | provenance.extension.ServiceEvent - Palvelutapahtumatunnus |
| include-own | token | Vapaaehtoinen 0..1 | Palautetaanko hakutuloksessa tiedot kyselyn tekijän rekisteristä vai rajataanko ne pois (oletuksena true) |
** Sallitut ajan muodot:
- Päivätarkkuus: yyyy-mm-dd
- Sekuntitarkkuus: yyyy-mm-ddThh:mm:ss tai yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]. Ilman aikavyöhykettä annettu arvo käsitellään Helsingin aikavyöhykkeenä. LT1
Hakua ohjaavat parametrit
| Parametri | Tyyppi | Pakollisuus | Kuvaus |
|---|---|---|---|
| _count | Number | Vapaaehtoinen 0..1 | Parametri kertoo kuinka monta ajanvarausta halutaan palautettavaksi yhdellä sivulla. Historiahaussa yhteen ajanvaraukseen liittyy kaikki ajanvarauksen versiot. Jos parametria ei ole annettu, käytetään Potilastietovarannossa asetettua oletussivukokoa. |
Esimerkkejä hakuparametrien käytöstä
Yhteen hakuun voidaan liittää useita kyselyparametreja, alla esimerkkejä hakulauseista.
Kun system-arvona on vakio urn:ietf:rfc:3986, system-arvo voidaan välittää tai jättää välittämättä.
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001
Yksittäisen ajanvarauksen haku potilaan ja ajanvarauksen tunnisteen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&identifier={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja palvelunjärjestäjän perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&service-organiser={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja palveluntuottajan perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&appointment-service-provider={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja palvelun toteuttavan yksikön perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&appointment-service-provider-unit={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen, palveluntuottajan ja resurssin tallentajan palveluyksikön perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&appointment-service-provider-unit={system|value}&producing-service-provider-unit={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja ajanvarauksen alkamisajan perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&date=&date=
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&date=ge2024-01-01&date=le2024-12-31
Haku palauttaa ne tiedot, joissa Appointment.start on aikarajauksen sisällä.
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja ajanvarauksen luontiajan perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&provenance:recorded=&provenance:recorded=
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&provenance:recorded=ge2024-01-01
Haku palauttaa ne tiedot, joissa Provenance.recorded on annetun aikarajauksen mukainen.
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&provenance:recorded=ge2024-01-01&provenance:recorded=le2024-01-07
Haku palauttaa ne tiedot, joissa Provenance.recorded on aikarajauksen sisällä
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja potilasrekisteritunnuksen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}®ister-type-code={system|code}
Potilaan ajanvarausten haku palvelutapahtumatunnuksen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&service-event={system|value}
Potilaan ajanvarausten haku luovutushaku, hakua ei kohdisteta hakijan omaan rekisteriin:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&include-own=boolean
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&include-own=false
Jos kerralla halutaan palautettavaksi oletussivukokoa vähemmän ajanvarauksia, käytetään hakua ohjavaa parametria _count
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&_count=10
Potilaan ajanvarausten jatkohaku:
Ajanvarauksen vastaussanomalla palautettu sivutetun hakuvastauksen jatkohaussa käytettävissä olevat linkit (esimerkissä palautettu hakutuloksen ensimmäisen sivun tiedot):
"resourceType": "Bundle",
"type": "searchset",
"link": [
{
"relation": "self",
"url": "http://example.org/baseR4/Appointment/_search?patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=10&_count=10"
},
{
"relation": "next",
"url": "http://example.org/baseR4/Appointment/_search?patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=20&_count=10"
},
{
"relation": "previous",
"url": "http://example.org/baseR4/Appointment/_search?patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=0&_count=10"
}
]
...
Jatkohaussa käytetään vastaussanomalla palautettuja hakuparametreja, jotka ovat poimittavissa halutun sivun url-arvosta. Esim. kun halutaan hakea edellä esitetyn hakutuloksen seuraavan sivun tiedot:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=20&_count=10
Miten aikarajaus toimii
Tuetut prefixit:
- eq
- gt
- lt
- ge
- le
Esim. Hakuehto, jossa potilaan palautettavat ajanvaraukset rajataan ajanvarauksen alkuajan perusteella:
patient:identifier=urn:oid:1.2.246.21|300111A9001&date=ge2023-10-30&date=lt2023-11-02
| Päivämäärä täyttää hakuehdon | Päivämäärä ei täytä hakuehtoa |
|---|---|
| 2023-10-31T01:00:12.000 | 2023-10-29T01:00:00.00 |
| 2023-10-30T00:00:00.000 | 2023-11-02T00:00:00.00 (Ei sisälly tulosjoukkoon, koska lt-prefix haussa) |
patient:identifier=urn:oid:1.2.246.21|300111A9001&date=eq2023-10-30
| Päivämäärä täyttää hakuehdon | Päivämäärä ei täytä hakuehtoa |
|---|---|
| 2023-10-30T10:30:00.000 | 2023-10-29T20:00:00.00 |
| 2023-10-30T15:00:00.000 | 2023-10-31T07:00:00.00 |
Lisätiedot
LT1 Aikavyöhyketiedot
Tallennettavan ajanvarauksen instant-tietotyyppiä olevat tiedot sisältävät aina aikavyöhyketiedon. Potilastietovaranto ei rajoita käytettäviä aikavyöhykkeitä.
Vastauksen jsonissa Helsingin aikavyöhykkeeet (+02:00 tai +03:00).