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

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

重要

Azure API for FHIR は、2026 年 9 月 30 日に廃止されます。 移行戦略に従って、その日までに Azure Health Data Services FHIR® サービスに切り替えてください。 Azure API for FHIR が廃止されたため、2025 年 4 月 1 日以降、新しいデプロイは許可されません。 Azure Health Data Services FHIR サービスは、お客様が他の Azure サービスへの統合を使用して、FHIR、DICOM、および MedTech サービスを管理できるようにする、進化したバージョンの Azure API for FHIR です。

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

Note

検索パラメーターを作成、更新、または削除するたびに、インデックス再作成ジョブを実行して、検索パラメーターを運用環境で使用できるようにする必要があります。この記事では、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"
}

Note

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

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 を含める必要があります。

Note

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

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

警告

データベースで既にインデックスが作成されている SearchParameters を更新する場合は注意してください。既存の SearchParameter の動作を変更すると、期待される動作に影響を与える可能性があります。インデックス再作成ジョブをすぐに実行することをお勧めします。

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

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

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

警告

データベースで既にインデックスが作成されている SearchParameters を削除する場合は注意してください。既存の SearchParameter の動作を変更すると、期待される動作に影響を与える可能性があります。インデックス再作成ジョブをすぐに実行することをお勧めします。

次のステップ

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

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

Note

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

次の方法で共有

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

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

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

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

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

次のステップ

フィードバック

その他のリソース