Możliwości interfejsu API REST FHIR dla usługi Azure Health Data Services FHIR
W tym artykule omówimy niektóre niuanse interakcji RESTful usługi Azure Health Data Services FHIR (o nazwie FHIR).
Tworzenie/aktualizowanie warunkowe
Usługa 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 wyświetlony komunikat o błędzie 412 Niepowodzenie warunku wstępnego.
Usuwanie i usuwanie warunkowe
Usługa FHIR oferuje dwa typy usuwania. Istnieje funkcja Delete, która jest również znana jako Usuwanie twarde i usuwanie nietrwałe oraz Usuwanie warunkowe.
Usuń (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 jest już znajdowany podczas wyszukiwania. Ponadto usługa 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 parametrów do wartości true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Jeśli nie przekażesz tego parametru lub ustawisz wartość hardDelete false, historyczne wersje zasobu będą nadal dostępne.
Uwaga
Jeśli chcesz usunąć tylko historię, usługa FHIR obsługuje operację niestandardową o nazwie $purge-history. Ta operacja umożliwia usunięcie historii poza zasobem.
Usuwanie warunkowe
Usuwanie warunkowe umożliwia przekazanie kryteriów wyszukiwania w celu usunięcia zasobu. Domyślnie funkcja Usuwania warunkowego 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żywania funkcji usuwania warunkowego.
Aby usunąć pojedynczy element przy użyciu usuwania warunkowego, należy określić kryteria wyszukiwania, które zwracają 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 spowoduje usunięcie 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 usuwania twardego, rekordy w usłudze 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żyj POST operacji , aby utworzyć nowy zasób z tymi samymi informacjami.
Uwaga
Nie ma czasu wygaśnięcia danych historii/usuwania nietrwałego. Jedynym sposobem usunięcia danych historii/usunięcia nietrwałego jest operacja usuwania twardego lub historii przeczyszczania.
Pakiety wsadowe i transakcyjne
W środowisku FHIR pakiety mogą być traktowane jako kontener, który zawiera wiele zasobów. Pakiety wsadowe i transakcyjne umożliwiają użytkownikom przesyłanie zestawu akcji do wykonania na serwerze w ramach pojedynczego żądania/odpowiedzi HTTP. Akcje mogą być wykonywane niezależnie jako "partia" lub jako pojedyncza niepodzielna "transakcja", w której cały zestaw zmian powiedzie się lub zakończy się niepowodzeniem jako pojedyncza jednostka. Można przesyłać akcje dla wielu zasobów tego samego lub różnych typów, takie jak tworzenie, aktualizowanie lub usuwanie. Aby uzyskać więcej informacji, odwiedź stronę Pakiety FHIR.
Interakcja wsadowa lub transakcyjna pakietu z usługą FHIR jest wykonywana za pomocą polecenia HTTP POST pod podstawowym adresem 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"
}
}
}
]
}
W przypadku partii każdy wpis jest traktowany jako pojedyncza interakcja lub operacja. W przypadku pakietu transakcji wszystkie interakcje lub operacje kończą się powodzeniem lub niepowodzeniem. W przypadku partii lub pomyślnego pakietu transakcji odpowiedź zawiera jeden wpis dla każdego wpisu w żądaniu. W przypadku pakietu transakcji, które zakończyły się niepowodzeniem, usługa FHIR zwraca pojedynczą operacjęOutcome.
Uwaga
W przypadku pakietów wsadowych nie powinno istnieć współzależności między różnymi wpisami w pakiecie FHIR. Powodzenie lub niepowodzenie jednego wpisu nie powinno mieć wpływu na powodzenie lub niepowodzenie innego wpisu.
Przetwarzanie równoległe pakietu usługi Batch w publicznej wersji zapoznawczej
Obecnie pakiety usługi Batch i transakcji są wykonywane szeregowo w usłudze FHIR. Aby zwiększyć wydajność i przepływność, włączamy równoległe przetwarzanie pakietów wsadowych w publicznej wersji zapoznawczej.
Aby użyć możliwości równoległego przetwarzania pakietów wsadowych-
- Ustaw wartość "x-bundle-processing-logic" nagłówka na "parallel".
- Upewnij się, że w tym samym pakiecie nie ma nakładającego się identyfikatora zasobu, który wykonuje operacje DELETE, POST, PUT lub PATCH.
Ważne
Przetwarzanie równoległe pakietu jest obecnie dostępne w publicznej wersji zapoznawczej. Interfejsy API i zestawy SDK w wersji zapoznawczej są udostępniane bez umowy dotyczącej poziomu usług. Zalecamy, aby nie używać ich w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zapoznaj się z dodatkowymi warunkami użytkowania dla wersji zapoznawczych platformy Microsoft Azure
Stosowanie poprawek i stosowanie poprawki warunkowej
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. Środowisko FHIR definiuje trzy sposoby stosowania poprawek zasobów: poprawkę JSON, poprawkę XML i poprawkę FHIRPath. Usługa FHIR obsługuje zarówno poprawkę JSON, jak i poprawkę FHIRPath wraz z warunkową poprawką JSON i warunkową poprawką FHIRPath (umożliwiającą 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, przeczytaj dokumentację HL7 dotyczącą operacji poprawek za pomocą standardu FHIR.
Uwaga
W przypadku korzystania z funkcji PATCH STU3, a jeśli żądasz pakietu Historia, poprawiony Bundle.entry.request.method zasób jest mapowany na .PUT Dzieje się tak, ponieważ funkcja STU3 nie zawiera definicji zlecenia PATCH w ustawieniu wartości HTTPVerb.
Stosowanie poprawek za pomocą poprawki FHIRPath
Ta metoda stosowania poprawek jest najbardziej zaawansowana, ponieważ wykorzystuje metodę FHIRPath do wybierania elementu docelowego. Jednym z typowych scenariuszy jest użycie poprawki FHIRPath do zaktualizowania elementu na liście bez znajomości kolejności listy. Jeśli na przykład chcesz usunąć informacje telekomunikacyjne dotyczące domu 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 poprawek 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 poprawek za pomocą poprawki 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 wyboru 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 usługi FHIR. Następnie możesz dowiedzieć się więcej o kluczowych aspektach wyszukiwania zasobów w usłudze FHIR.
(FHIR®) jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7 .