カスタム検索パラメーターの定義

[アーティクル]
10/16/2024

FHIR® 仕様では、すべてのリソースに適用される一連の検索パラメーターを定義します。さらに、FHIR は、特定のリソースに固有の多くの検索パラメーターを定義します。ただし、FHIR 仕様で標準の検索パラメーターとして定義されていないリソース内の要素に対して検索することもできます。この記事では、Azure Health Data Services の FHIR サービスで使用するために独自のカスタム検索パラメーターを定義する方法について説明します。

Note

検索パラメーターを作成、更新、または削除するたびに、 reindex ジョブを実行してライブ運用の検索パラメーターを有効にする必要があります。以下では、FHIR サービスデータベース全体のインデックスを再作成する前に、検索パラメーターをテストする方法について説明します。

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

新しい検索パラメーターを作成するには、SearchParameter リソースを FHIR サービスデータベースにPOSTする必要があります。

POST {{FHIR_URL}}/SearchParameter

次の例では、新しいカスタム検索パラメーターを作成する方法を示します。

実装ガイドの定義ごとに新しい検索パラメーターを作成する

次のコード例は、 US Core Race 検索パラメーター FHIR サービスデータベースの Patient リソースの種類に追加する方法を示しています。

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

参照型のリソース属性の新しい検索パラメーターを作成する

次のコード例は、カスタム検索パラメーターを作成して、割り当てられた場所に基づいて MedicationDispense リソースを検索する方法を示しています。参照型のカスタム検索パラメーターを追加する例を次に示します。

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

Note

新しい検索パラメーターは、検索パラメーターをデータベース にPOSTした後、FHIR サービスの capability ステートメントに表示されます。またデータベースのインデックスを再作成します。機能ステートメントで SearchParameter を表示することは、FHIR サービスで検索パラメーターがサポートされているかどうかを確認する唯一の方法です。 capability ステートメントで SearchParameter が見つからない場合でも、データベースのインデックスを再作成して検索パラメーターをアクティブ化する必要があります。インデックス再作成操作をトリガーする前に、複数の検索パラメーターを POST できます。

SearchParameter リソースの重要な要素は次のとおりです。

url: 検索パラメーターを記述する一意のキー。 HL7 などの組織は、上記の US Core Race 検索パラメーターに示すように、定義されている検索パラメーターに標準の URL 形式を使用します。
code: code 要素に格納されている値は、API 呼び出しに含まれるときに検索パラメーターに使用される名前です。前の例の "US Core Race" 拡張機能では、<code>が指定されたコーディングシステムから設定された値に含まれるGET {{FHIR_URL}}/Patient?race=<code>で検索します。この呼び出しは、特定のレースのすべての患者を取得します。
base: 検索パラメーターが適用されるリソースの種類について説明します。検索パラメーターがすべてのリソースに適用される場合は、 Resourceを使用できます。それ以外の場合は、関連するすべてのリソースの種類を一覧表示できます。
target: 検索パラメーターが一致するリソースの種類について説明します。
type: 検索パラメーターのデータ型について説明します。型は、FHIR サービスでのデータ型のサポートによって制限されます。つまり、サポートされている組み合わせでない限り、Special 型の検索パラメーターを定義したり、 composite 検索パラメーターを定義したりすることはできません。
expression: 検索の値を計算する方法について説明します。検索パラメーターを記述する場合は、仕様では必要ない式を含める必要があります。これは、式または xpath 構文が必要であり、FHIR サービスが xpath 構文を無視するためです。

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

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

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

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOURCE_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 つのリソースのインデックスを再作成して、新しい検索パラメーターを使用して検索をテストできます。 1 つのリソースのインデックスを再作成するには、次のコマンドを使用します。

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

この POST 呼び出しを実行すると、要求で指定されたリソースインスタンスに対して定義されているすべての検索パラメーターのインデックスが設定されます。この呼び出しは、FHIR サービスデータベースに変更を加えます。これで、 x-ms-use-partial-indices ヘッダーを検索して true に設定できるようになりました。これにより、その種類のすべてのリソースインスタンスにインデックスが作成されていない場合でも、検索パラメーターがインデックス付けされたリソースの結果が FHIR サービスによって返されます。

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

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

次に、検索をテストします。

レースによる患者の場合:

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

場所 (参照型) の場合

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

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

FHIR サービスデータベースのインデックスを再作成する方法については、「インデックス再作成ジョブの実行を参照してください。

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

検索パラメーターを更新するには、PUT を使用して検索パラメーターの新しいバージョンを作成します。 PUT要求の本文とPUT要求文字列のid フィールドに検索パラメーター ID を含める必要があります。

Note

検索パラメーターの ID がわからない場合は、 GET {{FHIR_URL}}/SearchParameterを使用して検索できます。これにより、すべてのカスタムおよび標準の検索パラメーターが返されます。一覧をスクロールして、必要な検索パラメーターを見つけることができます。検索を名前で制限することもできます。次の要求例に示すように、カスタム SearchParameter リソースインスタンスの名前は USCoreRace。 GET {{FHIR_URL}}/SearchParameter?name=USCoreRaceを使用して、名前でこのSearchParameter リソースを検索できます。

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 サービスデータベースのインデックスを再作成する方法について説明します。詳細については、「

インデックス再作成ジョブを実行する方法

Note

FHIR® は HL7 の登録商標であり、HL7 の許可を得て使用しています。

次の方法で共有

カスタム検索パラメーターの定義

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

実装ガイドの定義ごとに新しい検索パラメーターを作成する

参照型のリソース属性の新しい検索パラメーターを作成する

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

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

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

次のステップ

フィードバック

その他のリソース