HL7中国发布订阅框架实施指南
2025.03.10 - release

HL7中国发布订阅框架实施指南 - Local Development build (v2025.03.10) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

交易

在本交互规范的当前版本定义了如下7个交易：

注册订阅主题

本交易由通知代理和发布者角色使用。注册订阅主题(IST-SUB-001)交易用于

调用地址:

POST http://[base]/SubscriptionTopic

请求消息

消息体定义参见BaseSubscriptionTopic：

  • 应含有一个全球唯一标识以指代当前的订阅主题。
  • 应至少含有一个触发器：
    • 资源触发器
    • 事件触发器
  • 可含有一个过滤器
  • 可含有一个事件内容设置，以确定在事件中应包含哪些资源。

这里提供了一个参考示例，具体格式和内容参见表单填报就绪订阅主题资源示例页面。

响应消息

  • 使用状态码201 Create标识整个请求处理成功。
  • 订阅代理根据订阅主题的全球唯一标识(url)来判定当前订阅主题是否存在：
    • 如果未存在，则接受该资源并进行后续处理，最后返回状态码 201 Created。
    • 如果存在，可直接返回状态码 201 Created，从而使客户端看起来好像已经创建新资源，即使该资源实际上是预先存在的资源。

订阅

本交易由通知代理和订阅者角色使用。订阅(IST-SUB-002)交易用于订阅者向通知代理发出订阅请求消息。

调用地址:

POST http://[base]/Subscription

请求消息

消息体定义和示例参见BaseSubscription：

  • 应含有一个订阅主题
  • 应指定通知的通道类型
  • 应指定通知内容的形式

这里提供了一个参考示例，具体格式和内容参见表单填报订阅资源示例页面。

响应消息

响应消息反馈了提交订阅请求后的处理结果，应遵循如下约束条件：

  • 使用状态码201 Create标识整个请求处理成功。
  • 订阅成功后，返回的订阅资源状态取值应为status=requested
  • 如果处理失败，参见错误处理章节描述。

取消订阅

本交易由通知代理和订阅者角色使用。取消订阅(IST-SUB-003)交易用于当不再需要订阅时，订阅者向通知代理发出取消订阅请求消息。

此操作为满足业务需求而自定义的操作。操作的定义参见取消订阅的结构说明。

调用地址:

PUT http://[base]/Subscription/[id]/$cancel

请求消息

消息体为空。

响应消息

订阅不可修改、不可删除。修改Subscription.status为off表示取消。

通知代理应取消相应的订阅。

查询订阅

本交易由通知代理和订阅者角色使用。查询订阅(IST-SUB-004)交易用于订阅者从通知代理获取符合查询条件的订阅。

调用地址:

GET http://[base]/Subscription

请求消息

查询参数表示为一系列的name-value对，这些name-value对表示查询的筛选器，在本规范中需支持：

params description mapping
status 订阅的状态 Subscription.status
name 订阅的名称 Subscription.name
topic 订阅的主题 Subscription.topic
type 订阅的通道类型 Subscription.channelType

响应消息

响应消息应返回符合查询条件的资源结果集，应遵循如下约束条件：

  • 使用状态码200 OK标识整个请求处理成功。
  • 返回Bundle资源，其中包含零到多个Subscription资源。
  • 如果执行失败，参见错误处理章节描述。

获取订阅状态

本交易由通知代理和订阅者角色使用。获取订阅状态(IST-SUB-005)交易用于订阅者从通知代理获取指定订阅的运行状态。

调用地址:

GET http://[base]/Subscription/[id]/$status

请求消息

消息体为空。

响应消息

响应消息应返回指定标识订阅的运行状态，应遵循如下条件：

  • 使用状态码200 OK标请求处理成功。
  • 返回消息体应为Bundle资源（type=searchset），且应包含一个SubscriptionStatus资源记录订阅的运行状况。
  • 如果处理失败，参见错误处理章节描述。

这里提供了一个参考示例，具体格式和内容参见获取订阅状态返回消息示例页面。

通知

本交易由通知代理和通知接收者角色使用。通知(IST-SUB-006)交易用于从通知代理向通知接收者发送有关与现有订阅匹配的事件的通知。

接收通知的服务端点与订阅的Subscription.endpoint保持一致。

调用地址:

POST http://[notify_rest_hook_endpoint]

请求消息

消息体定义和示例参见NotifynMessage：

  • Bundle资源的元素type=subscription-notification
  • 应含有唯一一个SubscriptionStatus资源，且位于首位。
  • 基于通知类型：
    • 事件通知 应含有一到多个事件关注的资源（由SubscriptionStatus.event引用）
    • 握手通知/心跳通知 无其它资源

响应消息

  • 成功接收到通知后，直接返回200 OK状态码）。
  • 无消息体。

发布

本交易由通知代理和发布者角色使用。发布(IST-SUB-007)交易用于从发布者向通知代理提供有关可能具有订阅事件的消息。

调用地址:

POST http://[base]/notify

请求消息

消息体定义和示例参见PublishMessage。

发布的消息和通知的消息基本一致，都是采用通知类型的容器（Bundle.type=subscription-notification），但是仍存在如下区别：

  • 发布的消息中事件只有一个，而通知的消息中事件是存在多个，可以批量推送。
  • 因发布者对订阅是无感的，所以在通知消息中的SubsciptionStatus资源里无法提供订阅的引用。

响应消息

  • 成功时，消息头返回200 OK状态码。
  • 无消息体。

错误处理

订阅异常错误消息的定义和示例参见SubscribeOperationOutcome。

当处理流程出现错误时：

  • 使用状态码4xx和5xx标识整个请求处理失败
  • 响应消息体使用OperationOutcome资源代替Bundle资源。

下表给出了details的取值：

代码 说明
TopicNotSupportedFault 订阅消息引用了通知代理不支持的主题
InvalidFilterFault 订阅消息过滤器的过滤参数不被通知代理理解或支持。
ChannelNotSupportedFault 订阅消息使用了通知代理不支持的通道类型。
SubscribeCreationFailedFault 通知代理未能处理订阅消息。