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

数值搜索接口

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

我的收藏

本页目录：

接口描述

用于基于数值类字段对资源进行条件检索，常见于检验结果、生命体征、测量值等场景。客户端可通过 HTTP GET 方法访问目标资源类型端点，并结合标准搜索参数对检验项目编码、数值大小、单位等条件进行筛选。
本示例展示了基于 Observation 资源进行实验室检验结果搜索的几种常见方式，包括：
查询指定患者的全部实验室检验结果。
查询所有患者的某一项特定检验结果。
查询满足特定数值范围的检验结果。

输入参数

参数名称
类型
是否必填
说明
HTTP Method
String
是
固定为 GET。
URL
String
是
搜索地址，格式为 [baseUrl]/[resourceType]?[searchParams]。
Authorization
String
是
访问令牌，格式为 Bearer <AccessToken>。获取方式详见 调用方式。
Accept
String
否
响应格式，建议使用 application/fhir+json。
subject
String
否
按关联患者过滤，格式通常为 Patient/{id}。其中 {id} 为被引用资源的唯一标识，可通过 基础搜索接口 或控制台资源查看器获取。
category
String
否
按资源分类过滤，本示例为实验室分类，如 http://hl7.org/fhir/observation-category%7Claboratory。
code
String
否
按检验项目编码过滤，通常为标准术语编码，如 http://loinc.org%7C6298-4。注意 URL 中 system%7Ccode 的竖线 | 需编码为 %7C。
value-quantity
String
否
按数值和单位过滤，格式通常为 [prefix][value]%7C[system]%7C[unit]，其中 prefix 为比较前缀（lt、le、gt、ge 等），竖线 | 需编码为 %7C。
说明：
category 可用于限制仅返回实验室类 Observation 资源。
code 常用于检索某个具体的检验项目，例如钾离子检验。
value-quantity 支持比较前缀，如 lt、le、gt、ge 等。
单位过滤通常建议同时带上单位系统和单位编码，以提高匹配准确性。
FHIR 搜索参数中用于分隔 system 与 code 的竖线 \\| 在 URL 中需编码为 %7C，否则可能导致请求失败。

输出参数

接口调用成功后，通常返回 HTTP 状态码 200 OK，响应体一般为 Bundle 资源，包含符合条件的 Observation 资源列表及分页信息。
响应体主要字段说明：
字段
类型
说明
resourceType
String
返回资源类型，通常为 Bundle。
id
String
Bundle 资源的唯一 ID，通常为 UUID。
meta
Object
Bundle 元数据，包含 lastUpdated 等字段。
meta.lastUpdated
String
Bundle 生成时间，ISO 8601 格式。
type
String
Bundle 类型，搜索场景通常为 searchset。
link
Array
分页链接信息，包含 relation 与 url。
link[].relation
String
链接关系类型，如 self、next、previous。
link[].url
String
对应分页的完整请求地址。
entry
Array
搜索结果列表。
entry[].fullUrl
String
资源的完整访问地址。
entry[].resource
Object
匹配到的 Observation 资源内容。
entry[].resource.id
String
资源的唯一 ID。
entry[].resource.meta
Object
资源元数据，包含 versionId、lastUpdated、source 等。
entry[].resource.status
String
观察结果状态，如 final、preliminary 等。
entry[].resource.category
Array
资源分类信息，如实验室分类。
entry[].resource.code
Object
检验项目编码信息。
entry[].resource.subject
Object
关联患者引用信息。
entry[].resource.valueQuantity
Object
检验数值及单位信息。
entry[].search.mode
String
搜索命中模式，如 match。

示例

请求示例

示例一：查询指定患者的全部实验室检验结果。
GET /INSTANCE_ID/fhir/Observation?subject=Patient/h0e270d9-ed56-4041-9dec-a45a73461c66&category=http://hl7.org/fhir/observation-category%7Claboratory HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
示例二：查询所有患者的某项特定检验结果。
GET /INSTANCE_ID/fhir/Observation?code=http://loinc.org%7C6298-4 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
示例三：查询数值低于 4.0 mmol/L 的钾离子结果。
GET /INSTANCE_ID/fhir/Observation?code=http://loinc.org%7C6298-4&value-quantity=lt4.0%7Chttp://unitsofmeasure.org%7Cmmol/L HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json

响应示例

{
  "resourceType": "Bundle",
  "id": "a9fdb12d-8a08-4cfb-8d8c-13f8a0fa50ad",
  "meta": {
    "lastUpdated": "2026-07-08T21:24:14.191+08:00"
  },
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir/Observation?code=http%3A%2F%2Floinc.org%7C6298-4&value-quantity=lt4.0%7Chttp%3A%2F%2Funitsofmeasure.org%7Cmmol%2FL"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://HOSTNAME/INSTANCE_ID/fhir/Observation/9a6adc7c-2496-43b9-881f-72a3f3067544",
      "resource": {
        "resourceType": "Observation",
        "id": "9a6adc7c-2496-43b9-881f-72a3f3067544",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2026-07-08T21:24:13.487+08:00",
          "source": "#nB7pryS0ElzarOdc"
        },
        "status": "final",
        "category": [
          {
            "coding": [
              {
                "system": "http://hl7.org/fhir/observation-category",
                "code": "laboratory"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "6298-4",
              "display": "Potassium"
            }
          ]
        },
        "subject": {
          "reference": "Patient/f25a8f0c-3473-4deb-8917-45d967263a1e"
        },
        "valueQuantity": {
          "value": 3.8,
          "system": "http://unitsofmeasure.org",
          "code": "mmol/L"
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

错误码

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

中国站