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

分页与结果数量控制

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

我的收藏

本页目录：

接口描述

用于对 FHIR 搜索结果进行分页获取及返回条数控制。客户端可通过 HTTP GET 方法发起搜索请求，服务端通常会以分页方式返回结果集合，并在响应的 Bundle.link 中提供后续分页链接。同时，也可通过 _count 参数控制单页返回的记录数。
本示例展示了以下两类常见场景：
搜索结果分页返回。
使用 _count 控制单次返回条数。

输入参数

参数名称
类型
是否必填
说明
HTTP Method
String
是
固定为 GET。
URL
String
是
搜索地址，格式为 [baseUrl]/[resourceType]?[searchParams]。
Authorization
String
是
访问令牌，格式为 Bearer <AccessToken>。获取方式详见 调用方式。
Accept
String
否
响应格式，建议使用 application/fhir+json。
_count
Integer
否
指定单页返回记录数，默认值为 20，需为正整数。实际最大值受服务端配置约束。
其他搜索参数
Query String
否
可与分页参数组合使用的常规搜索条件。
说明：
搜索结果通常默认分页返回。
第一页结果中通常会提供 self 和 next 等分页链接。
存在更多结果时，可通过 next 链接继续获取后续页面。
_count 仅控制单页返回条数，不改变命中的总结果数。

输出参数

接口调用成功后，通常返回 HTTP 状态码 200 OK，响应体一般为 Bundle 资源，包含当前页结果、总数以及分页链接信息。
响应体主要字段说明：
字段
类型
说明
resourceType
String
返回资源类型，通常为 Bundle。
id
String
当前结果集唯一标识。
meta.lastUpdated
String
当前结果集生成时间。
type
String
Bundle 类型，搜索场景通常为 searchset。
total
Integer
命中的总记录数。默认情况下可能不返回此字段，仅当服务端能够高效计算总数时返回；当前服务端不支持通过 _total=accurate 强制返回准确总数。
link
Array
分页链接信息。
link[].relation
String
链接关系，如 self、next。
link[].url
String
对应分页访问地址。
entry
Array
当前页返回的资源列表。

示例

示例一：分页查询搜索结果

请求示例

GET /INSTANCE_ID/fhir/Patient?birthdate=1974-02-13 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json

响应示例

{
  "resourceType": "Bundle",
  "id": "3c4b5bfc-a03e-474c-9cb2-bd640022cf20",
  "meta": {
    "lastUpdated": "2022-10-13T14:07:20.613+00:00"
  },
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir/Patient?birthdate=1974-02-13"
    },
    {
      "relation": "next",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir?_getpages=3c4b5bfc-a03e-474c-9cb2-bd640022cf20&_getpagesoffset=20&_count=20&_bundletype=searchset"
    }
  ]
}

示例二：控制单次返回结果数量

请求示例

GET /INSTANCE_ID/fhir/Observation?code=http://loinc.org%7C718-7&_count=20 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json

响应示例

HTTP/1.1 200 OK
Content-Type: application/fhir+json
x-request-id: ENqsVXqc5SeqLOfU
{
  "resourceType": "Bundle",
  "id": "3c4b5bfc-a03e-474c-9cb2-bd640022cf20",
  "meta": {
    "lastUpdated": "2022-10-13T14:07:20.613+00:00"
  },
  "type": "searchset",
  "total": 45,
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir/Observation?code=http://loinc.org%7C718-7&_count=20"
    },
    {
      "relation": "next",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir?_getpages=3c4b5bfc-a03e-474c-9cb2-bd640022cf20&_getpagesoffset=20&_count=20&_bundletype=searchset"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://HOSTNAME/INSTANCE_ID/fhir/Observation/OBS001",
      "resource": {
        "resourceType": "Observation",
        "id": "OBS001",
        "status": "final",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "718-7",
              "display": "Hemoglobin [Mass/volume] in Blood"
            }
          ]
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

错误码

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

中国站