Možnosti rozhraní FHIR REST API pro Azure API for FHIR
V tomto článku se podíváme na některé nuance interakcí RESTful v rozhraní Azure API for FHIR.
Podmíněné vytvoření nebo aktualizace
Rozhraní Azure API for FHIR podporuje vytváření, podmíněné vytváření, aktualizace a podmíněné aktualizace definované specifikací FHIR. Jednou z užitečných hlaviček v těchto scénářích je hlavička If-Match . Hlavička If-Match se použije a před provedením aktualizace ověří verzi, která se aktualizuje. Pokud se neshoduje ETag s očekávaným ETagkódem , zobrazí se chybová zpráva 412 – Předběžná podmínka se nezdařila.
Odstranění a podmíněné odstranění
Azure API for FHIR nabízí dva typy odstranění. Existuje možnost Delete, která se také označuje jako pevné a obnovitelné odstranění a podmíněné odstranění.
Odstranit (pevné + obnovitelné odstranění)
Odstranění definované specifikací FHIR vyžaduje, aby po odstranění prostředku vrátilo následující čtení prostředku, které není specifické pro konkrétní verzi, stavový kód HTTP 410. Proto se prostředek už při hledání nenajde. Rozhraní Azure API for FHIR navíc umožňuje plně odstranit (včetně celé historie) prostředek. Pokud chcete prostředek úplně odstranit, můžete předat nastavení hardDelete parametru na hodnotu true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Pokud tento parametr nepředáte nebo nenastavíte hardDelete hodnotu false, budou i nadále k dispozici historické verze prostředku.
Poznámka
Pokud chcete odstranit pouze historii, azure API for FHIR podporuje vlastní operaci s názvem $purge-history. Tato operace umožňuje odstranit historii prostředku.
Podmíněné odstranění
Podmíněné odstranění umožňuje předat kritéria hledání k odstranění prostředku. Ve výchozím nastavení umožňuje podmíněné odstranění odstranit jednu položku najednou. Můžete také zadat parametr pro _count odstranění až 100 položek najednou. Níže najdete několik příkladů použití podmíněného odstranění.
Pokud chcete odstranit jednu položku pomocí podmíněného odstranění, musíte zadat kritéria hledání, která vrátí jednu položku.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Můžete provést stejné vyhledávání, ale zahrnout hardDelete=true také odstranit celou historii.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Pokud chcete odstranit více prostředků, zahrňte _count=100 parametr . Tento parametr odstraní až 100 prostředků, které splňují kritéria hledání.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Obnovení odstraněných souborů
Pokud nepoužíváte parametr hard delete, měly by záznamy v rozhraní Azure API for FHIR stále existovat. Záznamy se dají najít tak, že v prostředku vyhledáte historii a vyhledáte poslední verzi s daty.
Pokud je ID odstraněného prostředku známé, použijte následující vzor adresy URL:
<FHIR_URL>/<resource-type>/<resource-id>/_history
Příklad: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Pokud ID prostředku není známé, vyhledejte v historii celý typ prostředku:
<FHIR_URL>/<resource-type>/_history
Příklad: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Jakmile najdete záznam, který chcete obnovit, použijte PUT operaci k opětovnému vytvoření prostředku se stejným ID nebo pomocí POST operace vytvořte nový prostředek se stejnými informacemi.
Poznámka
Pro data o historii nebo obnovitelném odstranění neexistuje žádné vypršení platnosti na základě času. Jediným způsobem, jak odebrat historii nebo obnovitelně odstraněná data, je operace pevného odstranění nebo vyprázdnění historie.
Oprava a podmíněná oprava
Oprava je cenná operace RESTful, když potřebujete aktualizovat jenom část prostředku FHIR. Pomocí opravy můžete zadat prvky, které chcete v prostředku aktualizovat, aniž byste museli aktualizovat celý záznam. FHIR definuje tři způsoby, jak opravit prostředky: opravy JSON, opravy XML a opravy FHIRPath. Služba FHIR Service podporuje opravu JSON i opravu FHIRPath spolu s podmíněnou opravou JSON a podmíněnou opravou FHIRPath (která umožňuje opravit prostředek na základě kritérií hledání místo ID prostředku). Pokud si chcete projít některé příklady, projděte si ukázkový soubor REST opravy FHIRPath a soubor REST opravy JSON pro jednotlivé přístupy. Další podrobnosti najdete v dokumentaci HL7 pro operace oprav pomocí FHIR.
Poznámka
Při použití PATCH proti stu3 a pokud požadujete sadu Historie, je opravený prostředek Bundle.entry.request.method mapován na PUT. Je to proto, že STU3 neobsahuje definici slovesa PATCH v sadě hodnot HTTPVerb.
Oprava s opravou FHIRPath
Tato metoda opravy je nejvýkonnější, protože využívá FHIRPath k výběru prvku, na který se má cílit. Jedním z běžných scénářů je použití opravy FHIRPath k aktualizaci prvku v seznamu bez znalosti pořadí seznamu. Pokud například chcete odstranit informace o domácí telekomunikační službě pacienta, aniž byste znali index, můžete použít následující příklad.
OPRAVA http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Typ obsahu: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Všechny operace opravy FHIRPath musí mít nastavenou hlavičku application/fhir+json Content-Type. FHIRPatch Patch podporuje operace přidání, vložení, odstranění, odebrání a přesunutí. Operace oprav FHIRPatch lze také snadno integrovat do sad. Další příklady najdete v ukázkovém souboru REST opravy FHIRPath.
Oprava s využitím opravy JSON
Oprava JSON ve službě FHIR odpovídá dobře používané specifikaci definované pracovní sadou Internetových technických úloh. Formát datové části nepoužívá prostředky FHIR a místo toho používá dokument JSON využívající JSON-Pointers pro výběr elementu. Oprava JSON je kompaktnější a má testovací operaci, která umožňuje před provedením opravy ověřit, jestli je podmínka pravdivá. Pokud například chcete nastavit pacienta jako zesnulého jenom v případě, že ještě není označený jako zesnulý, můžete použít následující příklad.
OPRAVA http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Typ obsahu: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Všechny operace oprav JSON musí mít nastavenou hlavičku application/json-patch+json Content-Type. Oprava JSON podporuje operace přidání, odebrání, nahrazení, kopírování, přesunu a testování. Další příklady najdete v ukázkovém souboru REST opravy JSON.
Oprava JSON v balíčcích
Ve výchozím nastavení není oprava JSON podporovaná v prostředcích sady. Je to proto, že sada podporuje pouze prostředky FHIR a datová část opravy JSON není prostředkem FHIR. Abychom to mohli obejít, použijeme binární prostředky s typem "application/json-patch+json" obsahu a kódováním base64 datové části JSON uvnitř sady. Informace o tomto alternativním řešení najdete na webu FHIR Chat Zulip.
V následujícím příkladu chceme změnit pohlaví pacienta na ženskou. Vzali jsme opravu [{"op":"replace","path":"/gender","value":"female"}] JSON a zakódovali ji do base64.
PŘÍSPĚVEK https://{FHIR-SERVICE-HOST-NAME}/
Typ obsahu: 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}"
}
}
]
}
Další kroky
V tomto článku jste se dozvěděli o některých funkcích REST služby Azure API for FHIR. Dále se můžete dozvědět více o klíčových aspektech vyhledávání prostředků ve FHIR.
(FHIR®) je registrovaná ochranná známka společnosti HL7 a používá se se svolením HL7.