FHIR REST API-funktioner för FHIR-tjänsten Azure Health Data Services
I den här artikeln går vi igenom några av nyanserna i RESTful-interaktionerna i Azure Health Data Services FHIR-tjänsten (kallas härmed FHIR-tjänst).
Villkorlig skapande/uppdatering
FHIR-tjänsten stöder skapa, villkorlig skapa, uppdatera och villkorlig uppdatering enligt definitionen i FHIR-specifikationen. En användbar rubrik i dessa scenarier är if-match-huvudet . Huvudet If-Match används och verifierar den version som uppdateras innan uppdateringen görs. ETag Om inte matchar den förväntade ETagkommer det att generera felmeddelandet 412 Villkor misslyckades.
Ta bort och villkorlig borttagning
FHIR-tjänsten erbjuder två borttagningstyper. Det finns Ta bort, som också kallas hård + mjuk borttagning och villkorsstyrd borttagning.
Ta bort (hård + mjuk borttagning)
Borttagning som definieras av FHIR-specifikationen kräver att efterföljande icke-versionsspecifika läsningar av en resurs returnerar en HTTP-statuskod på 410 efter borttagning av en resurs. Därför kan resursen inte längre hittas genom sökning. Med FHIR-tjänsten kan du dessutom ta bort resursen fullständigt (inklusive all historik). Om du vill ta bort resursen fullständigt kan du skicka parameterinställningarna hardDelete till true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Om du inte skickar den här parametern eller anger hardDelete till false är de historiska versionerna av resursen fortfarande tillgängliga.
Anteckning
Om du bara vill ta bort historiken stöder FHIR-tjänsten en anpassad åtgärd med namnet $purge-history. Med den här åtgärden kan du ta bort historiken från en resurs.
Villkorlig borttagning
Med villkorsstyrd borttagning kan du skicka sökvillkor för att ta bort en resurs. Med villkorsstyrd borttagning kan du som standard ta bort ett objekt i taget. Du kan också ange parametern _count för att ta bort upp till 100 objekt åt gången. Nedan visas några exempel på hur du använder villkorsstyrd borttagning.
Om du vill ta bort ett enskilt objekt med villkorsstyrd borttagning måste du ange sökvillkor som returnerar ett enda objekt.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Du kan göra samma sökning men inkludera hardDelete=true för att även ta bort all historik.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Om du vill ta bort flera resurser inkluderar du _count=100 parametern . Den här parametern tar bort upp till 100 resurser som matchar sökvillkoren.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Återställning av borttagna filer
Om du inte använder parametern för hård borttagning bör posterna i FHIR-tjänsten fortfarande finnas. Posterna kan hittas genom att göra en historiksökning på resursen och leta efter den senaste versionen med data.
Om ID:t för resursen som togs bort är känt använder du följande URL-mönster:
<FHIR_URL>/<resource-type>/<resource-id>/_history
Exempelvis: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Om resursens ID inte är känt gör du en historiksökning på hela resurstypen:
<FHIR_URL>/<resource-type>/_history
Exempelvis: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
När du har hittat den post som du vill återställa kan du använda PUT åtgärden för att återskapa resursen med samma ID eller använda POST åtgärden för att skapa en ny resurs med samma information.
Anteckning
Det finns ingen tidsbaserad förfallotid för historik/mjuk borttagning av data. Det enda sättet att ta bort historik/mjukt borttagna data är med en hård borttagning eller rensningshistorikåtgärden.
Batch- och transaktionspaket
I FHIR kan paket betraktas som en container som innehåller flera resurser. Batch- och transaktionspaket gör det möjligt för användare att skicka en uppsättning åtgärder som ska utföras på en server i en enda HTTP-begäran/svar. Åtgärderna kan utföras oberoende av varandra som en "batch" eller som en enda atomisk "transaktion" där hela uppsättningen ändringar lyckas eller misslyckas som en enda entitet. Åtgärder på flera resurser av samma eller olika typer kan skickas, till exempel skapa, uppdatera eller ta bort. Mer information finns i FHIR-paket.
En batch- eller transaktionspaketinteraktion med FHIR-tjänsten utförs med HTTP POST-kommandot på bas-URL:en.
POST {{fhir_url}}
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "patient-1",
"name": [
{
"given": ["Alice"],
"family": "Smith"
}
],
"gender": "female",
"birthDate": "1990-05-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Patient",
"id": "patient-2",
"name": [
{
"given": ["Bob"],
"family": "Johnson"
}
],
"gender": "male",
"birthDate": "1985-08-23"
},
"request": {
"method": "POST",
"url": "Patient"
}
}
}
]
}
När det gäller en batch behandlas varje post som en enskild interaktion eller åtgärd. När det gäller ett transaktionspaket lyckas eller misslyckas alla interaktioner eller åtgärder tillsammans. För en batch eller ett lyckat transaktionspaket innehåller svaret en post för varje post i begäran. För misslyckade transaktionspaket returnerar FHIR-tjänsten enstaka OperationOutcome.
Anteckning
För batchpaket bör det inte finnas några beroenden mellan olika poster i FHIR-paketet. En posts framgång eller misslyckande bör inte påverka en annan posts framgång eller misslyckande.
Parallell bearbetning av Batch-paket i offentlig förhandsversion
Batch- och transaktionspaket körs för närvarande seriellt i FHIR-tjänsten. För att förbättra prestanda och dataflöde aktiverar vi parallell bearbetning av batchpaket i offentlig förhandsversion.
Om du vill använda funktionen för parallell batchpaketbearbetning
- Ange värdet "x-bundle-processing-logic" för sidhuvudet till "parallel".
- Kontrollera att det inte finns något överlappande resurs-ID som körs på åtgärderna DELETE, POST, PUT eller PATCH i samma paket.
Viktigt
Parallell bearbetning av paket är för närvarande i offentlig förhandsversion. Förhandsversions-API:er och SDK:er tillhandahålls utan serviceavtal. Vi rekommenderar att du inte använder dem för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller också har de begränsade funktioner. Mer information finns i Kompletterande användningsvillkor för Förhandsversioner av Microsoft Azure
Korrigering och villkorsstyrd korrigering
Korrigering är en värdefull RESTful-åtgärd när du bara behöver uppdatera en del av FHIR-resursen. Med korrigering kan du ange de element som du vill uppdatera i resursen utan att behöva uppdatera hela posten. FHIR definierar tre sätt att korrigera resurser: JSON Patch, XML Patch och FHIRPath Patch. FHIR-tjänsten stöder både JSON Patch och FHIRPath Patch tillsammans med villkorsstyrd JSON-korrigering och villkorsstyrd FHIRPath Patch (som gör att du kan korrigera en resurs baserat på ett sökvillkor i stället för ett resurs-ID). Om du vill gå igenom några exempel läser du FHIRPath Patch REST-exempelfilen och JSON Patch REST-filen för varje metod. Mer information finns i HL7-dokumentationen för korrigeringsåtgärder med FHIR.
Anteckning
När du använder PATCH mot STU3, och om du begär ett historikpaket, mappas Bundle.entry.request.method den korrigerade resursen till PUT. Det beror på att STU3 inte innehåller någon definition för verbet PATCH i HTTPVerb-värdeuppsättningen.
Korrigering med FHIRPath Patch
Den här korrigeringsmetoden är den mest kraftfulla eftersom den använder FHIRPath för att välja vilket element som ska riktas. Ett vanligt scenario är att använda FHIRPath Patch för att uppdatera ett element i en lista utan att känna till listans ordning. Om du till exempel vill ta bort en patients hemteleinformation utan att känna till indexet kan du använda exemplet nedan.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Innehållstyp: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Alla FHIRPath Patch-åtgärder måste ha rubrikuppsättningen application/fhir+json Innehållstyp. FHIRPatch Patch stöder åtgärder för att lägga till, infoga, ta bort, ta bort och flytta. FHIRPatch Patch-åtgärder kan också enkelt integreras i paket. Fler exempel finns i FHIRPath Patch REST-exempelfilen.
Korrigering med JSON-korrigering
JSON-korrigeringen i FHIR-tjänsten överensstämmer med den välanvända specifikationen som definierats av Internet Engineering Task Force. Nyttolastformatet använder inte FHIR-resurser och använder i stället ett JSON-dokument som använder JSON-Pointers för elementval. JSON Patch är mer kompakt och har en teståtgärd som gör att du kan verifiera att ett villkor är sant innan du gör korrigeringen. Om du till exempel bara vill ange en patient som avliden om de inte redan har markerats som avlidna kan du använda exemplet nedan.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Innehållstyp: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Alla JSON-korrigeringsåtgärder måste ha rubrikuppsättningen application/json-patch+json Innehållstyp. JSON Patch stöder åtgärder för att lägga till, ta bort, ersätta, kopiera, flytta och testa. Om du vill ha fler exempel kan du titta på JSON Patch REST-exempelfilen.
JSON-korrigering i paket
JSON Patch stöds som standard inte i Bundle-resurser. Det beror på att ett paket endast stöder FHIR-resurser och JSON Patch-nyttolasten inte är en FHIR-resurs. För att undvika detta använder vi binära resurser med innehållstypen "application/json-patch+json" och base64-kodningen för JSON-nyttolasten i ett paket. Information om den här lösningen finns i det här avsnittet om FHIR Chat Zulip.
I exemplet nedan vill vi ändra könet på patienten till kvinna. Vi har tagit JSON-korrigeringen [{"op":"replace","path":"/gender","value":"female"}] och kodat den till base64.
INLÄGG https://{FHIR-SERVICE-HOST-NAME}/
Innehållstyp: application/json
{
"resourceType": "Bundle",
"id": "bundle-batch",
"type": "batch",
"entry": [
{
"fullUrl": "Patient/{PatientID}",
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/{PatientID}"
}
}
]
}
Nästa steg
I den här artikeln har du lärt dig om några av REST-funktionerna i FHIR-tjänsten. Härnäst kan du lära dig mer om de viktigaste aspekterna av att söka efter resurser i FHIR-tjänsten.
(FHIR®) är ett registrerat varumärke som tillhör HL7 och används med tillstånd av HL7.