Funkcje interfejsu API REST FHIR dla interfejsu API platformy Azure dla platformy FHIR
W tym artykule omówimy niektóre niuanse interakcji RESTful interfejsu API platformy Azure for FHIR.
Tworzenie/aktualizowanie warunkowe
Interfejs API platformy Azure dla standardu FHIR obsługuje tworzenie, tworzenie warunkowe, aktualizowanie i aktualizowanie warunkowe zgodnie ze specyfikacją FHIR. Jednym z przydatnych nagłówków w tych scenariuszach jest nagłówek If-Match . Nagłówek If-Match jest używany i weryfikuje zaktualizowaną wersję przed wprowadzeniem aktualizacji. Jeśli wartość ETag nie jest zgodna z oczekiwaną ETagwartością , zostanie wygenerowany komunikat o błędzie 412 Warunek wstępny nie powiodło się.
Usuwanie i usuwanie warunkowe
Interfejs API platformy Azure dla platformy FHIR oferuje dwa typy usuwania. Istnieje również funkcja Delete, która jest również znana jako Usuwanie twarde i nietrwałe oraz Usuwanie warunkowe.
Usuwanie (twarde + usuwanie nietrwałe)
Usunięcie zdefiniowane przez specyfikację FHIR wymaga, aby po usunięciu zasobu kolejne odczyty specyficzne dla wersji zasobu zwróciły kod stanu HTTP 410. W związku z tym zasób nie został już znaleziony przez wyszukiwanie. Ponadto usługa Azure API for FHIR umożliwia pełne usunięcie (w tym całej historii) zasobu. Aby w pełni usunąć zasób, możesz przekazać ustawienia hardDelete parametru do wartości true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Jeśli nie przekażesz tego parametru lub ustawisz hardDelete wartość false, historyczne wersje zasobu będą nadal dostępne.
Uwaga
Jeśli chcesz usunąć historię, interfejs API platformy Azure for FHIR obsługuje operację niestandardową o nazwie $purge-history. Ta operacja umożliwia usunięcie historii z zasobu.
Usuwanie warunkowe
Warunkowe usuwanie umożliwia przekazanie kryteriów wyszukiwania w celu usunięcia zasobu. Domyślnie usuwanie warunkowe umożliwia usunięcie jednego elementu naraz. Można również określić _count parametr do usunięcia maksymalnie 100 elementów jednocześnie. Poniżej przedstawiono kilka przykładów użycia funkcji usuwania warunkowego.
Aby usunąć pojedynczy element przy użyciu funkcji Usuwania warunkowego, należy określić kryteria wyszukiwania zwracające pojedynczy element.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Możesz wykonać to samo wyszukiwanie, ale uwzględnić hardDelete=true , aby również usunąć całą historię.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Aby usunąć wiele zasobów, dołącz _count=100 parametr. Ten parametr usunie maksymalnie 100 zasobów spełniających kryteria wyszukiwania.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Odzyskiwanie usuniętych plików
Jeśli nie używasz parametru twardego usuwania, rekordy w interfejsie API platformy Azure for FHIR powinny nadal istnieć. Rekordy można znaleźć, wyszukując historię zasobu i wyszukując ostatnią wersję z danymi.
Jeśli jest znany identyfikator usuniętego zasobu, użyj następującego wzorca adresu URL:
<FHIR_URL>/<resource-type>/<resource-id>/_history
Na przykład: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Jeśli identyfikator zasobu nie jest znany, wykonaj wyszukiwanie historii dla całego typu zasobu:
<FHIR_URL>/<resource-type>/_history
Na przykład: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Po znalezieniu rekordu, który chcesz przywrócić, użyj PUT operacji , aby ponownie utworzyć zasób o tym samym identyfikatorze lub użyć POST operacji , aby utworzyć nowy zasób z tymi samymi informacjami.
Uwaga
Nie ma wygaśnięcia na podstawie czasu dla danych historii/usuwania nietrwałego. Jedynym sposobem usunięcia historii/nietrwałych danych jest operacja usuwania twardego lub historii przeczyszczania.
Poprawka i poprawka warunkowa
Patch to cenna operacja RESTful, gdy trzeba zaktualizować tylko część zasobu FHIR. Użycie poprawki umożliwia określenie elementów, które mają zostać zaktualizowane w zasobie bez konieczności aktualizowania całego rekordu. FHIR definiuje trzy sposoby stosowania poprawek zasobów: JSON Patch, XML Patch i FHIRPath Patch. Usługa FHIR obsługuje zarówno poprawkę JSON, jak i poprawkę FHIRPath wraz z warunkową poprawką JSON i warunkową poprawką FHIRPath (która umożliwia stosowanie poprawek zasobu na podstawie kryteriów wyszukiwania zamiast identyfikatora zasobu). Aby zapoznać się z przykładami, zapoznaj się z przykładowym plikiem REST poprawek FHIRPath i plikiem REST poprawek JSON dla każdego podejścia. Aby uzyskać dodatkowe informacje, zapoznaj się z dokumentacją HL7 dotyczącą operacji poprawek za pomocą platformy FHIR.
Uwaga
W przypadku używania w PATCH systemie STU3, a jeśli żądasz pakietu Historia, zasób Bundle.entry.request.method z poprawkami jest mapowany na PUT. Dzieje się tak, ponieważ funkcja STU3 nie zawiera definicji czasownika PATCH w zestawie wartości HTTPVerb.
Patch z poprawką FHIRPath
Ta metoda poprawki jest najbardziej zaawansowana, ponieważ wykorzystuje bibliotekę FHIRPath do wybierania elementu docelowego. Jednym z typowych scenariuszy jest użycie poprawki FHIRPath w celu zaktualizowania elementu na liście bez znajomości kolejności listy. Jeśli na przykład chcesz usunąć informacje telekomunikacyjne pacjenta bez znajomości indeksu, możesz użyć poniższego przykładu.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Typ zawartości: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Wszystkie operacje poprawki FHIRPath muszą mieć zestaw nagłówków application/fhir+json Content-Type. Poprawka FHIRPatch obsługuje operacje dodawania, wstawiania, usuwania, usuwania i przenoszenia. Operacje poprawek FHIRPatch można również łatwo zintegrować z pakietami. Aby uzyskać więcej przykładów, zapoznaj się z przykładowym plikiem REST poprawki FHIRPath.
Stosowanie poprawki w formacie JSON
Poprawka JSON w usłudze FHIR jest zgodna ze specyfikacją dobrze używaną zdefiniowaną przez Internet Engineering Task Force. Format ładunku nie używa zasobów FHIR, a zamiast tego używa dokumentu JSON wykorzystującego JSON-Pointers do zaznaczenia elementów. Poprawka JSON jest bardziej kompaktowa i ma operację testową, która umożliwia sprawdzenie, czy warunek jest spełniony przed wykonaniem poprawki. Jeśli na przykład chcesz ustawić pacjenta jako zmarłego tylko wtedy, gdy nie są one jeszcze oznaczone jako zmarłe, możesz użyć poniższego przykładu.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Typ zawartości: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Wszystkie operacje poprawek JSON muszą mieć zestaw nagłówków application/json-patch+json Content-Type. Poprawka JSON obsługuje operacje dodawania, usuwania, zastępowania, kopiowania, przenoszenia i testowania. Aby uzyskać więcej przykładów, zapoznaj się z przykładowym plikiem REST poprawek JSON.
Poprawka JSON w pakietach
Domyślnie poprawka JSON nie jest obsługiwana w zasobach pakietu. Dzieje się tak, ponieważ pakiet obsługuje tylko zasoby FHIR, a ładunek poprawki JSON nie jest zasobem FHIR. Aby obejść ten proces, użyjemy zasobów binarnych "application/json-patch+json" z typem zawartości i kodowaniem base64 ładunku JSON wewnątrz pakietu. Aby uzyskać informacje o tym obejściem, zapoznaj się z tym tematem na stronie FHIR Chat Zulip.
W poniższym przykładzie chcemy zmienić płeć pacjenta na kobietę. Pobraliśmy poprawkę [{"op":"replace","path":"/gender","value":"female"}] JSON i zakodowaliśmy ją do base64.
POST https://{FHIR-SERVICE-HOST-NAME}/
Typ zawartości: 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}"
}
}
]
}
Następne kroki
W tym artykule przedstawiono niektóre funkcje REST interfejsu API platformy Azure for FHIR. Następnie możesz dowiedzieć się więcej o kluczowych aspektach wyszukiwania zasobów w środowisku FHIR.
(FHIR®) jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7 .