Udostępnij za pośrednictwem

Definiowanie niestandardowych parametrów wyszukiwania

  • Artykuł

Specyfikacja FHIR® definiuje zestaw parametrów wyszukiwania, które mają zastosowanie do wszystkich zasobów. Ponadto funkcja FHIR definiuje wiele parametrów wyszukiwania specyficznych dla niektórych zasobów. Można jednak również 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 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 włączyć parametr wyszukiwania dla produkcji na żywo. Przedstawimy sposób testowania parametrów wyszukiwania przed ponownym indeksowaniem całej bazy danych usługi FHIR.

Tworzenie nowego parametru wyszukiwania

Aby utworzyć nowy parametr wyszukiwania, musisz POST SearchParameter zasób do bazy danych usługi FHIR.

POST {{FHIR_URL}}/SearchParameter

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

Tworzenie nowego parametru wyszukiwania na definicję 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

W poniższym przykładzie kodu pokazano, jak utworzyć niestandardowy parametr wyszukiwania w celu wyszukania zasobów LekDispense na podstawie lokalizacji, w której zostały one wyzwane. Jest to przykład dodawania niestandardowego parametru 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 zostanie wyświetlony w instrukcji capability usługi FHIR po POST parametrze wyszukiwania do bazy danych i ponownym indeksie bazy danych. SearchParameter Wyświetlanie w instrukcji capability instrukcji jest jedynym sposobem, aby określić, czy parametr wyszukiwania jest obsługiwany w usłudze FHIR. Jeśli nie możesz znaleźć SearchParameter elementu w instrukcji capability, nadal musisz ponownie zindeksować bazę danych, aby aktywować parametr wyszukiwania. Przed wyzwoleniem operacji ponownego indeksowania można POST uzyskać wiele parametrów wyszukiwania.

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 powyżej 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" należy wyszukać GET {{FHIR_URL}}/Patient?race=<code> , gdzie <code> znajduje się w wartości ustawionej z określonego systemu kodowania. To wywołanie spowoduje pobranie wszystkich pacjentów z określonego wyścigu.

  • base: opisuje typy zasobów, do których 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 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. 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.

  • expression: 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 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, istnieją sposoby testowania niestandardowych parametrów 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 (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 spowoduje zmiany żadnego zachowania w usłudze FHIR.

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

Uruchomienie tego POST wywołania powoduje ustawienie indeksów dla wszystkich parametrów wyszukiwania zdefiniowanych dla wystąpienia zasobu określonego w żądaniu. To wywołanie powoduje zmianę bazy danych usługi FHIR. Teraz możesz wyszukać i ustawić x-ms-use-partial-indices nagłówek na true, co powoduje, że usługa FHIR zwraca wyniki dla dowolnych zasobów, które mają indeksowany parametr wyszukiwania, nawet jeśli nie wszystkie wystąpienia zasobów tego typu mają indeksowane.

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

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

Następnie przetestuj wyszukiwania:

  1. Dla pacjenta według rasy:
GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
  1. W polu Lokalizacja (typ odwołania)
{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Po przetestowaniu nowego parametru wyszukiwania i potwierdzeniu, że działa zgodnie z oczekiwaniami, uruchom lub zaplanuj zadanie ponownego indeksu, 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 dołączyć identyfikator parametru wyszukiwania w polu w id treści PUT żądania i PUT ciąg żądania.

Uwaga

Jeśli nie znasz identyfikatora parametru wyszukiwania, możesz go wyszukać przy użyciu polecenia GET {{FHIR_URL}}/SearchParameter. Spowoduje to zwrócenie wszystkich niestandardowych i standardowych parametrów 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 przy użyciu nazwy .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 będzie zaktualizowany SearchParameter zasób.

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

Podczas usuwania parametrów wyszukiwania należy zachować ostrożność. Usunięcie istniejącego parametru wyszukiwania może mieć wpływ na oczekiwane zachowanie. Zalecamy natychmiastowe uruchomienie zadania ponownego indeksu.

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. Aby uzyskać więcej informacji, zobacz

Jak uruchomić zadanie ponownego indeksowania

Uwaga

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