8. 服务的细节

8.1 事件

本章节会覆盖订阅以及接收事件消息的REST-based机制。 Redfish服务要求客户端或者管理员去创建接收事项的订阅。当管理员发送一个HTTP POST消息到订阅资源的URI时，一个订阅会被创建。该请求包括事件接收客户端所预期被发送事件的URI与事件类型。当一个事件通过服务被触发时，Redfish服务将随后发送一个事件到这个URI。

服务应该为所有资源的发送事件提供“推送”样式的能力
服务不应“推送”事件（使用HTTP POST）除非一个事件订阅已经被创建。在任意时刻客户端或者服务都可以通过删除订阅的方式来结束该事件流。如果分发任务的错误次数超出了预定的门限值时，服务可能会删除一个订阅。
服务应该给出一个201的HTTP状态码当订阅成功时，并且将HTTP位置头的内容设置成新订阅资源的地址。订阅被持久化并且将会保留住在事件服务重启后。
客户端应该通过发送一个HTTP DELETE消息到订阅资源的URI上来终止一个订阅。
服务可能通过发送一个特别的“订阅已终止”事件作为最后的消息来终止一个订阅。将来关联到该订阅资源的请求将得到一个404的HTTP响应。

在Redfish服务中会生成两种类型的事件-生命周期和警告。生命周期事件产生在资源被创建，被修改或被删除的时候。不是资源上每一次修改都会产生一个事件-这类似于当ETag被改变时，具体实现可能不会为每一个资源的变化发送事件。如果每接收到一个网卡封包或是每次传感器温度变化一度就发送一个事件，那么结果就是事件过多。这里的事件通常是指资源发生了改变，如同任何属性被改变一样。

警告事件发生在当资源需要去指示某些重要变化的时候。它可能直接的或者间接的关联到资源。事件的样式通常采用一个消息注册的方式类似于扩展了错误处理，它会包含一个MessageId。这类事件的例子如当底盘被打开，按钮被推动，线缆没插好或者门限值被超出。这类事件通常无法对应到生命周期事件上，因此它们有着自己的分类。注意：关于事件的安全性隐喻请查看安全章节

8.1.1 消息订阅

客户端通过横越Redfish服务接口来定位事件服务。当事件服务被发现后，客户端通过发送一个HTTP POST到与订阅相关的集合的URL来订阅消息。正如Redfish架构中描述的那样，这应经由根服务来查找。有关于订阅主体的特定语法可以在Redfish架构找到。一旦成功，“订阅”行为应当返回201的HTTP状态码（被创建）并且在响应内的位置头应包含一个URI用于表示新创建的“订阅”资源的位置信息。响应体，如果有的话，应该包含订阅资源相关的展现。发送一个HTTP GET给订阅资源应该返回订阅资源的配置信息。一旦带有服务的订阅被注册成功，客户端就开始接收新的事件，并且不再接收以往的事件。历史事件不会被该服务所保留。

8.1.2 事件消息对象

投递给特定客户端端点的事件消息对象应该包含Redfish事件架构中所描述的那些属性。该事件消息结构体支持一个消息注册表。在消息注册表方法中，消息注册表拥有一系列或一组众以所周知格式定义的MessageIds。这些MessageIds本质上是一些简化，并且它们的大小远小于真实的消息，如此以使得它们可以适用于嵌入式环境。在注册表中，它们依然是一个消息。消息本身可以拥有参数，如严重等级和推荐行为的默认值。 MessageIds属性的内容应该符合如下格式：注册表名.主版本号.次版本号.消息关键字其中：

注册表名是注册表的名称。它应该是Pascal-cased格式的。
主版本号是一个正整数，用于描述注册表的主版本信息
次版本号是一个正整数，用于描述注册表带的次版本信息
消息关键字是注册表中一个人可读的关键字。消息关键字应该是Pascal-cased格式的并且不应该包含空格，句号或者特殊字符。

8.1.3 清除订阅

取消消息的相关订阅，客户端或者管理员只需很简单的发送一个HTTP DELETE请求到订阅资源的URI即可。这里有些可配置的属性是全局设置,用于定义所有事件订阅的行为。在事件服务Redfish架构中查看这些用于参数的细节定义的属性可用来配置服务的行为。

8.2 异步操作

一个服务要支持异步操作将需要实现Task服务和Task资源。 Task服务被用于描述那些处理任务的服务。它包含一个有着零个或者更多任务资源的集合。Task资源被用于描述一个长时间运行的操作，它通常产生于当一个请求需要超过数秒钟时间来处理，如当一个服务被实例化时。客户端将查询任务资源的URI来确定何时任务已经完成并且执行成功。在Redfish架构中的Task结构体包含一个Task的确切结构。信息的类别包括开始时间，结束时间，任务状况（task state），任务状态（task status），和该任务上关联的零个或多个消息。每个任务具有多个可能的状态。确切的状态与它们的语义被定义在了Redfish架构的Task资源中。当客户端请求一个长时间操作时，服务会返回一个202的状态码（已接受）。任何带有202状态码（已接受）的响应应该包括一个位置头，它包含一个任务监视者的URL，并也可能包括一个等待头来说明在查询该操作的状态前客户端需要等待的时间。当对状态监视器进行一个GET请求时，客户端不应在接收头中包含application/http mime类型。一个202（已接收）的响应体应该包含一个Task资源的实例来描述任务的状态。正如在进程内操作那样，当查询状态监视器的返回时，服务应该持续的在位置头中返回202（已接收）状态码。一旦操作完成，状态监视器应该返回OK（200）的状态码并且包含初始化操作的头和响应体，就好像它已经同步的完成那样。如果初始化操作发生错误，响应体应包含一个错误响应（Error Response）。服务可能会返回410（丢失）的状态码，当操作已完成并且服务已经删除了该任务。客户端可以继续去获取信息，通过使用在202（已接受）响应体中的资源标识符（resource identifier）来直接的查询关于Task资源的状态。

支持异步操作的服务应实现Task资源
对于一个异步操作的响应应返回202（已接受）状态码并设置HTTP响应头中的“Location”为与该活动相关的状态监视器的URI。响应可能也包含一个等待头用于指明客户端在获取到状态前还需要等待的时间。响应体应以JSON的格式来表达Task资源。
对于Task监视器或Task资源的GET请求应无阻塞的返回操作的当前状态。
使用HTTP GET,PUT,PATCH的操作应该总是同步的。
对于HTTP DELETE和HTTP POST请求，客户端应准备好去处理同步和异步两种响应。

8.3 资源树的稳定性

资源树被定义为URI的集合与带有具体实现的数组元素，它必须在单一服务上是一致的，能跨设备重启和A/C电源循环，还必须允许一定量合理的配置更改（如添加一个适配器到一台服务器）。一个服务上的资源树可能不会在跨设备实例上保持一致。客户端必须遍历数据模型并发现资源来与它们交互。这也意味着某些资源在系统间要保持非常的稳定（如BMC的网络设置）--但它并不是一个架构上的保证。

资源树需要能够在跨服务重启与设备配置小调整上保持稳定，因此URI集合与数组元素索引应该保持连续。
客户端不应该期待资源树在服务实例间是一致的。

8.4 发现

Redfish可扩展平台管理编程接口支持被管理设备的自动发现，它通过使用简单服务发现协议（SSDP）来完成。该协议允许通过高效的网络发现而无需诉诸于ping扫描，路由表查找，或是限制性DNS命名模式。SSDP的使用是可选的，并且如果实现的话，应该允许用户通过‘管理者网络服务（Manager Network Service）’来禁用该协议。发现的目的是使得客户端软件能够定位Redfish兼容的（Redfish-compliant）可管设备。主要采纳的SSDP方式是M-SEARCH查询。Redfish也适当的遵循SSDP扩展与UPnP所使用的命名，诸如Redfish兼容的（Redfish-compliant）系统也可以无冲突的实现UPnP协议。

8.4.1 UPnP兼容性

为了兼容一般的SSDP客户端软件，主要的UPnP，TCP端口1900应该被用于所有的SSDP传输。另外，用于SSDP多播消息的Time-to-Live（TTL)跳跃数设置默认值应为2.推荐的方式是设备也要使用恰当的描述符与XML文档来响应UPnP根设备的M-SEARCH查询（带有NT:upnp:rootdevice）。

8.4.2 USN格式

在USN字段中提供的UUID应与用于管理器实现Redfish服务所返回的UUID相等。如果有多个/冗余的管理器，该UUID应保持不变即便发生了冗余故障转移。唯一ID应以‘::dtmf-org’的形式存在于规范的UUID格式中。

8.4.3 M-SEARCH响应

被管理设备必须响应来自于客户端为了查找Redfish服务的查找目标（ST）的M-SEARCH查询，该客户端具有指向Redfish根服务URI的AL。Redfish设备也应该响应查询目标（ST）类型为“ssdp:all”的M-SEARCH查询。 Redfish服务根查询目标（ST）格式为：URN:dmtf-org:service:redfish-rest:1 答复中的URN应使用一个为‘redfish-rest:’的服务名称，其后紧跟一个Redfish规范的主版本号。如果服务所遵循的Redfish规范的次版本号是非零值，并且该版本号是为了向后兼容之前的小修改，那么次版本号应该被追加并以冒号分隔。例如，一个服务所遵循的Redfish规范版本为“1.4”，则会答复带有一个“redfish-rest:1:4”的服务。一个M-SEARCH多播或单播查询的响应应该符合以下显示的格式。尖括号中的字符是占位符用于替代具体设备值。

HTTP/1.1 200 OK
CACHE-CONTROL:<seconds, at least 1800> ST:urn:dmtf-org:service:redfish-rest:1
USN:uuid:<UUID of Manager>::urn:dmtf-org:service:rest-rest:1 AL:<URL of Redfish service root>
EXT:

8.4.4 通知，活着与关机消息

Redfish设备可能实现了经由UPnP定义的额外的SSDP消息来对软件声明他们的可用性。这种能力，如果被实现，必须允许最终用户能在M-SEARCH响应功能之外来禁用这种传输。这样就允许用户可以以最小的网络传输代价来利用发现功能。