Definiowanie niestandardowych parametrów wyszukiwania

Specyfikacja FHIR® definiuje zestaw parametrów wyszukiwania, które mają zastosowanie do wszystkich zasobów. Ponadto można zdefiniować niestandardowe parametry wyszukiwania specyficzne dla niektórych zasobów. Parametry wyszukiwania niestandardowego umożliwiają wyszukiwanie elementu w zasobie, który nie jest zdefiniowany przez specyfikację FHIR jako standardowy parametr wyszukiwania. W tym artykule opisano sposób definiowania własnych niestandardowych parametrów wyszukiwania do użycia w usłudze FHIR w usługach Azure Health Data Services.

Uwaga

Za każdym razem, gdy tworzysz, aktualizujesz lub usuwasz parametr wyszukiwania, musisz uruchomić zadanie ponownego indeksowania , aby zaakceptować zmiany. Aby wyświetlić stan parametrów wyszukiwania, udostępniono punkt końcowy interfejsu API $status. Jeśli stan parametru wyszukiwania to Pending, wskazuje, że parametr wyszukiwania musi zostać ponownie zindeksowany.

Tworzenie nowego parametru wyszukiwania

Aby utworzyć nowy parametr wyszukiwania, POSTSearchParameter dodaj zasób do bazy danych usługi FHIR.

POST {{FHIR_URL}}/SearchParameter

W poniższych przykładach pokazano tworzenie nowego niestandardowego parametru wyszukiwania.

Utwórz nowy parametr wyszukiwania dla każdej definicji w Przewodniku implementacji

Poniższy przykład kodu pokazuje, jak dodać parametr wyszukiwania US Core Race do Patient typu zasobu w bazie danych usługi FHIR.

{
  "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"
}

Tworzenie nowego parametru wyszukiwania dla atrybutów zasobu z typem referencyjnym

Poniższy przykład kodu pokazuje, jak utworzyć niestandardowy parametr wyszukiwania do wyszukiwania zasobów MedicationDispense na podstawie lokalizacji, w której zostały wydane. W tym przykładzie pokazano, jak dodać niestandardowy parametr wyszukiwania dla typu odwołania.

{
 "resourceType": "SearchParameter",
  "id": "a3c28d46-fd06-49ca-aea7-5f9314ef0497",
  "url": "{{An absolute URI that is used to identify this search parameter}}",
  "version": "1.0",
  "name": "MedicationDispenseLocationSearchParameter",
  "status": "active",
  "description": "Search parameter for MedicationDispense by location",
  "code": "location",
  "base": ["MedicationDispense"],
  "target": ["Location"],
  "type": "reference",
  "expression": "MedicationDispense.location"
}

Uwaga

Nowy parametr wyszukiwania pojawia się w deklaracji możliwości usługi FHIR po POST dodaniu parametru wyszukiwania do bazy danych oraz ponownym zindeksowaniu bazy danych. Wyświetlenie elementu SearchParameter w deklaracji możliwości jest jedynym sposobem, aby stwierdzić, czy parametr wyszukiwania jest obsługiwany w usłudze FHIR. Jeśli nie możesz znaleźć elementu SearchParameter w deklaracji możliwości, wciąż musisz ponownie zindeksować bazę danych, aby aktywować parametr wyszukiwania. Można POST skonfigurować wiele parametrów wyszukiwania przed uruchomieniem operacji ponownego indeksowania.

Ważne elementy SearchParameter zasobu to:

url: unikatowy klucz opisujący parametr wyszukiwania. Organizacje, takie jak HL7, używają standardowego formatu adresu URL dla zdefiniowanych parametrów wyszukiwania, jak pokazano wcześniej w parametrze wyszukiwania US Core Race.
code: wartość przechowywana w elemecie kodu jest nazwą używaną dla parametru wyszukiwania, gdy jest uwzględniona w wywołaniu interfejsu API. W poprzednim przykładzie z rozszerzeniem „US Core Race” wyszukujesz za pomocą GET {{FHIR_URL}}/Patient?race=<code>, gdzie <code> znajduje się w zestawie wartości z określonego systemu kodowania. To wywołanie pobiera wszystkich pacjentów z określonej rasy.
base: opisuje typy zasobów, do których ma zastosowanie parametr wyszukiwania. Jeśli parametr wyszukiwania ma zastosowanie do wszystkich zasobów, użyj polecenia Resource; w przeciwnym razie wyświetl listę wszystkich odpowiednich typów zasobów.
target: opisuje typy zasobów, do których pasuje parametr wyszukiwania.
type: opisuje typ danych dla parametru wyszukiwania. Typ jest ograniczony przez obsługę typów danych w usłudze FHIR. To ograniczenie oznacza, że nie można zdefiniować parametru wyszukiwania typu Special ani zdefiniować złożonego parametru wyszukiwania , chyba że jest to obsługiwana kombinacja.
expression: Opisuje sposób obliczania wartości wyszukiwania. Podczas opisywania parametru wyszukiwania należy uwzględnić wyrażenie, mimo że specyfikacja tego nie wymaga. To wymaganie istnieje, ponieważ potrzebne jest wyrażenie lub składnia xpath, a usługa FHIR ignoruje składnię xpath.

Testowanie nowych parametrów wyszukiwania

Chociaż nie można używać nowych parametrów wyszukiwania w środowisku produkcyjnym, dopóki nie uruchomisz zadania ponownego indeksowania, możesz przetestować parametry wyszukiwania niestandardowego przed ponownym indeksowaniem całej bazy danych.

Najpierw przetestuj nowy parametr wyszukiwania, aby zobaczyć, jakie wartości zwraca. Uruchamiając następujące polecenie względem określonego wystąpienia zasobu (podając identyfikator zasobu), należy wrócić do listy par wartości z nazwą parametru wyszukiwania i wartością przechowywaną w odpowiednim elemenie. Ta lista zawiera wszystkie parametry wyszukiwania zasobu. Możesz przewinąć, aby znaleźć utworzony parametr wyszukiwania. Uruchomienie tego polecenia nie zmienia żadnego zachowania w usłudze FHIR.

Uwaga

Za każdym razem, gdy tworzysz, aktualizujesz lub usuwasz parametr wyszukiwania, musisz uruchomić zadanie ponownego indeksowania , aby zaakceptować zmiany. Aby wyświetlić stan parametrów wyszukiwania, zostanie udostępniony punkt końcowy interfejsu API ($status). Jeśli parametr wyszukiwania jest w stanie Oczekiwanie, jest to dobra wskazówka, że wymaga ponownego zindeksowania.

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

Aby na przykład znaleźć wszystkie parametry wyszukiwania pacjenta:

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 zaindeksować pojedynczy zasób, aby przetestować wyszukiwanie przy użyciu nowego parametru wyszukiwania. Aby ponownie indeksować pojedynczy zasób, użyj następującego polecenia.

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

Wykonanie tego wywołania POST ustawia indeksy dla dowolnych parametrów wyszukiwania zdefiniowanych dla instancji zasobu określonej w żądaniu. To wywołanie powoduje zmianę bazy danych usługi FHIR. Teraz możesz wyszukać i ustawić nagłówek x-ms-use-partial-indices na true. To ustawienie powoduje, że usługa FHIR zwraca wyniki dla wszystkich zasobów, które mają zaindeksowany ten parametr wyszukiwania, nawet jeśli nie wszystkie instancje zasobów tego typu mają go zaindeksowanego.

Kontynuując nasz przykład, możesz zindeksować jednego pacjenta, aby włączyć SearchParameter:

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

Następnie wykonaj testowe wyszukiwania:

Dla pacjenta według rasy:

GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true

Dla lokalizacji (typ odwołania)

{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Po przetestowaniu nowego parametru wyszukiwania i upewnieniu się, że działa zgodnie z oczekiwaniami, uruchom lub zaplanuj ponowne indeksowanie zadania, aby nowe parametry wyszukiwania mogły być używane w środowisku produkcyjnym na żywo.

Aby uzyskać informacje na temat ponownego indeksowania bazy danych usługi FHIR, zobacz Uruchamianie zadania ponownego indeksowania.

Aktualizowanie parametru wyszukiwania

Aby zaktualizować parametr wyszukiwania, użyj polecenia PUT , aby utworzyć nową wersję parametru wyszukiwania. Należy uwzględnić identyfikator parametru wyszukiwania w polu id w treści żądania PUT oraz w ciągu żądania PUT.

Uwaga

Jeśli nie znasz identyfikatora parametru wyszukiwania, możesz go wyszukać przy użyciu polecenia GET {{FHIR_URL}}/SearchParameter. To żądanie zwraca wszystkie standardowe i niestandardowe parametry wyszukiwania. Możesz przewinąć listę, aby znaleźć potrzebny parametr wyszukiwania. Możesz również ograniczyć wyszukiwanie według nazwy. Jak pokazano w poniższym przykładowym żądaniu, nazwa wystąpienia zasobu niestandardowego SearchParameter to USCoreRace. Możesz wyszukać ten SearchParameter zasób według nazwy przy użyciu polecenia 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"
}

Wynikiem powyższego żądania jest zaktualizowany SearchParameter zasób.

Aby uniknąć zakłóceń podczas ponownego indeksowania istniejącego niestandardowego parametru wyszukiwania, rozważ utworzenie nowego niestandardowego parametru wyszukiwania. Upewnij się, że wartości podstawowe, kodu i adresu URL skojarzone z nowym parametrem wyszukiwania są unikatowe. Duplikowanie tych pól może prowadzić do nieokreślonego zachowania podczas ponownego indeksowania.

Ostrzeżenie

Podczas aktualizowania parametrów wyszukiwania należy zachować ostrożność. Zmiana istniejącego parametru wyszukiwania może mieć wpływ na oczekiwane zachowanie. Natychmiast uruchom zadanie ponownego indeksowania. Uwaga: częste zmiany niestandardowych parametrów wyszukiwania w wystąpieniach produkcyjnych mogą zakłócać zapytania. Starannie zaplanuj takie zmiany, aby uniknąć potencjalnych problemów.

Usuwanie parametru wyszukiwania

Aby usunąć parametr wyszukiwania, użyj następującego żądania.

Uwaga

Za każdym razem, gdy usuniesz parametr wyszukiwania, musisz uruchomić zadanie ponownego indeksowania , aby zaakceptować zmiany. Aby wyświetlić stan parametrów wyszukiwania, zostanie udostępniony punkt końcowy interfejsu API ($status). Jeśli parametr wyszukiwania ma stan PendingDelete lub PendingHardDelete, upewnij się, że uruchomisz ponowne indeksowanie.

DELETE {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

Następne kroki

W tym artykule przedstawiono sposób tworzenia niestandardowego parametru wyszukiwania. Następnie możesz dowiedzieć się, jak ponownie indeksować bazę danych usługi FHIR.

Jak uruchomić zadanie ponownego indeksowania

Uwaga

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

Opinia

Czy ta strona była pomocna?

Last updated on 2026-07-07

Definiowanie niestandardowych parametrów wyszukiwania

Tworzenie nowego parametru wyszukiwania

Utwórz nowy parametr wyszukiwania dla każdej definicji w Przewodniku implementacji

Tworzenie nowego parametru wyszukiwania dla atrybutów zasobu z typem referencyjnym

Testowanie nowych parametrów wyszukiwania

Aktualizowanie parametru wyszukiwania

Usuwanie parametru wyszukiwania

Następne kroki

Opinia

Dodatkowe zasoby