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

基础搜索接口

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

我的收藏

本页目录：

接口描述

用于基于标准 FHIR 搜索能力对指定资源类型进行条件检索。客户端可通过 HTTP GET 方法访问资源类型端点，并在 URL 中携带搜索参数，以筛选符合条件的资源记录。
基础搜索支持以下常见方式：
无参数搜索：返回指定资源类型的记录列表。
单参数搜索：基于单个搜索字段筛选结果。
多参数组合搜索：多个参数之间默认按 AND 关系组合。
逗号分隔值搜索：同一参数中多个值按 OR 关系匹配。
本示例展示了对 Patient 资源执行基础搜索的常见方式。

输入参数

参数名称
类型
是否必填
说明
HTTP Method
String
是
固定为 GET。
URL
String
是
搜索地址，格式为 [baseUrl]/[resourceType] 或 [baseUrl]/[resourceType]?[searchParams]。
Authorization
String
是
访问令牌，格式为 Bearer <AccessToken>。获取方式详见 调用方式。
Accept
String
否
响应格式，建议使用 application/fhir+json。
searchParams
String
否
搜索参数，以 URL 查询字符串（key=value&...）形式拼接在 URL 之后，支持单个或多个参数组合。
常用搜索参数说明：
参数名称
类型
是否必填
说明
name
String
否
按患者姓名检索，可匹配姓名相关字段。
gender
String
否
按性别检索，如 male、female。
family
String
否
按姓氏检索。
given
String
否
按名字检索；支持逗号分隔多个值。
说明：
当不传任何搜索参数时，系统返回指定资源类型的记录列表。
多个不同参数同时传入时，默认按 AND 关系组合。
同一参数传入逗号分隔多个值时，通常按 OR 关系处理。
搜索结果通常按分页策略返回，单次响应可能只包含部分记录。

输出参数

接口调用成功后，通常返回 HTTP 状态码200 OK，响应体一般为 Bundle 资源，其中包含本次检索命中的资源列表及分页信息。
响应体主要字段说明：
字段
类型
说明
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
匹配到的资源内容。
entry[].resource.id
String
资源的唯一 ID。
entry[].resource.meta
Object
资源元数据，包含 versionId、lastUpdated 等。
entry[].search.mode
String
搜索命中模式。
link
Array
分页链接信息，如首页、下一页等。

示例

请求示例

示例一：无参数搜索
GET /INSTANCE_ID/fhir/Patient HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
示例二：按姓名搜索
GET /INSTANCE_ID/fhir/Patient?name=chalmers HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
示例三：多参数组合搜索（AND）
GET /INSTANCE_ID/fhir/Patient?name=chalmers&gender=male HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
示例四：逗号分隔多值搜索（OR）
GET /INSTANCE_ID/fhir/Patient?given=peter,james HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json

响应示例

{
  "resourceType": "Bundle",
  "id": "2d7b3566-1773-40b3-abd4-0c8ebdd6466f",
  "meta": {
    "lastUpdated": "2026-07-08T21:24:05.941+08:00"
  },
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir/Patient?name=chalmers"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://HOSTNAME/INSTANCE_ID/fhir/Patient/199963",
      "resource": {
        "resourceType": "Patient",
        "id": "199963",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2022-10-10T07:07:33.086-04:00"
        },
        "name": [
          {
            "family": "Chalmers",
            "given": [
              "Peter",
              "James"
            ]
          }
        ],
        "gender": "male"
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

错误码

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

中国站