你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
在 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 API for FHIR 的演化版本，可让客户管理 FHIR、DICOM 和医疗技术服务，并集成到其他 Azure 服务。
快速医疗保健互操作性资源 (FHIR®) 规范定义了搜索 FHIR 资源的基础。 本文将指导你完成在 FHIR 中搜索资源的一些关键方面。 有关搜索 FHIR 资源的完整详细信息，请参阅 HL7 FHIR 规范中的搜索。 在本文中，我们提供了搜索语法的示例。 每个搜索都针对 FHIR 服务器，该服务器通常具有 URL https://<FHIRSERVERNAME>.azurewebsites.net。 在此示例中，我们将占位符 {{FHIR_URL}} 用于此 URL。
FHIR 搜索可以面向特定资源类型、指定的隔离舱或所有资源。 在 FHIR 中执行搜索的最简单方法是使用 GET 请求。 例如，如果要拉取数据库中的所有患者，可以使用以下请求。
GET {{FHIR_URL}}/Patient
还可以使用 POST搜索，如果查询字符串很长，这非常有用。 若要使用 POST 进行搜索，可以表单正文形式提交搜索参数。 这允许使用更长、更复杂的查询参数序列，而这些参数在查询字符串中可能难以查看和理解。
如果搜索请求成功，则会收到类型为 searchsetFHIR 捆绑包的响应。 如果搜索失败，可以在“搜索失败”中找到 OperationOutcome 错误详细信息，以帮助了解搜索失败的原因。
在以下部分中，我们将介绍搜索所涉及的方方面面。 查看这些详细信息后，请参阅示例页，该页包含可在 Azure API for FHIR 中进行的搜索示例。
搜索参数
搜索基于资源的各种属性。 这些属性称为搜索参数。 每种资源都有一组定义的搜索参数。 必须在数据库中定义搜索参数并编制索引，方可成功搜索该参数。
每个搜索参数都有一个定义的数据类型。 下表概述了对各种数据类型的支持。
警告
在 Azure API for FHIR 上使用链接搜索时 _sort ，当前存在问题。 有关详细信息，请参阅开源问题 #2344。 这将在 2021 年 12 月的发布中得到解决。
| 搜索参数类型 | 适用于 FHIR 的 Azure API | Azure Health Data Services 中的 FHIR 服务 | 评论 |
|---|---|---|---|
| 数字 | 是 | 是 | |
| date | 是 | 是 | |
| string | 是 | 是 | |
| token | 是 | 是 | |
| reference | 是 | 是 | |
| 复合 | 部分 | 部分 | 本文稍后将介绍支持的复合类型列表。 |
| quantity | 是 | 是 | |
| uri | 是 | 是 | |
| 特殊 | 否 | 否 |
通用搜索参数
存在适用于所有资源的通用搜索参数。 这些列表位于以下列表中，以及他们在 Azure API for FHIR 中的支持。
| 通用搜索参数 | 适用于 FHIR 的 Azure API | Azure Health Data Services 中的 FHIR 服务 | 评论 |
|---|---|---|---|
| _id | 是 | 是 | |
| _lastUpdated | 是 | 是 | |
| _tag | 是 | 是 | |
| _type | 是 | 是 | |
| _security | 是 | 是 | |
| _profile | 是 | 是 | |
| _has | 部分 | 是 | _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 查找所有资源的搜索参数。
注意
Azure API for FHIR 不会自动创建任何非 FHIR 规范定义的搜索参数并编制其索引。 但是，我们确实支持你定义自己的 搜索参数。
组合搜索参数
组合搜索允许搜索值对。 例如，如要搜索用户身高 60 英寸的身高观测值，则需要确保单一观测分量包含身高代码和值 60。 你不想得到重量 60、身高 48 的观测值，即使观测值有符合值为 60 和高度代码的项，只是在不同的组分部分也不行。
使用 Azure API for FHIR，我们支持以下搜索参数类型配对。
- 引用、令牌
- 令牌、日期
- 令牌、数字、数字
- 令牌、数量
- 数字、字符串
- 令牌、令牌
有关详细信息，请参阅 HL7 组合搜索参数。
注意
根据 FHIR 规范，组合搜索参数不支持修饰符。
修饰符和前缀
修饰符允许修改搜索参数。 下表概述了 Azure API for FHIR 中的所有 FHIR 修饰符及其支持。
| 修饰符 | 适用于 FHIR 的 Azure API | 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 网站。
| 搜索结果参数 | 适用于 FHIR 的 Azure API | Azure Health Data Services 中的 FHIR 服务 | 评论 |
|---|---|---|---|
| _elements | 是 | 是 | |
| _计数 | 是 | 是 | _count 仅限 1000 个资源。 如果设置为高于 1000，则只返回 1000，并且将在捆绑包中返回警告。 |
| _include | 是 | 是 | 包含的项仅限 100 个。 PaaS 上的 _include 和 Azure Cosmos DB 上的 OSS 不包括 :iterate 支持 (#2137)。 |
| _revinclude | 是 | 是 | 包含的项仅限 100 个。 PaaS 上的 _revinclude 和 Azure Cosmos DB 上的 OSS 不包括 :iterate 支持 (#2137)。 错误的请求 #1319 还包含错误的状态代码 |
| _summary | 是 | 是 | |
| _total | 部分 | 部分 | _total=none 和 _total=accurate |
| _sort | 部分 | 部分 | Azure API for FHIR 和 FHIR 服务上支持 sort=_lastUpdated。 对于在 2021 年 4 月 20 日之后创建的 Azure API for FHIR 和 OSS Azure Cosmos DB 数据库，支持对名字、姓氏、出生日期和临床日期进行排序。 |
| _contained | 否 | 否 | |
| _containedType | 否 | 否 | |
| _score | 否 | 否 |
注意
默认情况下，_sort 按升序对记录进行排序。 可以使用前缀 '-' 来按降序排序。 此外，FHIR 服务和 Azure API for FHIR 仅允许你一次对单个字段进行排序。
默认情况下，Azure API for FHIR 设置为宽松处理。 这意味着服务器忽略任何未知或不支持的参数。 如想使用严格处理，可以使用首选标头并设置 handling=strict。
链接搜索和反向链接搜索
链接搜索允许使用搜索参数在其他资源引用的资源上执行搜索。 例如，如果要查找患者名为 Jane 的情况，请使用：
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane。
同样地，可以执行反向链接搜索。 如此一来便可获取一些资源，你可以在其中对其他引用这些资源的资源指定条件。 有关链接搜索和反向链接搜索的更多示例，请参阅 FHIR 搜索示例页。
注意
Azure Cosmos DB 支持的 Azure API for FHIR 和开源中有一个限制，即链式搜索和反向链式搜索所需的每个子查询仅返回 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 许可使用。