次の方法で共有

Azure API for FHIR での検索の概要

  • [アーティクル]

重要

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 です。

高速ヘルスケア相互運用性リソース (FHIR) の仕様では、FHIR リソースの検索の基礎が定義されています。 この記事では、FHIR でのリソース検索について、いくつかの主要な側面について説明します。 FHIR リソースの検索の詳細については、HL7 FHIR 仕様の 検索 に関するページを参照してください。 この記事全体を通して、検索構文の例を示します。 各検索は FHIR サーバーに対して行います。通常、URL は https://<FHIRSERVERNAME>.azurewebsites.net です。 この例では、この URL にプレースホルダー {{FHIR_URL}} を使用します。

FHIR 検索は、特定のリソースの種類、指定されたコンパートメント、すべてのリソースに対して実行できます。 FHIR で検索を実行する最も簡単な方法は、GET 要求を使用する方法です。 たとえば、データベース内のすべての患者をプルする場合は、次の要求を使用できます。

GET {{FHIR_URL}}/Patient

POST を使用して検索することもできます。これは、クエリ文字列が長すぎる場合に便利です。 POST を使用して検索するには、検索パラメーターをフォーム本文として送信できます。 これにより、クエリ文字列では表示と理解が困難になる可能性がある、より長く複雑な一連のクエリ パラメーターが可能になります。

検索要求が成功すると、searchset 型の FHIR バンドル応答が返されます。 検索に失敗した場合は、OperationOutcome にエラーの詳細が表示され、検索が失敗した理由を理解するのに役立ちます。

次のセクションでは、検索に関連するさまざまな側面について説明します。 これらの詳細を確認したら、Azure API for FHIR で実行できる検索の例があるサンプル ページを参照してください。

検索パラメーター

検索を行う場合は、リソースのさまざまな属性に基づいて検索します。 これらの属性は検索パラメーターと呼ばれます。 各リソースには、定義された検索パラメーターのセットがあります。 検索パラメーターを正しく検索するには、データベースで検索パラメーターを定義してインデックスを作成する必要があります。

各検索パラメーターには、定義済みのデータ型があります。 さまざまなデータ型のサポートの概要を次に示します。

警告

現在、チェーン検索で Azure API for FHIR で _sort を使用する場合、問題があります。 詳細については、オープンソースの問題 #2344 を参照してください。 この問題は、2021 年 12 月のリリース中に解決される予定です。

検索パラメーターの種類 Azure API for FHIR Azure Health Data Services の FHIR サービス コメント
数値 はい はい
日付 はい あり
string はい はい
token はい はい
reference はい はい
複合 部分的 Partial サポートされている複合型の一覧については、この記事の後半で説明します。
数量 はい はい
uri はい はい
スペシャル いいえ いいえ

一般的な検索パラメーター

すべてのリソースに適用される一般的な検索パラメーターがあります。 それらを、Azure API for FHI でのサポートとともに以下に示しています。

一般的な検索パラメーター Azure API for FHIR Azure Health Data Services の FHIR サービス コメント
_id はい はい
_lastUpdated はい はい
_tag はい はい
_type はい はい
_security はい はい
_profile はい はい
_has Partial はい _has のサポートは、Azure API for FHIR の MVP と、Azure Cosmos DB によってサポートされる OSS バージョンにあります。 詳細については、以下のチェーンに関するセクションを参照してください。
_query いいえ いいえ
_filter いいえ いいえ
_list いいえ いいえ
_text いいえ いいえ
_content いいえ いいえ

リソース固有のパラメーター

Azure API for FHIR では、FHIR 仕様で定義されているほぼすべてのリソース固有の検索パラメーターがサポートされています。 サポートされない唯一の検索パラメーターは、次のリンクにあります。

次の要求を使用して、FHIR 機能ステートメントの検索パラメーターの現在のサポートを確認することもできます。

GET {{FHIR_URL}}/metadata

機能ステートメントで検索パラメーターを表示するには、CapabilityStatement.rest.resource.searchParam に移動して各リソースと CapabilityStatement.rest.searchParam の検索パラメーターを表示し、すべてのリソースの検索パラメーターを検索します。

Note

Azure API for FHIR では、FHIR 仕様で定義されていない検索パラメーターを自動的に作成またはインデックス付けしません。 ただし、独自 の検索パラメーターを定義するためのサポートが提供されています。

複合検索パラメーター

複合検索を使用すると、値ペアに対して検索できます。 たとえば、人物が身長 60 インチという測定値を検索する場合は、測定の 1 つのコンポーネントに高さのコードおよび 60 の値が含まれている必要があります。 観察結果には、値 60 と身長のコードに該当するエントリが、異なるコンポーネント セクションに含まれている可能性がありますが、体重 60 と身長 48 が格納された測定結果を取得したくはありません。

Azure API for FHIRでは、次の検索パラメーター型のペアがサポートされています。

  • 参照、トークン
  • トークン、日付
  • トークン、数字、数字
  • トークン、数量
  • トークン、文字列
  • トークン、トークン

詳細については、HL7 複合検索パラメーターに関するページを参照してください。

Note

複合検索パラメーターでは、FHIR 仕様に基づく修飾子はサポートされていません。

修飾子とプレフィックス

修飾子を使用すると、検索パラメーターを変更できます。 次に示されているのは、すべての FHIR 修飾子の概要と、Azure API for FHIR でのサポートです。

修飾子 Azure API for FHIR Azure Health Data Services の FHIR サービス コメント
:missing はい はい
:exact はい はい
:contains はい はい
text: はい はい
:type (reference) はい はい
:not はい はい
:below (uri) はい はい
:above (uri) はい はい
:in (token) いいえ いいえ
:below (token) いいえ いいえ
:above (token) いいえ いいえ
:not-in (token) いいえ いいえ

特定の順序 (数値、日付、数量) を持つ検索パラメーターの場合は、パラメーターのプレフィックスを使用すると、一致を見つけるのに役立ちます。 Azure API for FHIR では、すべてのプレフィックスがサポートされています。

検索結果のパラメーター

返されたリソースを管理するために、検索で使用できる検索結果パラメーターがあります。 各検索結果パラメーターの使い方の詳細については HL7 の Web サイトを参照してください。

検索結果のパラメーター Azure API for FHIR Azure Health Data Services の FHIR サービス コメント
_elements はい はい
_count はい はい _count は 1,000 リソースに制限されています。 1,000 より大きい値に設定すると、1,000 件だけが返され、バンドルで警告が返されます。
_include はい はい 含まれる項目は 100 に制限されています。 Azure Cosmos DB の PaaS および OSS の _include には、:iterate サポート (#2137) は含まれていません。
_revinclude はい はい 含まれる項目は 100 に制限されています。 Azure Cosmos DB の PaaS と OSS の_revincludeには、:iterate のサポート (#2137) が含まれていません。 また、不適切な要求 #1319 に対する正しくない状態コードがあります
_summary はい はい
_total 部分的 Partial _total=none および _total=accurate
_sort 部分的 Partial sort=_lastUpdated は、Azure API for FHIR と FHIR サービスでサポートされています。 2021 年 4 月 20 日以降に作成された Azure API for FHIR および OSS Azure Cosmos DB データベースでは、姓、生年月日、臨床日で並べ替えがサポートされています。
_contained いいえ いいえ
_containedType いいえ いいえ
_score いいえ 無効

Note

既定 _sort では、コードは昇順で並べ替えられます。 プレフィックス '-' を使用して、降順で並べ替えることができます。 さらに、FHIR サービスと Azure API for FHIR では、一度に 1 つのフィールドでのみ並べ替えることができます。

既定では、Azure API for FHIR は厳密な処理に設定されています。 これは、サーバーが不明なパラメーターまたはサポートされていないパラメーターを無視することを意味します。 厳密な処理を使用する場合は、Prefer ヘッダーを使用して handling=strict を設定できます。

チェーンおよびリバース チェーン検索

チェーン検索を使用すると、別のリソースによって参照されるリソースの検索パラメーターを使用して検索できます。 たとえば、患者の名前が Jane である結果を探す場合は、次のコマンドを使用します。

GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane

同様に、リバース チェーン検索を実行できます。 これにより、リソースを参照する他のリソースの条件を指定して、リソースを取得できます。 チェーン検索とリバース チェーン検索のその他の例については、FHIR 検索の例に関するページを参照してください。

Note

Azure API for FHIR と Azure Cosmos DB によってサポートされるオープン ソースでは、チェーン検索とリバース チェーン検索に必要な各サブクエリで返される項目が 1000 項目のみになるという制限があります。 見つかった項目が 1000 を超える場合は、次のエラー メッセージが表示されます。"チェーンされた式のサブクエリでは 1000 を超える結果を返すことができません。より限定的な条件を使用してください。" クエリを正常に実行するには、探している情報についてより具体的にする必要があります。

ページ区切り

前述のように、検索の結果はページを使ったバンドルになります。 既定では、検索では 1 ページあたり 10 件の結果が返されますが、_count を指定することでこれを増やしたり減らしたりできます。 バンドル内には、検索の現在の結果を含む自己リンクがあります。 追加の一致がある場合、バンドルには次へのリンクが含まれます。 次へのリンクを引き続き使用して、結果の後続のページを取得できます。 _count は 1,000 項目以下に制限されます。

バンドル内の次のリンクには、継続トークンのサイズ制限が 3 KB (キロバイト) です。 ヘッダー "x-ms-documentdb-responsecontinuationtokenlimitinkb" を使用して、継続トークンのサイズを 1 から 3 KB (キロバイト) に柔軟に調整できます。

現時点では、Azure API for FHIR はバンドル内の次へのリンクのみをサポートし、最初、最後、または前へのリンクはサポートされていません。

次のステップ

検索の基本について学習したので、さまざまな検索パラメーター、修飾子、その他の FHIR 検索シナリオを使用して検索する方法の詳細について、検索サンプル ページを参照してください。

FHIR 検索の例

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