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

FHIR® 仕様では、すべてのリソースに適用される一連の検索パラメーターを定義します。 さらに、FHIR は、特定のリソースに固有の多くの検索パラメーターを定義します。 ただし、FHIR 仕様で標準の検索パラメーターとして定義されていないリソース内の要素に対して検索することもできます。 この記事では、Azure Health Data Services の 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"
}

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

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

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

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

2. 場所 (参照型) の場合

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

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

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

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

検索パラメーターを更新するには、PUT を使用して検索パラメーターの新しいバージョンを作成します。 PUT要求の本文とPUT要求文字列のid フィールドに検索パラメーター 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 サービス データベースのインデックスを再作成する方法について説明します。 詳細については、以下を参照してください。