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

[アーティクル]
03/18/2023

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

注意

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

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

新しい検索パラメーターを作成するには、FHIR サービスデータベースへのリソースが必要POSTSearchParameterです。

POST {{FHIR_URL}}/SearchParameter

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

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

次のコード例は、FHIR サービスデータベースのリソースの種類に US Core Race 検索パラメーターを追加する 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"
}

注意

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

リソースの重要な SearchParameter 要素:

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

Location (参照型) の場合:

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

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

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

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

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

注意

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

上記の要求の結果は、更新 SearchParameter されたリソースになります。

警告

検索パラメーターを更新するときは注意してください。既存の検索パラメーターを変更すると、予想される動作に影響する可能性があります。インデックス再作成ジョブをすぐに実行することをお勧めします。

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

検索パラメーターを削除する必要がある場合は、次を使用してください。

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

警告

検索パラメーターを削除する場合は注意してください。既存の検索パラメーターを削除すると、予想される動作に影響する可能性があります。インデックス再作成ジョブをすぐに実行することをお勧めします。

次のステップ

この記事では、カスタム検索パラメーターを作成する方法について説明しました。次に、FHIR サービスデータベースのインデックスを再作成する方法について説明します。詳細については、「

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

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

次の方法で共有