適用於 Azure API for FHIR 的 FHIR 搜尋範例

發行項
10/31/2024

重要

Azure API for FHIR 將於 2026 年 9 月 30 日淘汰。 請依照移轉策略，在該日期前轉換至 Azure 健康資料服務 FHIR® 服務。由於 Azure API for FHIR 已淘汰，因此從 2025 年 4 月 1 日開始，將不允許新的部署。 Azure 健康資料服務 FHIR 服務是 Azure API for FHIR 的進化版本，可讓客戶透過與其他 Azure 服務整合來管理 FHIR、DICOM 和醫療技術服務。

以下是使用快速醫療保健互操作性資源（FHIR®）搜尋作業的範例，包括搜尋參數和修飾詞、鏈結和反向鏈結搜尋、複合搜尋、檢視、檢視結果的下一個專案 POST 集，以及使用要求搜尋。如需搜尋的詳細資訊，請參閱 FHIR 搜尋概觀。

搜尋結果參數

_包括

_include 會跨資源搜尋包含資源指定參數的資源。例如，您可以跨 MedicationRequest 資源搜尋，只尋找包含特定病患處方相關信息的指定患者，也就是 reference 參數 patient。下列範例會從提取參考MedicationRequests的所有 MedicationRequests 和所有患者。

 GET [your-fhir-server]/MedicationRequest?_include=MedicationRequest:patient

注意

_include和_revinclude限制為100個專案。

_revinclude

_revinclude 可讓您將相反的方向搜尋為 _include。例如，您可以搜尋患者，然後反向包含參考患者的所有遭遇：

GET [your-fhir-server]/Patient?_revinclude=Encounter:subject

_元素

_elements 將搜尋結果縮小為字段子集，以省略不必要的數據來減少回應大小。參數接受以逗號分隔的基底項目清單。

GET [your-fhir-server]/Patient?_elements=identifier,active

在此要求中，您會取得一組患者，其中每個資源只包含標識碼和病患的作用中狀態。此回應中的資源包含 meta.tag 值 SUBSETTED ，指出它們是一組不完整的結果。

搜尋修飾詞

：不

:not 可讓您尋找屬性不是 true 的資源。例如，您可以搜尋性別不是女性的患者。

GET [your-fhir-server]/Patient?gender:not=female

作為傳回值，您會取得性別不是女性的所有病患專案，包括空白值（沒有性別指定的專案）。這與搜尋性別為男性的患者不同，因為這不會包含沒有特定性別的專案。

：失蹤

:missing 傳回值為 true時，沒有指定專案值的所有資源，並在值為 false時傳回包含指定專案的所有資源。對於簡單的數據類型專案， :missing=true 會比對元素具有擴充功能但具有空值的所有資源。下列範例示範如何尋找在出生日期上遺漏資訊的所有 Patient 資源。

GET [your-fhir-server]/Patient?birthdate:missing=true

：確切

:exact 用於 string 參數，並傳回完全符合參數的結果，例如大小寫和字串連。

GET [your-fhir-server]/Patient?name:exact=Jon

此要求會傳 Patient 回名稱與完全相同 Jon的資源。如果資源具有名稱為或joN的Jonathan病患，搜尋會忽略並略過資源，因為它與指定的值不完全相符。

：包含

:contains 用於 string 參數，並搜尋具有所搜尋欄位內字串中指定值部分相符項目的資源。 contains 不區分大小寫，並允許字串連。例如：

GET [your-fhir-server]/Patient?address:contains=Meadow

此要求會傳回具有address包含字串「Meadow」值的所有Patient資源。這表示您可以有位址，其中包含當做搜尋結果傳回的值，例如 “Meadowers” 或 “59 Meadow ST”。

鏈結搜尋

若要執行涵蓋多個參考參數的一系列搜尋作業，您可以使用句點 .將一個參考參數附加至伺服器要求，以「鏈結」一連串的參考參數。例如，如果您想要檢視具有包含特定 name之資源參考Patient的所有DiagnosticReport資源subject：

 GET [your-fhir-server]/DiagnosticReport?subject:Patient.name=Sarah

此要求會傳回具有名為「Sarah」之病患主體的所有 DiagnosticReport 資源。欄位Patient之後的句點.會在參數的subject參考參數上執行鏈結搜尋。

一般搜尋的另一個常見用法（不是鏈結搜尋）是尋找特定患者的所有遭遇。 Patients 通常會有一或多個 Encounter具有主題的。下列會搜尋具有所提供 id之的所有Encounter資源Patient。

GET [your-fhir-server]/Encounter?subject=Patient/78a14cbe-8968-49fd-a231-d43e6619399f

使用鏈結搜尋，您可以找到符合特定資訊片段Patient的所有Encounter資源，例如 birthdate。

GET [your-fhir-server]/Encounter?subject:Patient.birthdate=1987-02-20

這可讓所有具有指定出生日期值的患者搜尋 Encounter 資源。

此外，鏈結搜尋可以使用符號 &在一個要求中多次完成，這可讓您在一個要求中搜尋多個條件。在這種情況下，鏈結搜尋「獨立」會搜尋每個參數，而不是搜尋只同時滿足所有條件的條件：

GET [your-fhir-server]/Patient?general-practitioner:Practitioner.name=Sarah&general-practitioner:Practitioner.address-state=WA

這會傳回 Patient 所有具有「Sarah」的資源， generalPractitioner 且 generalPractitioner 具有狀態 WA 的位址。換句話說，如果病人有來自紐約州的莎拉和州西澳大利亞州法案都參考為病人的 generalPractitioner，則兩者都會被傳回。

對於搜尋必須是AND涵蓋所有條件為群組之作業的案例，請參閱複合搜尋中的範例。

反向鏈結搜尋

鏈結搜尋可讓您根據所參考資源的屬性來搜尋資源。使用反向鏈結搜尋可讓您以另一種方式執行。您可以使用參數，根據參考資源 _has 的屬性來搜尋資源。例如， Observation 資源具有參考病患資源的搜尋參數 patient 。使用下列命令來尋找所 Observation 參考的所有病患資源與特定 code。

GET [base]/Patient?_has:Observation:patient:code=527

此要求會傳回使用程式代碼 527所Observation參考的病患資源。

此外，反向鏈結搜尋可以有遞歸結構。例如，下列會搜尋具有特定使用者janedoe稽核事件的所有患者Observation。

GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent:Practitioner.name=janedoe

注意

在 Azure API for FHIR 和 Azure Cosmos DB 支援的開放原始碼 FHIR 伺服器中，鏈結的搜尋和反向鏈結搜尋是 MVP 實作。為了在 Azure Cosmos DB 上完成鏈結搜尋，實作會逐步解說搜尋表示式，併發出子查詢來解決相符的資源。這會針對表達式的每個層級完成。如果有任何查詢傳回超過 100 個結果，則會擲回錯誤。

復合搜尋

若要一次搜尋符合多個條件的資源，請使用複合搜尋來聯結單一參數值序列與符號 $。結果會是符合聯結搜尋參數所指定之所有條件的資源交集。這類搜尋參數稱為複合搜尋參數，並定義結合巢狀結構中多個參數的新參數。例如，下列搜尋會尋找含Observation鉀值小於或等於 9.2 的所有DiagnosticReport資源。

GET [your-fhir-server]/DiagnosticReport?result.code-value-quantity=2823-3$lt9.2

此要求會指定包含之程式代碼的 2823-3元件，在此案例中為鉀。在符號之後 $ ，它會指定元件的值範圍，其使用 lt 「less than or equal to」和 9.2 針對鉀值範圍。

搜尋下一個專案集

每個單一搜尋查詢可傳回的項目數目上限為 1000。如果超過 1,000 個專案符合搜尋查詢，您可以使用下列程式來查看大於 1000 的專案。
使用中的searchset接續令牌url值，如下列Bundle結果所示。

    "resourceType": "Bundle",
    "id": "98731cb7-3a39-46f3-8a72-afe945741bd9",
    "meta": {
        "lastUpdated": "2021-04-22T09:58:16.7823171+00:00"
    },
    "type": "searchset",
    "link": [
        {
            "relation": "next",
            "url": "[your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd"
        },
        {
            "relation": "self",
            "url": "[your-fhir-server]/Patient?_sort=_lastUpdated"
        }
    ],

然後針對欄位 relation: next底下的所提供 URL 執行 GET 要求。

GET [your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd

這會傳回搜尋結果的下一組專案。 searchset是一組完整的搜尋結果專案，而接續令牌url是伺服器提供的連結，可供您擷取未顯示在前1000個專案的專案。

使用POST搜尋

先前提及的所有搜尋範例都已使用 GET 的要求。您也可以使用 POST _search要求來執行搜尋作業。

POST [your-fhir-server]/Patient/_search?_id=45

此要求會傳 Patient 回值為 45 的資源 id 。如同 GET 要求，伺服器會決定哪一組資源符合條件，並在 HTTP 回應中傳回套件組合資源。

使用 POST 搜尋的另一個範例，其中查詢參數會以窗體主體形式提交，如下所示。

POST [your-fhir-server]/Patient/_search
content-type: application/x-www-form-urlencoded

name=John

下一步

在本文中，您已瞭解如何使用不同的搜尋參數、修飾詞和 FHIR 搜尋工具進行搜尋。如需 FHIR 搜尋的詳細資訊，請參閱

FHIR 搜尋概觀

注意

FHIR® 是 HL7 的註冊商標，在 HL7 的許可下使用。

共用方式為