腾讯健康数据服务补丁

接口描述
用于对指定资源执行局部更新。该接口遵循标准 FHIR Patch 操作，客户端通过 HTTP PATCH 方法提交补丁文档，仅修改资源中的部分字段，无需传入完整资源内容。
本接口支持基于 JSON Patch 的更新方式，请求头 Content-Type 通常使用 application/json-patch+json。补丁文档以数组形式提交，每一项表示一个变更操作，常见操作包括：
add：新增字段或新增数组元素。
replace：替换现有字段值。
remove：删除字段或数组元素。
test：校验目标路径当前值是否符合预期，常用于执行删除前的条件检查。
输入参数
参数名称
类型
是否必填
说明
HTTP Method
String
是
固定为 PATCH。
URL
String
是
资源局部更新地址，格式为 [baseUrl]/[resourceType]/[id]。
Authorization
String
是
身份认证令牌，格式为 Bearer <AccessToken>，AccessToken 通过 调用方式 中的 GetAccessToken 接口获取（实例控制台场景可通过 GetWebAccessToken 接口获取）。
Content-Type
String
是
请求体 MIME 类型，固定为 application/json-patch+json。
Request Body
JSON Array
是
JSON Patch 补丁文档，数组中的每一项代表一个操作。
路径参数说明：
字段
类型
是否必填
说明
resourceType
String
是
FHIR 资源类型，本示例为 Patient。当前实例实际支持的全部资源类型，请通过 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。
请求 URL 示例：
https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954
请求体示例字段说明：
字段
类型
是否必填
说明
op
String
是
补丁操作类型，如 add、replace、remove、test。
path
String
是
变更目标路径，采用 JSON Pointer 格式，如 /gender。
value
Any
否
变更值；add、replace 时通常必填。
说明：
补丁文档必须为数组，即使仅包含一个操作也需使用数组格式。
对数组字段进行新增时，如目标数组不存在，通常需要先创建数组节点，再向指定下标写入内容。
path 必须准确指向资源中的目标字段，否则可能导致请求失败。
删除数组元素时，需要明确待删除元素的数组下标，例如 /address/0。
如需避免误删，可先使用 test 操作校验目标元素内容，再执行 remove 操作。
输出参数
接口调用成功后，通常返回 HTTP 状态码 200 OK，并在响应头中包含资源版本信息与最新版本地址，响应体中返回补丁执行后的最新资源内容。
响应头示例说明：
参数名称
类型
说明
Status Code
Integer
成功时返回 200 OK。
Content-Location
String
更新后资源的历史版本地址，格式为 [baseUrl]/[resourceType]/[id]/_history/[versionId]。
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
资源来源标识，仅当资源创建/更新时指定过该字段时返回。
gender
String
更新后的性别字段（本示例为 Patient 资源）。
birthDate
String
更新后的出生日期（本示例为 Patient 资源）。
address
Array
更新后的地址信息（本示例为 Patient 资源）。
说明：
响应体中 text 字段（Narrative 摘要）是否返回取决于服务端 Narrative 配置。当配置开启（narrative_enabled=true）时返回 text.status 和 text.div；配置关闭时不返回 text 字段。
text.status 可能值为 generated、extensions、additional、empty。
meta.source 仅在资源创建或更新时指定过该字段时才返回。该字段用于标识资源的原始来源系统，可通过请求头 X-Source（需服务端启用 CaptureResourceSourceFromHeaderInterceptor）或客户端直接写入 meta.source 设置。
上表中的 gender、birthDate、address 是 Patient 资源示例字段，实际响应体中的业务字段取决于执行补丁的资源类型与修改内容。
示例
示例一：新增性别字段
请求示例
PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/gender",
    "value": "female"
  }
]
响应示例
HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/2
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2022-04-24T19:05:13.111+05:30"
  },
  "gender": "female"
}
示例二：新增地址信息
请求示例
PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/address",
    "value": []
  },
  {
    "op": "add",
    "path": "/address/0",
    "value": {
      "use": "home",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "3999",
      "text": "<Sample Street Name>"
    }
  }
]
响应示例
HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/3
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "3",
    "lastUpdated": "2022-04-24T19:17:02.229+05:30"
  },
  "gender": "female",
  "address": [
    {
      "use": "home",
      "text": "<Sample Street Name>",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "3999"
    }
  ]
}
示例三：替换邮编和出生日期
请求示例
PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "replace",
    "path": "/address/0/postalCode",
    "value": "4000"
  },
  {
    "op": "replace",
    "path": "/birthDate",
    "value": "1974-02-20"
  }
]
响应示例
HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/4
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "4",
    "lastUpdated": "2022-04-24T19:37:51.559+05:30"
  },
  "gender": "female",
  "birthDate": "1974-02-20",
  "address": [
    {
      "use": "home",
      "text": "<Sample Street Name>",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "4000"
    }
  ]
}
示例四：删除地址数组中的第一个元素
请求示例
PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "remove",
    "path": "/address/0"
  }
]
响应示例
HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/5
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "5",
    "lastUpdated": "2022-04-24T19:54:03.769+05:30"
  },
  "gender": "female",
  "birthDate": "1974-02-20"
}
说明：
当目标字段为数组时，执行删除操作需要明确数组元素的位置。如果无法确保当前位置是否仍为目标数据，建议先使用 test 操作进行内容校验。
如果删除后数组变为空（即原数组只有 1 个元素），且实例开启了资源库校验（enable_repository_validating_interceptor=true），需要额外处理空数组和 meta.source 问题，请参见 示例六。
示例五：校验后删除地址信息
请求示例
PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/address/0",
    "value": {
      "use": "home",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "4000",
      "text": "<Sample Street Name>"
    }
  },
  {
    "op": "remove",
    "path": "/address/0"
  }
]
响应示例
HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/5
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "5",
    "lastUpdated": "2022-04-24T19:54:03.769+05:30"
  },
  "gender": "female",
  "birthDate": "1974-02-20"
}
示例六：开启数据校验时清空数组字段
请求示例
PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "replace",
    "path": "/meta/source",
    "value": "http://test.example.com/source"
  },
  {
    "op": "remove",
    "path": "/address/0"
  },
  {
    "op": "remove",
    "path": "/address"
  }
]
响应示例
HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/2
Last-Modified: Mon, 14 Jul 2026 12:17:58 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2026-07-14T20:17:58.710+08:00",
    "source": "http://test.example.com/source#rdVXtMxLI6QB74gC"
  },
  "identifier": [
    {
      "system": "http://test.example.com/patient-id",
      "value": "TEST-001"
    }
  ],
  "name": [
    {
      "family": "Test",
      "given": ["Validate"]
    }
  ],
  "gender": "male",
  "birthDate": "2000-01-01"
}
说明：
当实例开启了「资源库校验」（enable_repository_validating_interceptor=true，生产环境默认开启），PATCH 落地后的资源会经过 FHIR RepositoryValidatingInterceptor 全量校验。
第一条 replace /meta/source 把 source 改为有效 URL。HAPI 默认会将 requestId 拼成 #requestId 写入 meta.source，纯 fragment 不符合 URI 规范，需要替换为有效 URL。
第二条 remove /address/0 删除数组元素。
第三条 remove /address 删除空数组字段本身，避免留下空数组 []。
如果实例未开启资源库校验，只需第二步 remove 即可（见示例四）。
错误码
常见错误码如下，更多错误码请参见 错误码。
错误码
说明
400 Bad Request
补丁文档格式错误，或 path、op 参数非法
401 Unauthorized
未认证，缺少有效身份凭证
403 Forbidden
已认证但无更新该资源的权限
404 Not Found
指定资源不存在
409 Conflict
资源状态冲突，例如目标路径与当前资源状态不匹配
412 Precondition Failed
资源未通过 RepositoryValidatingInterceptor 数据校验。常见原因：PATCH 落地后出现空数组字段（如 remove /address/0 后未移除整个 address 数组）。
415 Unsupported Media Type
Content-Type 不受支持，例如未使用 application/json-patch+json
422 Unprocessable Entity
补丁语法正确，但未通过业务或 FHIR 规则校验
500 Internal Server Error
服务端内部处理异常
﻿

参数名称	类型	是否必填	说明
HTTP Method	String	是	固定为 `PATCH`。
URL	String	是	资源局部更新地址，格式为 `[baseUrl]/[resourceType]/[id]`。
Authorization	String	是	身份认证令牌，格式为 `Bearer <AccessToken>`，AccessToken 通过调用方式中的 `GetAccessToken` 接口获取（实例控制台场景可通过 `GetWebAccessToken` 接口获取）。
Content-Type	String	是	请求体 MIME 类型，固定为 `application/json-patch+json`。
Request Body	JSON Array	是	JSON Patch 补丁文档，数组中的每一项代表一个操作。

字段	类型	是否必填	说明
resourceType	String	是	FHIR 资源类型，本示例为 `Patient`。当前实例实际支持的全部资源类型，请通过 `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。

错误码	说明
400 Bad Request	补丁文档格式错误，或 `path`、`op` 参数非法
401 Unauthorized	未认证，缺少有效身份凭证
403 Forbidden	已认证但无更新该资源的权限
404 Not Found	指定资源不存在
409 Conflict	资源状态冲突，例如目标路径与当前资源状态不匹配
412 Precondition Failed	资源未通过 `RepositoryValidatingInterceptor` 数据校验。常见原因：PATCH 落地后出现空数组字段（如 `remove /address/0` 后未移除整个 `address` 数组）。
415 Unsupported Media Type	`Content-Type` 不受支持，例如未使用 `application/json-patch+json`
422 Unprocessable Entity	补丁语法正确，但未通过业务或 FHIR 规则校验
500 Internal Server Error	服务端内部处理异常

补丁

本页目录：

接口描述

输入参数

输出参数

示例

示例一：新增性别字段

请求示例

响应示例

示例二：新增地址信息

请求示例

响应示例

示例三：替换邮编和出生日期

请求示例

响应示例

示例四：删除地址数组中的第一个元素

请求示例

响应示例

示例五：校验后删除地址信息

请求示例

响应示例

示例六：开启数据校验时清空数组字段

请求示例

响应示例

错误码