帮你快速理解、总结文档立即下载
文档中心>腾讯健康数据服务>API 文档>Bundle 请求接口>占位符 ID 与引用

占位符 ID 与引用

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

我的收藏

本页目录：

接口描述

用于在同一个事务 Bundle 中建立尚未分配正式资源 ID 的资源之间的引用关系。当客户端在提交前尚不知道目标资源最终 ID 时，可以为资源分配临时占位符 ID，并在同一 Bundle 中通过该占位符完成资源引用。
服务端在处理事务时，会将占位符 ID 解析为实际资源 ID，并自动替换相关引用关系。

输入参数

参数名称
类型
是否必填
说明
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
是
包含占位符 ID 与引用关系的事务 Bundle。
请求 URL 示例：
https://HOSTNAME/INSTANCE_ID/fhir
请求体主要字段说明：
字段
类型
是否必填
说明
entry[].fullUrl
String
否
占位符 ID，通常使用 urn:uuid:{uuid} 形式。当该条目需要被同一 Bundle 内其他条目引用时必须填写；仅创建资源而不被引用时可省略。
entry[].resource
Object
是
对应资源内容。
entry[].resource.subject.reference
String
否
指向其他条目的占位符引用。
entry[].request.method
String
是
条目请求方法，示例为 POST。
entry[].request.url
String
是
条目目标资源路径。
说明：
占位符 ID 应由客户端随机生成。
占位符 ID 仅在当前 Bundle 内部用于建立关联关系。
事务处理完成后，服务端会为新建资源分配正式 ID，并替换引用。

输出参数

接口调用成功后，通常返回 HTTP 状态码200 OK 或201 Created，并在响应头中包含内容类型及请求追踪信息，响应体一般为结果 Bundle，包含实际写入后的资源位置和处理状态。
响应头示例说明：
参数名称
类型
说明
Status Code
Integer
成功时返回 200 OK 或 201 Created。
Content-Type
String
响应体 MIME 类型，通常为 application/fhir+json。
x-request-id
String
请求追踪 ID。
响应体主要字段说明：
字段
类型
说明
resourceType
String
返回资源类型，固定为 Bundle。
id
String
响应 Bundle 的唯一 ID，由服务端生成。
type
String
响应 Bundle 类型，固定为 transaction-response。
link
Array
导航链接，包含指向当前请求地址的 self 链接。
link[].relation
String
链接关系类型，通常为 self。
link[].url
String
链接对应的 URL。
entry
Array
条目执行结果。
entry[].response.status
String
条目执行状态，如 201 Created。
entry[].response.location
String
新资源的实际位置。
entry[].response.etag
String
资源版本标识。
entry[].response.lastModified
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": [
    {
      "fullUrl": "urn:uuid:e16eac01-a5ee-4904-b1c8-f4bd56e338d5",
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {
            "system": "http://acme.org/mrns",
            "value": "013872"
          }
        ],
        "name": [
          {
            "family": "Simpson",
            "given": [
              "Homer"
            ]
          }
        ],
        "gender": "male"
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      "fullUrl": "urn:uuid:499733fe-7ced-4d15-81ce-8a433a1fb71e",
      "resource": {
        "resourceType": "Condition",
        "clinicalStatus": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
              "code": "active"
            }
          ]
        },
        "verificationStatus": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
              "code": "confirmed"
            }
          ]
        },
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/condition-category",
                "code": "problem-list-item",
                "display": "Problem List Item"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "59621000",
              "display": "Essential hypertension"
            }
          ]
        },
        "subject": {
          "reference": "urn:uuid:e16eac01-a5ee-4904-b1c8-f4bd56e338d5"
        }
      },
      "request": {
        "method": "POST",
        "url": "Condition"
      }
    }
  ]
}

响应示例

HTTP/1.1 200 OK
Content-Type: application/fhir+json;charset=UTF-8
Location: https://HOSTNAME/INSTANCE_ID/fhir/Bundle/bundle-response-id
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Bundle/bundle-response-id
x-request-id: <REQUEST_ID>
{
  "resourceType": "Bundle",
  "id": "bundle-response-id",
  "type": "transaction-response",
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir"
    }
  ],
  "entry": [
    {
      "response": {
        "status": "201 Created",
        "location": "Patient/patient-resource-id/_history/1",
        "etag": "1",
        "lastModified": "2022-02-23T10:00:00.000+08:00",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "informational",
              "details": {
                "coding": [
                  {
                    "system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
                    "code": "SUCCESSFUL_CREATE",
                    "display": "Create succeeded."
                  }
                ]
              },
              "diagnostics": "Successfully created resource \\"Patient/patient-resource-id/_history/1\\"."
            }
          ]
        }
      }
    },
    {
      "response": {
        "status": "201 Created",
        "location": "Condition/condition-resource-id/_history/1",
        "etag": "1",
        "lastModified": "2022-02-23T10:00:00.000+08:00",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "informational",
              "details": {
                "coding": [
                  {
                    "system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
                    "code": "SUCCESSFUL_CREATE",
                    "display": "Create succeeded."
                  }
                ]
              },
              "diagnostics": "Successfully created resource \\"Condition/condition-resource-id/_history/1\\"."
            }
          ]
        }
      }
    }
  ]
}

错误码

常见错误码如下，更多错误码请参见 错误码。
错误码
说明
400 Bad Request
占位符 ID 格式错误，或引用路径不合法
401 Unauthorized
未认证，缺少有效身份凭证
403 Forbidden
已认证但无执行 Bundle 操作的权限
409 Conflict
引用关系冲突或资源状态冲突
422 Unprocessable Entity
Bundle 语法正确，但未通过业务或规则校验
500 Internal Server Error
服务端内部处理异常

中国站