你当前正在访问 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 Health Data Services FHIR 停用，在 2025 年 4 月 1 日开始前不会允许新的部署。 Azure Health Data Services FHIR 服务 是 Azure API for FHIR 的不断发展版本，可让客户通过集成到其他 Azure 服务来管理 FHIR、DICOM 和 MedTech 服务。
快速医疗保健互操作性资源 (FHIR®) 规范定义了搜索 FHIR 资源的基础。 本文将指导你完成在 FHIR 中搜索资源的部分关键内容。 有关搜索 FHIR 资源的完整详细信息，请参阅 HL7 FHIR 规范中的搜索。 我们将在本文中提供搜索语法示例。 每次搜索均面向 FHIR 服务器，通常而言，该服务器的 URL 为 https://<FHIRSERVERNAME>.azurewebsites.net。 在这些示例中，我们将使用占位符 {{FHIR_URL}} 表示此 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 月的发布中得到解决。
| 搜索参数类型 | 适用于 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 规范，组合搜索参数不支持修饰符。
修饰符和前缀
修饰符允许修改搜索参数。 下面概述了所有 FHIR 修饰符以及 Azure API for 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 仅限 1000 项或更少。
捆绑包中的下一个链接的延续令牌大小限制为 3知识库(KB)。 可以使用标头“x-ms-documentdb-responsecontinuationtokenlimitinkb”灵活调整 1 到 3 之间的继续标记大小知识库(KB)。
目前，Azure API for FHIR 仅支持捆绑包中有“下一页”链接，不支持“第一页”、“最后一页”或“上一页”链接。
后续步骤
现在，你已了解有关搜索的基本知识，请参阅搜索示例页，详细了解如何使用不同的搜索参数、修饰符和其他 FHIR 搜索方案进行搜索。
FHIR® 是 HL7 的注册商标，经 HL7 许可使用。