Definování vlastních parametrů vyhledávání pro rozhraní Azure API for FHIR

Článek
06/01/2023

Specifikace FHIR® (Fast Healthcare Interoperability Resources) definuje sadu parametrů vyhledávání pro všechny prostředky a parametry vyhledávání, které jsou specifické pro konkrétní prostředky. Existují však scénáře, ve kterých můžete chtít vyhledat prvek v prostředku, který není definován specifikací FHIR jako standardní parametr vyhledávání. Tento článek popisuje, jak můžete definovat vlastní parametry vyhledávání , které se mají použít v rozhraní Azure API for FHIR.

Poznámka

Pokaždé, když vytvoříte, aktualizujete nebo odstraníte parametr vyhledávání, budete muset spustit úlohu přeindexování , abyste povolili použití parametru vyhledávání v produkčním prostředí. Níže si ukážeme, jak můžete otestovat parametry vyhledávání před přeindexováním celého serveru FHIR.

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

Pokud chcete vytvořit nový parametr vyhledávání, musíte POSTSearchParameter prostředek použít k databázi. Následující příklad kódu ukazuje, jak do prostředku přidat parametr US Core Race SearchParameterPatient.

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

Poznámka

Nový parametr vyhledávání se zobrazí v příkazu capability serveru FHIR po odeslání parametru vyhledávání do databáze a přeindexování databáze. Zobrazení parametru SearchParameter v příkazu schopnosti je jediný způsob, jak zjistit, jestli je parametr vyhledávání na vašem serveru FHIR podporovaný. Pokud můžete najít parametr vyhledávání vyhledáním parametru vyhledávání, ale nevidíte ho v příkazu capability, musíte stále indexovat parametr vyhledávání. Před aktivací operace reindexování můžete postovat více parametrů vyhledávání.

Důležité prvky objektu SearchParameter:

url: Jedinečný klíč k popisu parametru vyhledávání. Mnoho organizací, jako je HL7, používá pro parametry hledání, které definují, standardní formát adresy URL, jak je znázorněno výše v parametru pro hledání rasy v USA – jádro.
code: Hodnota uložená v kódu je hodnota, kterou použijete při hledání. Ve výše uvedeném příkladu byste hledali pomocí , GET {FHIR_URL}/Patient?race=<code> abyste získali všechny pacienty konkrétní rasy. Kód musí být jedinečný pro prostředky, na které se vztahuje parametr vyhledávání.
base: Popisuje, na které prostředky se vztahuje vyhledávací parametr. Pokud se parametr vyhledávání vztahuje na všechny prostředky, můžete použít . V opačném případě můžete zobrazit Resourceseznam všech relevantních prostředků.
type: Popisuje datový typ parametru vyhledávání. Typ je omezený podporou rozhraní Azure API for FHIR. To znamená, že nemůžete definovat parametr vyhledávání typu Special nebo složeného parametru vyhledávání , pokud se nejedná o podporovanou kombinaci.
expression: Popisuje, jak vypočítat hodnotu pro hledání. Při popisu parametru vyhledávání musíte zahrnout výraz, i když to specifikace nevyžaduje. Je to proto, že potřebujete výraz nebo syntaxi xpath a rozhraní Azure API for FHIR syntaxi xpath ignoruje.

Test parametrů hledání

I když nemůžete parametry vyhledávání použít v produkčním prostředí, dokud nespustíte úlohu přeindexování, existuje několik způsobů, jak parametry vyhledávání otestovat před přeindexováním celé databáze.

Nejprve můžete otestovat nový parametr vyhledávání, abyste zjistili, jaké hodnoty se vrátí. Spuštěním následujícího příkazu pro konkrétní instanci prostředku (zadáním jejich ID) získáte zpět seznam párů hodnot s názvem parametru vyhledávání a hodnotou uloženou pro konkrétního pacienta. To bude zahrnovat všechny parametry vyhledávání pro daný prostředek a můžete procházet a vyhledat parametr vyhledávání, který jste vytvořili. Spuštěním tohoto příkazu se nezmění žádné chování na serveru FHIR.

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

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

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

Výsledek bude vypadat 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 váš parametr vyhledávání zobrazuje podle očekávání, můžete přeindexovat jeden prostředek a otestovat vyhledávání pomocí elementu . Nejprve přeindexujete jeden prostředek:

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

Spuštěním tohoto příkazu nastaví indexy pro všechny parametry vyhledávání pro konkrétní prostředek, který jste definovali pro daný typ prostředku. Tím dojde k aktualizaci serveru FHIR. Teď můžete hledat a nastavit hlavičku use partial indexs na hodnotu true, což znamená, že se vrátí výsledky, ve kterých má některý z prostředků indexovaný parametr vyhledávání, a to i v případě, že ne všechny prostředky tohoto typu ho indexují.

Když budeme pokračovat v našem příkladu výše, můžete indexovat jednoho pacienta, abyste povolili základní závod SearchParameterv USA:

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

A pak vyhledejte pacienty, kteří mají konkrétní rasu:

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

Po otestování a spokojenosti s tím, že parametr vyhledávání funguje podle očekávání, spusťte nebo naplánujte úlohu přeindexování, aby se parametry vyhledávání mohly použít na serveru FHIR pro produkční případy použití.

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 elementu textu požadavku a do PUT volání musíte zahrnout SearchParameter ID .PUTid

Poznámka

Pokud neznáte ID parametru hledání, můžete ho vyhledat. Při použití GET {{FHIR_URL}}/SearchParameter se vrátí všechny vlastní parametry hledání a můžete procházet parametr vyhledávání a najít požadovaný parametr hledání. Můžete také omezit vyhledávání podle názvu. V následujícím příkladu můžete název vyhledat pomocí USCoreRace: GET {{FHIR_URL}}/SearchParameter?name=USCoreRacepříkazu .

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 bude aktualizace SearchParameter a verze se bude zvyšovat.

Upozornění

Při aktualizaci parametrů searchParameters, které již byly indexovány ve vaší databázi, buďte opatrní. Změna chování existujícího parametru SearchParameter 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 hledání, použijte následující:

Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}

Upozornění

Při odstraňování parametrů SearchParameters, které již byly indexovány ve vaší databázi, buďte opatrní. Změna chování existujícího parametru SearchParameter 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 dozvěděli, jak vytvořit parametr vyhledávání. Dále se dozvíte, jak přeindexovat server FHIR.

Jak spustit úlohu přeindexování

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

Definování vlastních parametrů vyhledávání pro rozhraní Azure API for FHIR

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

Test parametrů hledání

Aktualizace parametru vyhledávání

Odstranění parametru vyhledávání

Další kroky

Další materiály