帮你快速理解、总结文档立即下载
文档中心>腾讯健康数据服务>API 文档>Bundle 请求接口>事务内 Patch

事务内 Patch

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

我的收藏

本页目录：

接口描述

用于在事务 Bundle 中执行补丁更新操作。客户端可将 FHIR Patch 文档作为 Bundle 条目的一部分提交，由服务端在事务执行过程中对指定资源进行局部更新。
当使用 FHIR Patch 时，补丁文档通常放置在 Bundle.entry.resource 中。若使用 JSON Patch，则通常需要将补丁内容封装在 Binary 资源后再放入条目资源中。条目请求方法固定为 PATCH。

输入参数

参数名称
类型
是否必填
说明
HTTP Method
String
是
固定为 POST。
URL
String
是
Bundle 提交地址，通常为 [baseUrl]。
Authorization
String
是
身份认证令牌，格式为 Bearer <AccessToken>，AccessToken 通过 调用方式 中的 GetAccessToken 接口获取（实例控制台场景可通过 GetWebAccessToken 接口获取）。
Content-Type
String
否
请求体 MIME 类型，写入类请求通常为 application/fhir+json；未指定时服务端将根据请求内容自动推断。
Request Body
JSON Object
是
包含 Patch 条目的事务 Bundle。
请求体主要字段说明：
字段
类型
是否必填
说明
resourceType
String
是
固定为 Bundle。
type
String
否
处理模式。取值为 transaction（事务模式，所有条目作为一个原子事务执行，任一条目失败则整体回滚）或 batch（批处理模式，各条目独立执行，互不影响）。
entry
Array
是
Patch 条目列表。
entry[].resource
Object
是
FHIR Patch 文档内容。使用 FHIR Patch 时为 Parameters 资源，包含补丁操作类型、路径和值；使用 JSON Patch 时需将补丁内容封装在 Binary 资源中。
entry[].request.method
String
是
固定为 PATCH。
entry[].request.url
String
是
需要执行补丁更新的资源路径，格式为 [resourceType]/[id]，例如 Patient/123。

输出参数

接口调用成功后，通常返回 HTTP 状态码 200 OK，并在响应头中包含内容类型及请求追踪信息，响应体一般为结果 Bundle，包含各条目执行状态及资源版本信息。
响应头示例说明：
参数名称
类型
说明
Status Code
Integer
成功时返回 200 OK。
Location
String
Bundle 响应资源地址，格式为 [baseUrl]/Bundle/[bundleId]。
Content-Location
String
Bundle 响应资源当前版本地址。
Content-Type
String
响应体 MIME 类型，通常为 application/fhir+json。
x-request-id
String
请求追踪 ID。
响应体主要字段说明：
字段
类型
说明
resourceType
String
返回资源类型，通常为 Bundle。
id
String
Bundle 资源的唯一标识。
type
String
响应 Bundle 类型，事务模式返回 transaction-response，批处理模式返回 batch-response。
link
Array
链接信息列表，包含与当前 Bundle 相关的导航链接。
link[].relation
String
链接关系类型，如 self（指向当前请求地址）。
link[].url
String
链接地址。
entry
Array
各 Patch 条目的执行结果。
entry[].response.status
String
Patch 执行状态。
entry[].response.location
String
更新后资源位置。
entry[].response.etag
String
资源版本标识。
entry[].response.outcome
Object
操作结果详情，包含 OperationOutcome 资源，描述条目执行的具体结果信息。

示例

请求示例

POST /INSTANCE_ID/fhir HTTP/1.1
Host: HOSTNAME
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "operation",
            "part": [
              { "name": "type",  "valueCode": "replace" },
              { "name": "path",  "valueString": "Patient.gender" },
              { "name": "value", "valueCode": "male" }
            ]
          },
          {
            "name": "operation",
            "part": [
              { "name": "type",  "valueCode": "replace" },
              { "name": "path",  "valueString": "Patient.identifier" },
              { "name": "value", "valueIdentifier": { "system": "http://new-system", "value": "0001" } }
            ]
          }
        ]
      },
      "request": { "method": "PATCH", "url": "Patient/__PID__" }
    }
  ]
}

响应示例

HTTP/1.1 200 OK
Location: https://HOSTNAME/INSTANCE_ID/fhir/Bundle/<BUNDLE_ID>
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Bundle/<BUNDLE_ID>
Content-Type: application/fhir+json
x-request-id: <REQUEST_ID>
{
  "resourceType": "Bundle",
  "id": "<BUNDLE_ID>",
  "type": "transaction-response",
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir"
    }
  ],
  "entry": [
    {
      "response": {
        "status": "200 OK",
        "location": "Patient/123/_history/2",
        "etag": "2",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "informational",
              "details": {
                "coding": [
                  {
                    "system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
                    "code": "SUCCESSFUL_PATCH",
                    "display": "Patch succeeded."
                  }
                ]
              },
              "diagnostics": "Successfully patched resource \\"Patient/123/_history/2\\"."
            }
          ]
        }
      }
    }
  ]
}

错误码

常见错误码如下，更多错误码请参见 错误码。
错误码
说明
400 Bad Request
Patch 文档格式错误，或补丁路径不合法
401 Unauthorized
未认证，缺少有效身份凭证
403 Forbidden
已认证但无执行 Patch 操作的权限
404 Not Found
条目中的目标资源不存在
422 Unprocessable Entity
Patch 语法正确，但未通过业务或规则校验
500 Internal Server Error
服务端内部处理异常

中国站