Definování vlastních parametrů hledání

Článek
10/16/2024

Specifikace FHIR® definuje sadu parametrů hledání, které se vztahují na všechny prostředky. Kromě toho FHIR definuje mnoho parametrů hledání, které jsou specifické pro určité prostředky. Můžete ale také chtít vyhledat prvek v prostředku, který není definován specifikací FHIR jako standardní vyhledávací parametr. Tento článek popisuje, jak můžete definovat vlastní parametry vyhledávání pro použití ve službě FHIR ve službě Azure Health Data Services.

Poznámka:

Pokaždé, když vytvoříte, aktualizujete nebo odstraníte parametr vyhledávání, budete muset spustit úlohu přeindexování, abyste povolili parametr vyhledávání pro živý produkční prostředí. Před přeindexováním celé databáze služby FHIR si ukážeme, jak můžete testovat parametry hledání.

Vytvoření nového parametru vyhledávání

Pokud chcete vytvořit nový vyhledávací parametr, musíte prostředek do POST SearchParameter databáze služby FHIR.

POST {{FHIR_URL}}/SearchParameter

Následující příklady ukazují vytvoření nového vlastního parametru vyhledávání.

Vytvoření nového vyhledávacího parametru na definici v průvodci implementací

Následující příklad kódu ukazuje, jak přidat parametr vyhledávání US Core Race do Patient typu prostředku v databázi služby 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"
}

Vytvoření nového vyhledávacího parametru pro atributy prostředků s odkazovým typem

Následující příklad kódu ukazuje, jak vytvořit vlastní vyhledávací parametr pro vyhledávání prostředků DrugDispense na základě umístění, kde byly vydány. Toto je příklad přidání vlastního vyhledávacího parametru pro typ odkazu.

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

Poznámka:

Nový parametr vyhledávání se zobrazí v příkazu capability služby FHIR po POST parametru vyhledávání do databáze a přeindexování databáze. SearchParameter Zobrazení příkazu capability je jediným způsobem, jak zjistit, jestli je ve službě FHIR podporovaný parametr vyhledávání. Pokud příkaz capability nenajdete SearchParameter , budete muset databázi přeindexovat, aby se aktivoval parametr vyhledávání. Před aktivací operace přeindexování můžete POST provést více parametrů hledání.

Mezi důležité prvky SearchParameter prostředku patří:

url: Jedinečný klíč pro popis parametru vyhledávání. Organizace, jako je HL7, používají standardní formát adresy URL pro parametry hledání, které definují, jak je znázorněno výše v parametru hledání US Core Race.
code: Hodnota uložená v elementu kódu je název použitý pro parametr vyhledávání, pokud je součástí volání rozhraní API. V předchozím příkladu s rozšířením "US Core Race" byste hledali, kde GET {{FHIR_URL}}/Patient?race=<code> <code> je v sadě hodnot ze zadaného systému kódování. Toto volání by načetlo všechny pacienty určitého závodu.
base: Popisuje, na které typy prostředků se parametr vyhledávání vztahuje. Pokud se vyhledávací parametr vztahuje na všechny prostředky, můžete použít Resource; jinak můžete zobrazit seznam všech relevantních typů prostředků.
target: Popisuje, které typy prostředků odpovídají parametru vyhledávání.
type: Popisuje datový typ pro parametr vyhledávání. Typ je omezen podporou datových typů ve službě FHIR. To znamená, že nemůžete definovat vyhledávací parametr typu Special nebo definovat složený vyhledávací parametr , pokud se nejedná o podporovanou kombinaci.
expression: Popisuje, jak vypočítat hodnotu hledání. Při popisu vyhledávacího parametru musíte výraz zahrnout, i když to specifikace nevyžaduje. Důvodem je to, že potřebujete výraz nebo syntaxi xpath a služba FHIR ignoruje syntaxi xpath.

Testování nových parametrů hledání

I když nové parametry hledání nemůžete použít v produkčním prostředí, dokud nespustíte úlohu přeindexování, existují způsoby, jak otestovat vlastní parametry hledání před opětovným indexováním celé databáze.

Nejprve můžete otestovat nový parametr vyhledávání a zjistit, jaké hodnoty se vrátí. Spuštěním následujícího příkazu pro konkrétní instanci prostředku (zadáním ID prostředku) získáte seznam párů hodnot s názvem parametru vyhledávání a hodnotou uloženou v odpovídajícím prvku. Tento seznam obsahuje všechny parametry hledání prostředku. Můžete procházet a najít parametr vyhledávání, který jste vytvořili. Spuštěním tohoto příkazu se nezmění žádné chování ve vaší službě FHIR.

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

Pokud například chcete najít všechny parametry hledání pro pacienta:

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

Výsledek vypadá takto:

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

Jakmile uvidíte, že se parametr vyhledávání zobrazuje podle očekávání, můžete znovu indexovat jeden prostředek a otestovat vyhledávání pomocí nového parametru vyhledávání. Pokud chcete přeindexovat jeden prostředek, použijte následující příkaz.

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

Spuštění tohoto POST volání nastaví indexy pro všechny parametry hledání definované pro instanci prostředku zadanou v požadavku. Toto volání provede změnu databáze služby FHIR. Teď můžete vyhledat a nastavit hlavičku x-ms-use-partial-indices true, která způsobí, že služba FHIR vrátí výsledky pro všechny prostředky, které mají indexovaný parametr vyhledávání, i když ne všechny instance prostředků tohoto typu mají indexované.

Pokračujte v našem příkladu a mohli byste indexovat jednoho pacienta, aby bylo možné:SearchParameter

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

A pak proveďte testování hledání:

Pro pacienta podle závodu:

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

Pro umístění (typ odkazu)

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

Po otestování nového vyhledávacího parametru a potvrzení, že funguje podle očekávání, spusťte nebo naplánujte úlohu přeindexování, aby se nové parametry hledání mohly použít v živém produkčním prostředí.

Informace o tom, jak přeindexovat databázi služby FHIR, najdete v tématu Spuštění úlohy přeindexování.

Aktualizace parametru vyhledávání

Pokud chcete aktualizovat parametr vyhledávání, použijte PUT k vytvoření nové verze parametru vyhledávání. Do pole v textu PUT požadavku a řetězci požadavku musíte zahrnout ID id parametru PUT vyhledávání.

Poznámka:

Pokud neznáte ID parametru hledání, můžete ho vyhledat pomocí GET {{FHIR_URL}}/SearchParameter. Tím se vrátí všechny vlastní a standardní parametry hledání. Projděte si seznam a vyhledejte parametr hledání, který potřebujete. Vyhledávání můžete také omezit podle názvu. Jak je znázorněno v následujícím příkladu požadavku, název instance vlastního SearchParameter prostředku je USCoreRace. Tento SearchParameter prostředek můžete vyhledat pomocí názvu .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"
}

Výsledkem výše uvedeného požadavku bude aktualizovaný SearchParameter prostředek.

Upozorňující

Při aktualizaci parametrů hledání buďte opatrní. Změna existujícího parametru vyhledávání může mít vliv na očekávané chování. Doporučujeme okamžitě spustit úlohu přeindexování.

Odstranění parametru vyhledávání

Pokud potřebujete odstranit parametr vyhledávání, použijte následující příkaz.

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

Upozorňující

Při odstraňování parametrů hledání buďte opatrní. Odstranění existujícího vyhledávacího parametru může mít vliv na očekávané chování. Doporučujeme okamžitě spustit úlohu přeindexování.

Další kroky

V tomto článku jste se naučili vytvořit vlastní parametr vyhledávání. Dále se dozvíte, jak přeindexovat databázi služby FHIR. Další informace najdete v tématu

Spuštění úlohy přeindexování

Poznámka:

FHIR® je registrovaná ochranná známka HL7 a používá se s povolením HL7.

Sdílet prostřednictvím

Definování vlastních parametrů hledání

Vytvoření nového parametru vyhledávání

Vytvoření nového vyhledávacího parametru na definici v průvodci implementací

Vytvoření nového vyhledávacího parametru pro atributy prostředků s odkazovým typem

Testování nových parametrů hledání

Aktualizace parametru vyhledávání

Odstranění parametru vyhledávání

Další kroky

Váš názor

Další materiály