你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

在 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 月的发布期间得到解决。

搜索参数类型 适用于 FHIR 的 Azure API Azure Health Data Services 中的 FHIR 服务 注释
number
date
string
令牌
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 中和 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 _count 仅限 1000 个资源。 如果将其设置为高于 1000,则仅返回 1000 个资源,并且捆绑包中会返回一则警告。
_include 包含的项仅限 100 个。 Cosmos DB 上的 PaaS 和 OSS 上的_include不包括:迭代支持 (#2137)
_revinclude 包含的项仅限 100 个。 Cosmos DB 上的 PaaS 和 OSS 上的_revinclude不包括:迭代支持 (#2137) 。 错误请求的状态代码 也不正确 #1319
_summary
_total 部分 部分 _total=none 和 _total=accurate
_sort 部分 部分 Azure API for FHIR 和 FHIR 服务支持 sort=_lastUpdated。 对于在 2021 年 4 月 20 日之后创建的 Azure API for FHIR 和 OSS 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 API for FHIR 和 Cosmos DB 支持的开放源代码中,存在一个限制,其中链式和反向链接搜索所需的每个子查询仅返回 1000 个项目。 如果发现超过 1000 个项目,将收到以下错误消息:“链接表达式中的子查询不能返回超过 1000 个结果,请使用更具选择性的条件。 若要成功查询,则需要更具体地了解所需内容。

分页

如上所述,搜索结果将分页捆绑包。 默认情况下,每页的搜索结果为 10 个,但此值可以通过指定 _count 增大(或减小)。 捆绑包中存在一个包含当前搜索结果的自链接。 如有其他匹配项,该捆绑包将包含“下一页”链接。 你可以继续使用“下一页”链接来获取后续的结果页面。 _count 仅限 1000 项或更少。

目前,Azure API for FHIR 仅支持捆绑包中有“下一页”链接,不支持“第一页”、“最后一页”或“上一页”链接。

后续步骤

现在,你已了解有关搜索的基本知识,请参阅搜索示例页,详细了解如何使用不同的搜索参数、修饰符和其他 FHIR 搜索方案进行搜索。

FHIR® 是 HL7 的注册商标,用于 HL7 的权限。