Azure API for FHIR のカスタム検索パラメーターの定義

Fast Healthcare Interoperability Resources (FHIR®) 仕様では、リソースに固有のすべてのリソースと検索パラメーターの検索パラメーターのセットを定義します。 ただし、FHIR 仕様で標準の検索パラメーターとして定義されていないリソース内の要素を検索するシナリオもあります。 この記事では、Azure API for FHIR で使用される独自の検索パラメーターを定義する方法について説明します。

新しい検索パラメーターを作成する

新しい検索パラメーターを作成するには、SearchParameter リソースをデータベースに POST します。 次のコード例は、Patient リソースに US Core Race SearchParameter を追加する方法を示しています。

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

SearchParameterの重要な要素は次のとおりです。

• url: 検索パラメーターを記述するための一意のキー。 HL7 などの多くの組織では、以前に US Core の競合検索パラメーターに示されているように、定義されている検索パラメーターに標準の URL 形式を使用します。

• code: code に格納されている値は、検索時に使用します。 前の例では、 GET {FHIR_URL}/Patient?race=<code> で検索して、特定のレースのすべての患者を取得します。 このコードは、検索パラメーターが適用されるリソースに対して一意である必要があります。

• base: 検索パラメーターが適用されるリソースについて説明します。 検索パラメーターがすべてのリソースに適用される場合は、Resource を使用できます。それ以外の場合は、関連するすべてのリソースのリストを指定できます。

• type: 検索パラメーターのデータ型について記述します。 型は、Azure API for FHIR のサポートによって制限されます。 つまり、サポートされている組み合わせでない限り、Special 型の検索パラメーターを定義したり、 composite 検索パラメーターを定義したりすることはできません 。

• expression: 検索の値を計算する方法について記述します。 検索パラメーターを記述する場合は、仕様では必要ない式を含める必要があります。 これは、式または xpath 構文が必要であり、Azure API for FHIR では xpath 構文が無視されるためです。

検索パラメーターをテストする

インデックス再作成ジョブを実行するまで、運用環境で検索パラメーターを使用することはできませんが、データベース全体のインデックスを再作成する前に検索パラメーターをテストできます。

まず、新しい検索パラメーターをテストして、返される値を確認できます。 (ID を入力して) 特定のリソース インスタンスに対して次のコマンドを実行すると、検索パラメーター名と特定の患者に格納されている値を含む値ペアの一覧を取得します。 これには、リソースのすべての検索パラメーターが含まれます。 返されたリストをスクロールして、作成した検索パラメーターを見つけることができます。 このコマンドを実行しても、FHIR サーバーの動作は変更されません。

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

たとえば、患者のすべての検索パラメーターを検索するには、次を使用します。

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

結果は次のようになります。

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

検索パラメーターが期待どおりに表示されていることを確認したら、単一のリソースのインデックスを再作成し、要素を使用して検索をテストできます。 まず、1 つのリソースのインデックスを再作成します。

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

これを実行すると、そのリソースの種類に対して定義した特定のリソースの検索パラメーターのインデックスが設定されます。 これにより、FHIR サーバーが更新されます。 これで、use partial indexs ヘッダーを検索して true に設定できます。つまり、検索パラメーターがインデックス付けされているリソースのうち、その型のすべてのリソースにインデックスが作成されていない場合でも、結果が返されます。

この例を続けて、1 人の患者にインデックスを付けて、次のように US Core Race SearchParameter を有効にすることができます。

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

次に、特定の人種を持つ患者を検索します。

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

検索パラメーターが想定どおりに動作していることを確認したら、インデックス再作成ジョブを実行またはスケジュールして、検索パラメーターを実稼働ユース ケース用の FHIR サーバーで使用できるようにします。

検索パラメーターを更新する

検索パラメーターを更新するには、PUT を使用して検索パラメーターの新しいバージョンを作成します。 PUT 要求の本文の id 要素内と、PUT 呼び出し内に、SearchParameter ID を含める必要があります。

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

結果は更新された SearchParameter になり、バージョンがインクリメントされます。

検索パラメーターを削除する

検索パラメーターを削除する必要がある場合は、次のコマンドを使用します。

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

次のステップ

この記事では、検索パラメーターを作成する方法について説明しました。 次に、FHIR サーバーのインデックスを再作成する方法を学習できます。