Definiowanie niestandardowych parametrów wyszukiwania dla usługi Azure API for FHIR
Ważne
Usługa Azure API for FHIR zostanie wycofana 30 września 2026 r. Postępuj zgodnie ze strategiami migracji, aby przejść do usługi Azure Health Data Services FHIR® do tej daty. Ze względu na wycofanie usługi Azure API for FHIR nowe wdrożenia nie będą możliwe od 1 kwietnia 2025 r. Usługa FHIR usług Azure Health Data Services to rozwinięta wersja usługi Azure API for FHIR, która umożliwia klientom zarządzanie usługami FHIR, DICOM i MedTech z integracją z innymi usługami platformy Azure.
Specyfikacja Fast Healthcare Interoperability Resources (FHIR®) definiuje zestaw parametrów wyszukiwania dla wszystkich zasobów i parametrów wyszukiwania specyficznych dla zasobu. Istnieją jednak scenariusze, w których można wyszukać element w zasobie, który nie jest zdefiniowany jako standardowy parametr wyszukiwania według specyfikacji FHIR. W tym artykule opisano sposób definiowania własnych parametrów wyszukiwania, które mają być używane w interfejsie AZURE API for FHIR.
Uwaga
Za każdym razem, gdy tworzysz, aktualizujesz lub usuwasz parametr wyszukiwania, musisz uruchomić zadanie ponownego indeksowania, aby umożliwić użycie parametru wyszukiwania w środowisku produkcyjnym. W tym artykule opisano sposób testowania parametrów wyszukiwania przed ponownym indeksowaniem całego serwera FHIR.
Tworzenie nowego parametru wyszukiwania
Aby utworzyć nowy parametr wyszukiwania, należy POST SearchParameter zasób do bazy danych. W poniższym przykładzie kodu pokazano, jak dodać parametr US Core Race SearchParameter do Patient zasobu.
POST {{FHIR_URL}}/SearchParameter
{
"resourceType" : "SearchParameter",
"id" : "us-core-race",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "Returns patients with a race extension matching the specified code.",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
Uwaga
Nowy parametr wyszukiwania zostanie wyświetlony w instrukcji capability serwera FHIR po opublikowaniu parametru wyszukiwania w bazie danych i ponownego indeksowania bazy danych. SearchParameter Wyświetlanie instrukcji w instrukcji capability jest jedynym sposobem, aby sprawdzić, czy parametr wyszukiwania jest obsługiwany na serwerze FHIR. Jeśli możesz znaleźć parametr wyszukiwania, ale nie widzisz go w instrukcji capability, nadal musisz zaindeksować parametr wyszukiwania. Przed wyzwoleniem operacji ponownego indeksowania można opublikować wiele parametrów wyszukiwania.
Ważne elementy elementu SearchParameter obejmują następujące elementy.
url: unikatowy klucz opisujący parametr wyszukiwania. Wiele organizacji, takich jak HL7, używa standardowego formatu adresu URL dla zdefiniowanych parametrów wyszukiwania, jak pokazano wcześniej w parametrze wyszukiwania wyścigów US Core.
code: wartość przechowywana w kodzie jest używana podczas wyszukiwania. W poprzednim przykładzie należy wyszukać element ,
GET {FHIR_URL}/Patient?race=<code>aby uzyskać wszystkich pacjentów z konkretnej rasy. Kod musi być unikatowy dla zasobu, do których ma zastosowanie parametr wyszukiwania.base: opisuje zasób, do którego ma zastosowanie parametr wyszukiwania. Jeśli parametr wyszukiwania ma zastosowanie do wszystkich zasobów, możesz użyć polecenia
Resource; w przeciwnym razie możesz wyświetlić listę wszystkich odpowiednich zasobów.type: Opisuje typ danych dla parametru wyszukiwania. Typ jest ograniczony przez obsługę interfejsu API platformy Azure dla standardu FHIR. Oznacza to, że nie można zdefiniować parametru wyszukiwania typu Special ani zdefiniować złożonego parametru wyszukiwania, chyba że jest to obsługiwana kombinacja.
wyrażenie: opisuje sposób obliczania wartości wyszukiwania. Podczas opisywania parametru wyszukiwania należy uwzględnić wyrażenie, mimo że nie jest wymagane przez specyfikację. Jest to spowodowane tym, że potrzebne jest wyrażenie lub składnia xpath, a interfejs API platformy Azure for FHIR ignoruje składnię xpath.
Testowanie parametrów wyszukiwania
Chociaż nie można używać parametrów wyszukiwania w środowisku produkcyjnym, dopóki nie uruchomisz zadania ponownego indeksowania, możesz przetestować parametry wyszukiwania przed ponownym indeksowaniem całej bazy danych.
Najpierw możesz przetestować nowy parametr wyszukiwania, aby zobaczyć, jakie wartości są zwracane. Uruchamiając następujące polecenie względem określonego wystąpienia zasobu (przez wprowadzenie ich identyfikatora), uzyskasz listę par wartości z nazwą parametru wyszukiwania i wartością przechowywaną dla określonego pacjenta. Obejmuje to wszystkie parametry wyszukiwania zasobu. Możesz przewinąć zwróconą listę, aby znaleźć utworzony parametr wyszukiwania. Uruchomienie tego polecenia nie spowoduje zmiany żadnego zachowania na serwerze FHIR.
GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex
Aby na przykład znaleźć wszystkie parametry wyszukiwania pacjenta, użyj następującego polecenia.
GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex
Wynik wygląda następująco.
{
"resourceType": "Parameters",
"id": "8be24e78-b333-49da-a861-523491c3437a",
"meta": {
"versionId": "1"
},
"parameter": [
{
"name": "deceased",
"valueString": "http://hl7.org/fhir/special-values|false"
},
{
"name": "language",
"valueString": "urn:ietf:bcp:47|en-US"
},
{
"name": "race",
"valueString": "2028-9"
},
...
Gdy zobaczysz, że parametr wyszukiwania jest wyświetlany zgodnie z oczekiwaniami, możesz ponownie zindeksować pojedynczy zasób, aby przetestować wyszukiwanie za pomocą elementu . Najpierw ponownie zaindeksujesz pojedynczy zasób:
POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex
Uruchomienie tej funkcji powoduje ustawienie indeksów dla wszystkich parametrów wyszukiwania dla określonego zasobu zdefiniowanego dla tego typu zasobu. Spowoduje to aktualizację serwera FHIR. Teraz możesz wyszukać i ustawić użycie nagłówka indeksów częściowych na wartość true, co oznacza, że zwraca wyniki, w których dowolny z zasobów, które mają indeksowany parametr wyszukiwania, nawet jeśli nie wszystkie zasoby tego typu mają indeksowane.
Kontynuując nasz przykład, możesz zaindeksować jednego pacjenta, aby włączyć us Core Race SearchParameter w następujący sposób.
POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex
Następnie wyszukaj pacjentów, którzy mają określony wyścig:
GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
Po spełnieniu, że parametr wyszukiwania działa zgodnie z oczekiwaniami, uruchom lub zaplanuj zadanie ponownego indeksu, aby parametry wyszukiwania mogły być używane na serwerze FHIR na potrzeby przypadków użycia w środowisku produkcyjnym.
Aktualizowanie parametru wyszukiwania
Aby zaktualizować parametr wyszukiwania, użyj polecenia PUT , aby utworzyć nową wersję parametru wyszukiwania. Musisz uwzględnić SearchParameter ID element w id treści PUT żądania i wywołaniu PUT .
Uwaga
Jeśli nie znasz identyfikatora parametru wyszukiwania, możesz go wyszukać. Użycie GET {{FHIR_URL}}/SearchParameter spowoduje zwrócenie wszystkich niestandardowych parametrów wyszukiwania i przewinięcie listy w celu znalezienia potrzebnego parametru wyszukiwania. Możesz również ograniczyć wyszukiwanie według nazwy. W poniższym przykładzie możesz wyszukać nazwę przy użyciu polecenia USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRace.
PUT {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
{
"resourceType" : "SearchParameter",
"id" : "SearchParameter ID",
"url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
"version" : "3.1.1",
"name" : "USCoreRace",
"status" : "active",
"date" : "2019-05-21",
"publisher" : "US Realm Steering Committee",
"contact" : [
{
"telecom" : [
{
"system" : "other",
"value" : "http://www.healthit.gov/"
}
]
}
],
"description" : "New Description!",
"jurisdiction" : [
{
"coding" : [
{
"system" : "urn:iso:std:iso:3166",
"code" : "US",
"display" : "United States of America"
}
]
}
],
"code" : "race",
"base" : [
"Patient"
],
"type" : "token",
"expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}
Wynik jest zaktualizowany SearchParameter i zwiększa wersję.
Ostrzeżenie
Podczas aktualizowania parametrów SearchParameters, które zostały już indeksowane w bazie danych, należy zachować ostrożność. Zmiana zachowania istniejącej metody SearchParameter może mieć wpływ na oczekiwane zachowanie. Zalecamy natychmiastowe uruchomienie zadania ponownego indeksu.
Usuwanie parametru wyszukiwania
Jeśli musisz usunąć parametr wyszukiwania, użyj następującego polecenia.
Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}
Ostrzeżenie
Należy zachować ostrożność podczas usuwania parametrów wyszukiwania, które zostały już indeksowane w bazie danych. Zmiana zachowania istniejącej metody SearchParameter może mieć wpływ na oczekiwane zachowanie. Zalecamy natychmiastowe uruchomienie zadania ponownego indeksu.
Następne kroki
W tym artykule przedstawiono sposób tworzenia parametru wyszukiwania. Następnie dowiesz się, jak ponownie indeksować serwer FHIR.
Uwaga
FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7.