Azure API for FHIR 中的搜尋概觀
重要
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） 規格會定義搜尋 FHIR® 資源的基本概念。 本文會引導您完成在 FHIR 中搜尋資源的一些重要層面。 如需搜尋 FHIR 資源的完整詳細數據，請參閱 HL7 FHIR 規格中的搜尋 。 在本文中，我們會提供搜尋語法的範例。 每個搜尋都會針對您的 FHIR 伺服器，其通常具有的 https://<FHIRSERVERNAME>.azurewebsites.netURL。 在此範例中，我們會針對此 URL 使用佔位元 {{FHIR_URL}}。
FHIR 搜尋可以針對特定資源類型、指定的區間或所有資源。 在 FHIR 中執行搜尋的最簡單方式是使用 GET 要求。 例如，如果您想要提取資料庫中的所有患者，您可以使用下列要求。
GET {{FHIR_URL}}/Patient
您也可以使用 POST來搜尋 ，如果查詢字串很長，這會很有用。 若要使用 POST進行搜尋，可以將搜尋參數提交為窗體主體。 這允許較長且更複雜的查詢參數系列，這些參數在查詢字串中可能難以查看和瞭解。
如果搜尋要求成功，您會收到類型 searchset為的 FHIR 套件組合回應。 如果搜尋失敗，您可以在 中找到 OperationOutcome 錯誤詳細數據，以協助您了解搜尋失敗的原因。
在下列各節中，我們將討論搜尋所涉及的各種層面。 檢閱這些詳細數據之後，請參閱我們的 範例頁面 ，其中包含您可以在 Azure API for FHIR 中建立的搜尋範例。
搜尋參數
搜尋是以資源的各種屬性為基礎。 這些屬性稱為搜尋參數。 每個資源都有一組定義的搜尋參數。 搜尋參數必須在資料庫中定義並編制索引，您才能成功搜尋它。
每個搜尋參數都有已定義的 數據類型。 下表概述各種數據類型的支援。
警告
搭配鏈結搜尋在 _sort Azure API for FHIR 上使用時，目前有問題。 如需詳細資訊，請參閱開放原始碼問題 #2344。 這會在 2021 年 12 月的發行期間解決。
| 搜尋參數類型 | 適用於 FHIR 的 Azure API | Azure Health Data Services 中的 FHIR 服務 | 註解 |
|---|---|---|---|
| 數值 | Yes | Yes | |
| date | Yes | Yes | |
| 字串 | Yes | Yes | |
| token | Yes | Yes | |
| 參考 | Yes | Yes | |
| 複合 | Partial | Partial | 本文稍後會說明支持的複合類型清單。 |
| 數量 | Yes | Yes | |
| uri | Yes | Yes | |
| 特殊 | No | No |
常見的搜尋參數
有一 些常見的搜尋參數 會套用至所有資源。 這些位於下列清單中，以及其在 Azure API for FHIR 中的支援。
| 一般搜尋參數 | 適用於 FHIR 的 Azure API | Azure Health Data Services 中的 FHIR 服務 | 註解 |
|---|---|---|---|
| _id | Yes | Yes | |
| _lastUpdated | Yes | Yes | |
| _標記 | Yes | Yes | |
| _type | Yes | Yes | |
| _安全 | Yes | Yes | |
| _輪廓 | Yes | Yes | |
| _has | Partial | Yes | _has的支持位於 Azure API for FHIR 中的 MVP 中，以及 Azure Cosmos DB 支援的 OSS 版本。 下列鏈結區段包含更多詳細數據。 |
| _查詢 | No | No | |
| _濾波器 | No | No | |
| _清單 | No | No | |
| _發短信 | No | No | |
| _內容 | No | No |
資源特定參數
透過 Azure API for FHIR，我們支援 FHIR 規格所定義的幾乎所有資源特定搜尋參數 。 下列連結提供我們不支援的唯一搜尋參數。
您也可以使用下列要求，在 FHIR 功能語句中看到搜尋參數的目前支援。
GET {{FHIR_URL}}/metadata
若要查看功能語句中的搜尋參數，請流覽至 CapabilityStatement.rest.resource.searchParam 以查看每個資源的搜尋參數，並 CapabilityStatement.rest.searchParam 尋找所有資源的搜尋參數。
注意
Azure API for FHIR 不會自動建立或編製任何未由 FHIR 規格定義之搜尋參數的索引。 不過，我們確實支援您定義自己的 搜尋參數。
複合搜尋參數
復合搜尋可讓您搜尋值組。 例如，如果您要搜尋人員為 60 英吋的高度觀察，您會想要確定觀察的單一元件包含高度 代碼和 60 的值。 您不會想要取得一個觀察，其中儲存了 60 和高度為 48 的粗細，即使觀察會有符合 60 值和高度代碼的專案，只是在不同的元件區段中。
使用 Azure API for FHIR，我們支援下列搜尋參數類型配對。
- 參考、令牌
- Token、Date
- Token、Number、Number
- Token、Quantity
- Token、String
- 令牌、令牌
如需詳細資訊，請參閱 HL7 複合搜尋參數。
注意
複合搜尋參數不支援 FHIR 規格的修飾詞。
修飾詞和前置詞
修飾詞 可讓您修改搜尋參數。 下表概述 Azure API for FHIR 中的所有 FHIR 修飾詞及其支援。
| 修飾詞 | 適用於 FHIR 的 Azure API | Azure Health Data Services 中的 FHIR 服務 | 註解 |
|---|---|---|---|
| ：失蹤 | Yes | Yes | |
| ：確切 | Yes | Yes | |
| ：包含 | Yes | Yes | |
| ：發短信 | Yes | Yes | |
| ：type （reference） | Yes | Yes | |
| ：不 | Yes | Yes | |
| ：below （uri） | Yes | Yes | |
| ：above （uri） | Yes | Yes | |
| ：in （token） | No | No | |
| ：below （token） | No | No | |
| ：above （token） | No | No | |
| ：not-in （token） | No | No |
對於具有特定訂單（數位、日期和數量）的搜尋參數，您可以使用 參數上的前置詞 來協助尋找相符專案。 Azure API for FHIR 支援所有前置詞。
搜尋結果參數
為了協助管理傳回的資源，您可以使用搜尋結果參數。 如需如何使用每個搜尋結果參數的詳細資訊，請參閱 HL7 網站。
| 搜尋結果參數 | 適用於 FHIR 的 Azure API | Azure Health Data Services 中的 FHIR 服務 | 註解 |
|---|---|---|---|
| _元素 | Yes | Yes | |
| _計數 | Yes | Yes | _count限制為1000個資源。 如果設定高於 1000，則只會傳回 1000，而且套件組合中會傳回警告。 |
| _包括 | Yes | Yes | 包含的專案限制為 100。 _include Azure Cosmos DB 上的 PaaS 和 OSS 不包含 ：iterate 支援 （#2137）。 |
| _revinclude | Yes | Yes | 包含的專案限制為 100。 _revinclude Azure Cosmos DB 上的 PaaS 和 OSS 不包含 ：iterate 支援 （#2137）。 不正確的要求 也有不正確的狀態代碼 #1319 |
| _總結 | Yes | Yes | |
| _總 | Partial | Partial | _total=none 和 _total=accurate |
| _排序 | Partial | Partial | azure API for FHIR 和 FHIR 服務支援 sort=_lastUpdated。 針對在 2021 年 4 月 20 日之後建立的 Azure API for FHIR 和 OSS Azure Cosmos DB 資料庫，支援名字、姓氏、出生日期和臨床日期排序。 |
| _包含 | No | No | |
| _containedType | No | No | |
| _得分 | No | 無 |
注意
根據預設 _sort ，會以遞增順序排序記錄。 您可以使用前置 '-' 詞以遞減順序排序。 此外，FHIR 服務和 Azure API for FHIR 一次只允許您排序單一字段。
根據預設，Azure API for FHIR 會設定為寬大處理。 這表示伺服器會忽略任何未知或不支持的參數。 如果您要使用嚴格的處理，您可以使用 Prefer 標頭並設定 handling=strict。
鏈結和反向鏈結搜尋
鏈結搜尋可讓您在另一個資源所參考的資源上使用搜尋參數進行搜尋。 例如，如果您想要尋找患者名稱為 Jane 的遭遇，請使用：
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane.
同樣地，您也可以執行反向鏈結搜尋。 這可讓您取得資源，讓您可以在參照這些資源的其他資源上指定準則。 如需鏈結和反向鏈結搜尋的更多範例，請參閱 FHIR 搜尋範例 頁面。
注意
在 Azure API for FHIR 和 Azure Cosmos DB 支援的 開放原始碼 中，鏈結和反向鏈結搜尋所需的每個子查詢只會傳回 1000 個專案的限制。 如果找到超過 1000 個專案，您會收到下列錯誤訊息：「鏈結運算式中的子查詢無法傳回超過 1000 個結果，請使用更選擇性的準則。 若要取得成功的查詢，您必須更具體地瞭解您要尋找的內容。
分頁
如先前所述，搜尋的結果是分頁組合。 根據預設，搜尋會傳回每頁 10 個結果，但藉由指定 _count來增加（或減少）。 在套件組合內，會有包含目前搜尋結果的自我連結。 如果有其他相符專案，套件組合將會包含下一個連結。 您可以繼續使用下一個連結來取得後續的結果頁面。 _count 限制為 1,000 個專案或更少。
套件組合中的下一個連結具有 3 KB 的接續令牌大小限制。 您可以使用標頭 x-ms-documentdb-responsecontinuationtokenlimitinkb，彈性調整介於 1 KB 到 3 KB 之間的接續令牌大小。
目前，Azure API for FHIR 僅支援套件組合中的下一個連結，而且不支援第一個、最後一個或上一個連結。
下一步
既然您已了解搜尋的基本概念，請參閱搜尋範例頁面，以取得如何使用不同搜尋參數、修飾詞和其他 FHIR 搜尋案例的詳細數據。
注意
FHIR® 是 HL7 的註冊商標，在 HL7 的許可下使用。