Možnosti rozhraní FHIR REST API pro službu Azure Health Data Services FHIR
V tomto článku se podíváme na některé nuance interakcí RESTful služby Azure Health Data Services FHIR (označované jako služba FHIR).
Podmíněné vytvoření nebo aktualizace
Služba 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í
Služba 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. Služba 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 na hodnotu false, budou i nadále k dispozici historické verze prostředku.
Poznámka
Pokud chcete odstranit pouze historii, služba 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 ve službě 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.
Batch a Transaction Bundles
Ve FHIR je možné balíčky považovat za kontejner, který obsahuje více prostředků. Balíčky dávek a transakcí umožňují uživatelům odeslat sadu akcí, které se mají provést na serveru v rámci jednoho požadavku nebo odpovědi HTTP. Akce mohou být provedeny nezávisle jako "dávka" nebo jako jedna atomická "transakce", kde celá sada změn proběhne úspěšně nebo selže jako jedna entita. Mohou být odeslány akce u více prostředků stejného nebo různého typu, například vytvoření, aktualizace nebo odstranění. Další informace najdete na stránce FHIR bundles.
Interakce dávkového nebo transakčního balíčku se službou FHIR se provádí pomocí příkazu HTTP POST na základní adrese URL.
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"
}
}
}
]
}
V případě dávky se každá položka považuje za individuální interakci nebo operaci. V případě balíčku transakcí jsou všechny interakce nebo operace úspěšné nebo selžou společně. V případě dávky nebo úspěšného balíčku transakcí obsahuje odpověď jednu položku pro každou položku v požadavku. Pro neúspěšnou sadu transakcí vrátí služba FHIR jeden OperationOutcome.
Poznámka
U dávkových svazků by neměly existovat žádné vzájemné závislosti mezi různými položkami v sadě FHIR. Úspěch nebo selhání jedné položky by neměl mít vliv na úspěch nebo selhání jiné položky.
Paralelní zpracování sady batch ve verzi Public Preview
V současné době se sady Batch a transakční sady spouští sériově ve službě FHIR. Abychom zlepšili výkon a propustnost, povolujeme paralelní zpracování dávkových sad ve verzi Public Preview.
Použití funkce paralelního dávkového zpracování
- Nastavte hodnotu záhlaví "x-bundle-processing-logic" na "parallel".
- Ujistěte se, že ve stejné sadě není žádné překrývající se ID prostředku, které se spouští u operací DELETE, POST, PUT nebo PATCH.
Důležité
Paralelní zpracování sady je v současné době ve verzi Public Preview. Rozhraní API a sady SDK verze Preview se poskytují bez smlouvy o úrovni služeb. Doporučujeme je nepoužívat pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v doplňkových podmínkách použití pro Verze Preview Microsoft Azure.
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 opravy prostředků: JSON Patch, XML Patch a FHIRPath Patch. Služba FHIR 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í vyhledává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á vám před provedením opravy umožňuje 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. Důvodem je to, ž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 FHIR. Dále se dozvíte více o klíčových aspektech vyhledávání prostředků ve službě FHIR.
(FHIR®) je registrovaná ochranná známka společnosti HL7 a používá se se svolením HL7.