Definiowanie niestandardowych parametrów wyszukiwania dla interfejsu API platformy Azure for FHIR

Artykuł
06/01/2023

Specyfikacja Fast Healthcare Interoperability Resources (FHIR®) definiuje zestaw parametrów wyszukiwania dla wszystkich zasobów i parametrów wyszukiwania specyficznych dla zasobów. Istnieją jednak scenariusze, w których można wyszukać element w zasobie, który nie jest zdefiniowany przez specyfikację FHIR jako standardowy parametr wyszukiwania. W tym artykule opisano sposób definiowania własnych parametrów wyszukiwania do użycia w interfejsie API platformy Azure 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. Poniżej przedstawiono sposób testowania parametrów wyszukiwania przed ponownym indeksowaniem całego serwera FHIR.

Tworzenie nowego parametru wyszukiwania

Aby utworzyć nowy parametr wyszukiwania, zasób POSTSearchParameter 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 pojawi się w instrukcji capability serwera FHIR po opublikowaniu parametru wyszukiwania do bazy 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, wyszukując parametr wyszukiwania, ale nie można go wyświetlić w instrukcji capability, nadal musisz indeksować parametr wyszukiwania. Przed wyzwoleniem operacji ponownego indeksowania można opublikować wiele parametrów wyszukiwania.

Ważne elementy elementu :SearchParameter

url: unikatowy klucz do opisania parametru wyszukiwania. Wiele organizacji, takich jak HL7, używa standardowego formatu adresu URL dla zdefiniowanych parametrów wyszukiwania, jak pokazano powyżej w parametrze wyszukiwania wyścigów US Core.
kod: wartość przechowywana w kodzie jest używana podczas wyszukiwania. W powyższym przykładzie należy wyszukać polecenie , GET {FHIR_URL}/Patient?race=<code> aby uzyskać wszystkich pacjentów z konkretnej rasy. Kod musi być unikatowy dla zasobów, do których ma zastosowanie parametr wyszukiwania.
base: opisuje, które zasoby mają zastosowanie do parametru wyszukiwania. Jeśli parametr wyszukiwania ma zastosowanie do wszystkich zasobów, możesz użyć Resourcepolecenia ; 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 for FHIR. Oznacza to, że nie można zdefiniować parametru wyszukiwania typu Special lub zdefiniować parametr wyszukiwania złożonego , 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 do momentu uruchomienia zadania ponownego indeksowania, istnieje kilka sposobów testowania parametrów wyszukiwania przed ponownym indeksowaniem całej bazy danych.

Najpierw możesz przetestować nowy parametr wyszukiwania, aby zobaczyć, jakie wartości zostaną zwrócone. Uruchamiając poniższe polecenie względem określonego wystąpienia zasobu (przez wprowadzenie ich identyfikatora), odzyskasz listę par wartości z nazwą parametru wyszukiwania i wartością przechowywaną dla konkretnego pacjenta. Obejmuje to wszystkie parametry wyszukiwania zasobu i można przewijać w celu znalezienia utworzonego parametru 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 dla pacjenta:

GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

Wynik będzie 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 indeksować pojedynczy zasób, aby przetestować wyszukiwanie za pomocą elementu. Najpierw zindeksujesz pojedynczy zasób:

POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

W tym celu ustawia indeksy 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 częściowych indeksów na wartość true, co oznacza, że zwróci wyniki, w których dowolny z zasobów ma indeksowany parametr wyszukiwania, nawet jeśli nie wszystkie zasoby tego typu mają indeksowane.

Kontynuując nasz przykład powyżej, możesz zaindeksować jednego pacjenta, aby włączyć wyścig US Core Race SearchParameter:

POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex

A 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 przetestowaniu i 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 parametru wyszukiwania 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 zostanie zaktualizowany SearchParameter , a wersja będzie zwiększana.

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

Zachowaj 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.

Jak uruchomić zadanie ponownego indeksowania

FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7 .

Definiowanie niestandardowych parametrów wyszukiwania dla interfejsu API platformy Azure for FHIR

Tworzenie nowego parametru wyszukiwania

Testowanie parametrów wyszukiwania

Aktualizowanie parametru wyszukiwania

Usuwanie parametru wyszukiwania

Następne kroki

Dodatkowe zasoby