HL7中国批量数据导出服务实施指南
2026.01.23 - release

HL7中国批量数据导出服务实施指南 - Local Development build (v2026.01.23) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

## ITS-BULK-001 批量数据导出

### 概述

本交易由`批量数据服务提供商`和`批量数据服务客户端`角色使用，用于启动导出数据操作的异步作业。

批量数据导出的类型有三种：

- 患者级导出：所有患者的数据
- 组级导出：通过Group资源导出患者子集的数据
- 系统级导出：所有类型的数据。

服务端应支持以FHIR 异步请求模式执行此操作。

服务端应支持GET请求。可选支持POST请求，通过Parameters资源提供参数。

返回资源中的引用可以是格式为`<resource type>/<id>`的相对URL，也可以是基于导出服务器根地址的绝对URL，它们是等价的。

#### 服务端点

该操作旨在获取所有患者的相关资源：

    [fhir base]/Patient/$export

该操作旨在获取指定患者子集的相关资源：

    [fhir base]/Group/[id]/$export

无论资源是否与患者关联，都可以使用如下操作从服务器根地址导出：

    [fhir base]/$export

#### 请求消息头部字段

- `Accept` (string)

  指定返回消息的格式。目前，仅支持`application/fhir+json`。客户端调用时应提供这个请求头部字段。如果省略，服务器可以返回错误，也可以采用默认值处理。

- `Prefer` (string)

  客户端应在该请求头部字段中设置参数`respond-async`，表示导出作业应异步处理。如果省略，服务器可以返回错误，也可以以默认的异步方式处理。

  客户端还可以在该请求头部字段中设置第二个参数`separate-export-status`，形如：`Prefer: respond-async,separate-export-status`。如果包含该参数且服务器支持，服务器应返回响应头部字段`Preference-Applie: respond-async,separate-export-status`。

  当导出请求中设置了参数`separate-export-status`，且服务器支持，批量数据状态响应消息中的HTTP状态码应反映状态请求本身，而非导出作业本身。在这种情况下，当批量数据状态操作响应消息的HTTP状态码为`200 OK`时，响应消息还应包含一个头部字段`X-Export-Status`，反映导出作业状态的HTTP状态码。

#### 查询参数

- `_outputFormat`（String类型）

  默认为`application/fhir+ndjson`。服务器应支持NDJSON格式，但也可以支持其它输出格式。该值还可以接受缩写形式：`application/ndjson`和`ndjson`。

- `_since`（instant类型）

  如果资源的状态在指定的时间之后发生变化，则响应消息中应包含该资源。例如：`Resource.meta.lastUpdated`比 `_since`时间晚。

  在组级导出中，如果资源与添加到组中的患者相关，服务器可能会返回在提供时间之前修改过的额外资源（服务器应明确记录此行为）。

  服务器还可以返回被资源引用的资源，无需考虑这些被引用资源的`lastUpdated`。

  对于那些不维护`lastUpdated`的资源，无论客户端提供的`_since`是什么，服务器都会在响应消息中返回这些资源。

- `_until`（instant类型）

  如果资源的状态在给定时间之前发生变化，则响应消息中应包含该资源。例如：`Resource.meta.lastUpdated`比 `_until`时间早。

  服务器还可以返回被资源引用的资源，无需考虑这些被引用资源的`lastUpdated`。

  对于那些不维护最后更新时间的资源，无论客户端提供的`_since`值是什么，服务器都会在响应消息中返回这些资源。

- `_type`（逗号分隔的资源类型字符串）

  可以通过该参数，在响应消息中仅包含指定资源类型的资源。如果省略该参数，服务器应返回所有支持资源。

  对于患者级和组级的请求，患者资源集应作为推荐资源返还的参考点。然而，如果患者资源集以外的资源由返回的资源引用，同时有助于解读患者数据，也可能会被返回（如`Organiztion`和`Practitioner`资源）。

  如果服务器不支持`_type`参数，应返回错误并通过`OperationOutcome`资源携带详细信息，以便客户端重新提交无`_type`参数的请求。

  如果客户端明确要求导出服务器不支持的资源，或只要求患者资源集以外的资源类型，服务器也应返回错误，并通过`OperationOutcome`资源携带详细信息。

- `_typeFilter`（FHIR REST API查询字符串）

  可以使导出响应消息更细粒度地过滤返回资源。例如，客户可能只想检索有效处方而非所有处方，或仅提取实验室观察数据而非所有观察数据。使用`_typeFilter`时，每种资源类型会独立筛选。例如，如果筛选2000年以后出生的`Patient`资源，那么就无法导出2000年以前出生患者的`Encounter`资源。

  基于与临床或行政事件相关的日期过滤资源，例如导出某一时间段内发生的就诊，应使用`_typeFilter`参数，而非`_since`和`_until`参数，因为这些筛选中使用的资源修改日期可能与临床或行政事件的日期不一致。

  FHIR查询参数 如`_sort`、`_include` 和`_elements`不得在`_typeFilter`参数中使用。此外，`_typeFilter`参数中的查询应具有单一FHIR资源类型的上下文 。

  客户端可以在导出请求中多次重复使用`_typeFilter`参数。 当`_typeFilter`查询同一资源类型时，服务器应包含满足任意参数条件的该资源类型中的资源（逻辑“或”）。

  如果服务器不支持`_typeFilter`参数，应返回错误并通过`OperationOutcome`资源携带详细信息，以便客户端重新提交无`_typeFilter`参数的请求。

  请求示例

  以下是`MedicationRequest`资源的导出请求，客户希望进一步限制`MedicationRequest`仅限于`active`的资源，或者2018年7月1日之后`completed`的资源。这可以通过两个`_typeFilter`查询参数和一个`_type`查询参数实现：

  - MedicationRequest?status=active
  - MedicationRequest?status=completed&date=gt2018-07-01T00:00:00Z

        $export?
          _type=
            MedicationRequest
          &_typeFilter=
            MedicationRequest%3Fstatus%3Dactive
          &_typeFilter=
            MedicationRequest%3Fstatus%3Dcompleted%26date%3Dgt2018-07-01T00%3A00%3A00Z

- `organizeOutputBy`（String类型）

  在提供该参数时，支持该参数的服务器应按指定资源类型的实例组织输出文件中的资源，包括参数指定类型中每个资源的头部，随后是输出中包含该资源引用的资源和资源。

  如果被省略，服务器应当用仅有单一类型的资源来组织每个输出文件。详见下方的详细情况 、 示例清单和示例输出文件 。

  无法结构化 `organizeOutputBy` 资源输出的服务器应当返回错误，并返回 `OperationOutcome`资源。

#### 处理逻辑

以下流程图展示了一个处理逻辑，描述服务器应如何处理批量数据导出作业。服务器实际执行的操作及其执行顺序可能不同。此外，根据导出请求提供的参数和头部字段，某些请求可能导致服务器返回错误，而非继续处理请求。

#### 响应 - 成功

- HTTP状态码`202 Accepted`；
- 响应头部字段`Content-Location`应带有端点的绝对URL，用于后续状态请求（轮询位置）；
- 当请求头部字段`Prefer`中提供了`separate-export-status`参数，且服务器支持，则响应消息应包含头部字段`Preference-Applied`，且应包含`respond-async`和`separate-export-status`两个参数。
- 消息体可选携带JSON格式的`OperationOutcome`资源。

#### 响应 - 错误

- HTTP状态码为`4XX`或者`5XX`；
- 消息体应为JSON格式的`OperationOutcome`资源。