帮你快速理解、总结文档立即下载
文档中心>腾讯健康数据服务>API 文档>搜索操作接口>引用搜索接口

引用搜索接口

最近更新时间：2026-07-28 16:18:01

我的收藏

本页目录：

接口描述

用于基于资源之间的引用关系执行检索。当某个资源字段引用了另一类资源时，可通过引用字段作为搜索参数，筛选与目标资源相关联的数据记录。
本示例展示了基于 subject 引用字段检索 Encounter 资源的方式，即查询指定患者关联的就诊记录，并通过 _sort 参数对结果按日期升序排列。

输入参数

参数名称
类型
是否必填
说明
HTTP Method
String
是
固定为 GET。
URL
String
是
搜索地址，格式为 [baseUrl]/[resourceType]?[searchParams]。
Authorization
String
是
访问令牌，格式为 Bearer <AccessToken>。获取方式详见 调用方式。
Accept
String
否
响应格式，建议使用 application/fhir+json。
subject
String
是
引用搜索参数，表示关联的患者资源引用，格式通常为 Patient/{id}。其中 {id} 为被引用资源的唯一标识，可通过 基础搜索接口 或控制台资源查看器获取。
_sort
String
否
排序参数，用于指定结果排序字段。本示例按 date 排序。
resourceType
String
是
FHIR 资源类型，支持 FHIR 标准资源类型，如 Patient、Encounter、Observation 等，本示例为 Encounter。
请求 URL 示例：
https://HOSTNAME/INSTANCE_ID/fhir/Encounter?subject=Patient/k62d9d82-3f2b-44db-b808-04159be709fd&_sort=date
说明：
引用搜索适用于存在资源关联关系的场景。
subject=Patient/{id} 表示仅返回关联到该患者的 Encounter 记录。
_sort=date 表示按日期字段排序，示例中为从旧到新返回。

输出参数

接口调用成功后，通常返回 HTTP 状态码 200 OK，响应体一般为 Bundle 资源，包含符合条件的 Encounter 记录列表及分页信息。
响应体主要字段说明：
字段
类型
说明
resourceType
String
返回资源类型，通常为 Bundle。
id
String
Bundle 资源的唯一 ID，通常为 UUID。
meta
Object
Bundle 元数据，包含 lastUpdated 等字段。
meta.lastUpdated
String
Bundle 生成时间，ISO 8601 格式。
type
String
Bundle 类型，搜索场景通常为 searchset。
total
Integer
命中的总记录数。默认情况下可能不返回此字段，仅当服务端能够高效计算总数时返回；当前服务端不支持通过 _total=accurate 强制返回准确总数。
entry
Array
搜索结果列表。
entry[].fullUrl
String
资源完整访问地址。
entry[].resource
Object
匹配到的 Encounter 资源内容。
entry[].resource.id
String
资源的唯一 ID。
entry[].resource.meta
Object
资源元数据，包含 versionId、lastUpdated 等。
entry[].resource.subject
Object
当前就诊记录关联的患者引用信息。
entry[].resource.period
Object
就诊时间范围信息。
link
Array
分页链接信息。

示例

请求示例

GET /INSTANCE_ID/fhir/Encounter?subject=Patient/k62d9d82-3f2b-44db-b808-04159be709fd&_sort=date HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json

响应示例

{
  "resourceType": "Bundle",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "meta": {
    "lastUpdated": "2024-01-10T08:00:00.000+08:00"
  },
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://HOSTNAME/INSTANCE_ID/fhir/Encounter/enc-10001",
      "resource": {
        "resourceType": "Encounter",
        "id": "enc-10001",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2024-01-10T08:00:00.000+08:00"
        },
        "subject": {
          "reference": "Patient/k62d9d82-3f2b-44db-b808-04159be709fd"
        },
        "period": {
          "start": "2024-01-10T08:00:00+08:00",
          "end": "2024-01-10T09:30:00+08:00"
        }
      }
    }
  ]
}

错误码

常见错误码如下，更多错误码请参见 错误码。
错误码
说明
400 Bad Request
搜索参数格式错误，或引用参数值不合法
401 Unauthorized
未认证，缺少有效身份凭证
403 Forbidden
已认证但无搜索该资源的权限
404 Not Found
指定资源类型不存在
422 Unprocessable Entity
搜索参数语法正确，但未通过业务或规则校验
500 Internal Server Error
服务端内部处理异常
中国站