tencent cloud

腾讯健康数据服务

文档腾讯健康数据服务API 文档资源基础操作接口vRead

vRead

Download
聚焦模式
字号
最后更新时间： 2026-08-28 16:18:37

接口描述

用于根据资源 ID 和版本号读取指定资源的历史版本内容。该接口遵循标准 FHIR vRead 操作，客户端通过 HTTP GET 方法访问指定资源的历史版本地址，服务端返回该资源对应版本的完整内容及版本信息。
本示例展示了读取 Patient 资源某一历史版本的调用方式。

输入参数

参数名称
类型
是否必填
说明
HTTP Method
String
是
固定为 GET。
URL
String
是
历史版本读取地址，格式为 [baseUrl]/[resourceType]/[id]/_history/[versionId]。
Authorization
String
是
身份认证令牌，格式为 Bearer <AccessToken>，AccessToken 通过 调用方式 中的 GetAccessToken 接口获取（实例控制台场景可通过 GetWebAccessToken 接口获取）。
路径参数说明：
字段
类型
是否必填
说明
resourceType
String
是
FHIR 资源类型，例如 Patient、Observation、MedicationRequest 等。当前实例实际支持的全部资源类型，请通过 GET /INSTANCE_ID/fhir/metadata 调用 CapabilityStatement 接口，在返回的 rest[].resource[].type 中查看（实例支持的资源类型可在创建时通过 supported_resource_types 配置裁剪，不同实例可能不同）。各资源类型的字段定义可参见 FHIR Resource Types。
id
String
是
资源唯一 ID。为服务端创建资源时自动分配的逻辑 ID，可通过以下方式获取：
调用 创建接口（POST）创建资源，从响应头 Content-Location 或响应体 id 字段获取。
调用 搜索接口（GET /[resourceType]?_id= 或 /[resourceType]?identifier=）查询已有资源 ID。
versionId
String
是
资源历史版本号。可通过以下方式获取：
调用 读取接口（GET /[resourceType]/[id]）时，响应头 ETag 或响应体 meta.versionId 字段即为当前版本号。
调用 历史接口（GET /[resourceType]/[id]/_history）可返回该资源的全部历史版本列表，其中每条记录的 versionId 即为可用版本号。
请求 URL 示例：
https://HOSTNAME/INSTANCE_ID/fhir/Patient/199963/_history/3

输出参数

接口调用成功后，通常返回 HTTP 状态码 200 OK，并在响应头中包含当前返回版本的版本信息与历史版本地址，响应体中返回对应版本的资源完整内容。
响应头示例说明：
参数名称
类型
说明
Status Code
Integer
成功时返回 200 OK。
ETag
String
资源版本标识，例如 W/"3"。
Content-Location
String
当前返回的历史版本地址。
Last-Modified
String
资源最后修改时间，格式为 HTTP-date，例如 Mon, 06 Jul 2026 08:42:36 GMT。
响应体主要字段说明：
字段
类型
说明
resourceType
String
资源类型。
id
String
资源唯一 ID。
meta.versionId
String
当前返回的资源版本号。
meta.lastUpdated
String
该版本资源的更新时间。
meta.source
String
资源来源标识，仅当资源创建/更新时指定过该字段时返回。
identifier
Array
标识信息。
name
Array
姓名信息。
gender
String
性别。
birthDate
String
出生日期。
address
Array
地址信息。
说明：
响应体中 text 字段（Narrative 摘要）是否返回取决于服务端 Narrative 配置。当配置开启（narrative_enabled=true）时返回 text.status 和 text.div；配置关闭时不返回 text 字段。
text.status 可能值为 generated、extensions、additional、empty。
meta.source 仅在资源创建或更新时指定过该字段时才返回。该字段用于标识资源的原始来源系统，可通过请求头 X-Source（需服务端启用 CaptureResourceSourceFromHeaderInterceptor）或客户端直接写入 meta.source 设置。
上表中的 identifier、name、gender、birthDate、address 是 Patient 资源示例字段，实际响应体中的业务字段取决于读取的资源类型。

示例

请求示例

GET /INSTANCE_ID/fhir/Patient/199963/_history/3 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>

响应示例

HTTP/1.1 200 OK
ETag: W/"3"
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/199963/_history/3
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "199963",
  "meta": {
    "versionId": "3",
    "lastUpdated": "2019-07-12T01:58:07.164+00:00",
    "source": "#PR9lyCiz7HWynomw"
  },
  "identifier": [
    {
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345"
    }
  ],
  "name": [
    {
      "family": "Chalmers",
      "given": [
        "Peter",
        "James"
      ]
    }
  ],
  "gender": "male",
  "birthDate": "1974-02-13",
  "address": [
    {
      "line": [
        "534 Erewhon St"
      ],
      "city": "PleasantVille",
      "state": "Vic",
      "postalCode": "M5C 2X8"
    }
  ]
}

错误码

常见错误码如下，更多错误码请参见 错误码。
错误码
说明
400 Bad Request
请求格式错误，或版本号格式非法
401 Unauthorized
未认证，缺少有效身份凭证
403 Forbidden
已认证但无读取该资源历史版本的权限
404 Not Found
指定资源或历史版本不存在
410 Gone
指定历史版本已不可访问
500 Internal Server Error
服务端内部处理异常

上一篇: Read下一篇: 基础搜索接口

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈