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

Článek
10/04/2024

Důležité

Rozhraní Azure API for FHIR bude vyřazeno 30. září 2026. Postupujte podle strategií migrace a do tohoto data přejděte na službu FHIR® služby Azure Health Data Services. Vzhledem k vyřazení rozhraní Azure API for FHIR nebudou nová nasazení od 1. dubna 2025 povolena. Služba FHIR služby Azure Health Data Services je vyvinutá verze rozhraní Azure API for FHIR, která zákazníkům umožňuje spravovat služby FHIR, DICOM a MedTech s integrací do jiných služeb Azure.

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

Poznámka:

Pokaždé, když vytvoříte, aktualizujete nebo odstraníte vyhledávací parametr, budete muset spustit úlohu přeindexování, aby se parametr vyhledávání mohl používat v produkčním prostředí. Tento článek popisuje, jak můžete testovat parametry hledání před opětovnou indexováním celého serveru FHIR.

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

Pokud chcete vytvořit nový vyhledávací parametr, prostředek POST SearchParameter do databáze. Následující příklad kódu ukazuje, jak přidat US Core Race SearchParameter do Patient prostředku.

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 schopností serveru FHIR po odeslání 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 na vašem serveru FHIR podporovaný parametr vyhledávání. Pokud najdete vyhledávací parametr, ale v příkazu capability ho nevidíte, budete muset indexovat parametr vyhledávání. Před aktivací operace přeindexování můžete odeslat více parametrů hledání.

Mezi důležité prvky SearchParameter patří následující:

url: Jedinečný klíč pro popis parametru vyhledávání. Mnoho organizací, jako je HL7, používá standardní formát adresy URL pro parametry hledání, které definují, jak je uvedeno dříve v parametru vyhledávání závodu US Core.
code: Hodnota uložená v kódu je to, co používáte při vyhledávání. V předchozím příkladu byste hledali GET {FHIR_URL}/Patient?race=<code> všechny pacienty konkrétní rasy. Kód musí být jedinečný pro prostředek, na který se parametr vyhledávání vztahuje.
base: Popisuje, na který prostředek 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 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 vyhledávací parametr typu Special nebo definovat složený vyhledávací parametr , pokud se nejedná o podporovanou kombinaci.
výraz: 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 rozhraní Azure API for FHIR ignoruje syntaxi xpath.

Test parametrů hledání

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

Nejprve můžete otestovat nový vyhledávací parametr 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) získáte seznam párů hodnot s názvem parametru vyhledávání a hodnotou uloženou pro konkrétního pacienta. To zahrnuje všechny parametry hledání pro prostředek. Vrácený seznam 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í vašeho serveru FHIR.

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

Pokud chcete například najít všechny parametry hledání pro pacienta, použijte následující příkaz.

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 zjistíte, že se váš vyhledávací parametr zobrazuje podle očekávání, můžete znovu indexovat jeden prostředek a otestovat vyhledávání pomocí elementu. Nejprve znovu indexujete jeden prostředek:

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

Spuštěním tohoto příkazu nastavíte indexy pro všechny parametry hledání pro konkrétní prostředek, který jste definovali pro daný typ prostředku. Tím dojde k aktualizaci serveru FHIR. Teď můžete prohledávat a nastavit hlavičku částečných indexů na true, což znamená, že vrátí výsledky, ve kterých se indexuje některý z prostředků, které mají indexovaný parametr vyhledávání, i když ne všechny prostředky tohoto typu jsou indexované.

Pokračujte v našem příkladu, mohli byste indexovat jednoho pacienta, abyste povolili us Core Race SearchParameter následujícím způsobem.

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

Pak vyhledejte pacienty, kteří mají určitou rasu:

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

Až budete spokojeni s tím, že váš parametr vyhledávání funguje podle očekávání, spusťte nebo naplánujte úlohu přeindexování, aby se parametry hledání mohly použít na serveru FHIR pro případy použití v produkčním prostředí.

Aktualizace parametru vyhledávání

Pokud chcete aktualizovat parametr vyhledávání, použijte PUT k vytvoření nové verze parametru vyhledávání. Musíte zahrnout prvek SearchParameter ID id textu PUT požadavku a do PUT volání.

Poznámka:

Pokud neznáte ID parametru hledání, můžete ho vyhledat. Použití GET {{FHIR_URL}}/SearchParameter vrátí všechny vlastní parametry hledání a v seznamu můžete vyhledat parametr hledání, který potřebujete. Vyhledávání můžete také omezit podle názvu. V následujícím příkladu můžete vyhledat název pomocí 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"
}

Výsledek je aktualizovaný SearchParameter a verze se zvýší.

Upozorňující

Při aktualizaci parametrů SearchParameters, které už byly indexovány ve vaší databázi, buďte opatrní. Změna chování existujícího searchParameteru 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ů SearchParameters, které už jsou ve vaší databázi indexované, buďte opatrní. Změna chování existujícího searchParameteru 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.

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ů vyhledávání pro 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

Váš názor

Další materiály