6. 协议细节

Redfish可扩展平台管理的应用程序接口是基于 REST 与 OData 来达成互操作的可用性，如同OData-协议所定义的：OData-JSON 是定义于JSON payload，OData-Schema是一种机械可读的表示法。此该要包含了注解 (annotation) 可以让支持 JSON 的工具，对 JSON进行验证与解析。下面的通用标准与协议增加了互操作性与对现有工具链的借用。

为了达成客戶端解析最少的元數據，Redfish遵循了最低的OData标准。

在这份文档中，我们提到的Redfsih是以一种协议对应到数据模型。更精确的来说，HTTP 是应用协议用来传递讯息而 TCP/IP 是一个传输的协议。RESTful 界面是用来映像讯息协议。为了简化来说，我们将会用 RESTful 来对应 HTTP、TCP/IP 与其他协议，传输与讯息层将使用 Redfish 协议。

Redfish 协议是基于因特网服务来设计，且对于用户接口与自动化操作的网络与可操作性来如是。此接口是基于REST模式语法来设计。

在 Redfish 中，HTTP 方法被用来当作一般的 CRUD* 操作与取得Header信息。

动作 (Actions) 是来用扩展CRUD类型的操作，应该被限制使用。

媒体类型 (Media types) 是来用指示讯息内容的类型。

HTTP 状态代码是用来指示服务器对于请求的处理。延伸的错误处理是用来响应更多的错误讯息。

发送安全的讯息是很重要的，此檔的安全章节会描述指定的TLS要求。

有些同步操作可能相当耗时。请确认在架构中包含异步的设计。

6.1 使用HTTP

HTTP 是適合RESTful 介面。此節將描述HTTP如何再HTTP之上如何使用Redfish介面與其約束來保證Redfish的實作相容性。

• 6.1.1 统一资源标志符 (URI)

  统一资源标志符是用来表示特定资源，且包含基本服务与全部的 Redfish 资源。

• 统一资源标志符对于资源来讲必须是唯一的。
• 统一资源标志对于客户端来说是不透明的，所以客户端不应该尝试去理解或是解构。 为了开始一个操作，客户端必须知道资源的统一资源标志符
• 执行 GET 操作会取得资源的属性与其相关资源的链接 基本的资源统一资源标志符是基于协议版本约定好的。探索其他资源的统一资源标志符是透过之前响应内容中的相关资源链接。轮巡统一资源标志符的API的种类为超媒体API。

统一资源标志符对于资源是独一无二的识别符。对于统一资源标志符Redfish包含了3个部分且描述于 RFC3986中。 统一资源标志的第一个部分包含定义与授权。第二部分包含了根服务与版本。第三部分是唯一的资源标志符。 举例来说，下列的统一资源标志符：

https://mgmt.vendor.com/redfish/v1/Systems/1

• 第一个部分是定义与授权 (https://mgmr.vendor.com)。
• 第二个部分是根服务与版本 (/redfish/v1)
• 第三个部分是唯一的资源标志符 (System/1)

统一资源标志符中的定义与授权不应该被当成唯一的资源标志符中的一部分。这是因为复位向能力与本机操作可能会导致不同的联机。统一资源标志符的其余部分 (服务与资源位置)对于服务本身是唯一的，且对于全部的Redfish返回结果都是如此。

• 统一资源标志符中的唯一的资源标志符在实作中是唯一的。 举例来说，POST操作可能会在标头中回传 Location（用来表示这是透过POST新建立的资源）

  /redfish/v1/Systems/2

假设客户端连接到 “mgmt.vendor.com” 装置，那完整的统一资源标志符为https://mgmt.vendor.com/redfish/v1/Systems/2。

就像再 RFC3986中描述的统一资源标志符，可能包含查询（?qurey）与锚点（#frag）的部分。查询会在查询章节中被谈及，锚点将会在服务器端被忽略。

6.1.2. HTTP 方法

RESTful 有个吸引人的特性是只支持极少数的操作。下列表格描述了一般性的操作对应到HTTP的方法。如果列中包含了必备的值为 “是”，那么Redfish 接口应该支持此HTTP方法

其他的HTTP方法是不被允许的，且客户端应该收到一个405的响应。

6.1.3 HTTP重定向

HTTP重定向允许一个服务通过重定向请求到另外一个URL上。从另一方面讲，这使得Redfish资源可以别名化数据模型的区域。

• 所有Redfish客户端应该正确的处理HTTP重定向 注意：有关于HTTP重定向的安全问题在安全章节进行说明

6.1.4 媒体类型

有些资源可能不止有一种展现类型。这种展现类型是通过媒体类型来指明。 在HTTP消息中，媒体类型是在Content-Type头中说明的。通过设置一系列可接收的媒体类型在HTTP接收头中，客户端可以告诉服务它想要的响应的确切媒体类型，。

• 所有资源应是以JSON媒体类型“application/json”方式可用的
• Redfish服务应使每个资源都可以基于JSON的方式来展现，如RFC4627中规范的。接收者不应拒绝以JSON进行编码的消息，并且应该提供至少一种基于JSON的响应展现方式。一个实现可能会提供额外的不是JSON媒体类型的展现方式。 客户端可能会通过指定请求中的Accept-Encoding头来要求进行数据压缩。
• 如果是客户端发起的GET请求，响应数据应该始终被压缩。
• 当请求是来自客户端时，服务应该支持gzip压缩。

6.1.5 ETags

为了减少不必要的RESTfull访问资源的情况，Redfish服务应该为每个资源关联一个独立的ETag。

• 具体实现支持为每一个资源返回ETag属性
• 具体实现应该支持为每一个响应（用于展现单独资源）返回ETag头。具体实现应该支持为每一个确切的请求和响应返回ETag头如安全章节里列的那样。 ETag被产生并被作为资源有效负载的一部分提供是因为服务具有最佳的位置来了解一个对象的新版本是否具有足够不同。这里有两种ETag类型：弱与强。
• 弱模式 -- 只有对象的“重要”部分会被包含ETag的规划中。具体实例，元数据如最后一次修改时间不应被包含在ETag产生方式中。那些可以决定ETag变化的“重要”属性包括可写的设置和可变的属性，如UUID， FRU数据，序列号等。
• 强模式 -- 对象的所有部分都被包含在ETag的规划中。 本规范没有规定特定的算法用于创建ETag，但是ETag们应该是高度不会发生碰撞的。一个ETag会是一个哈希值，一个产生方式ID，一个时间戳或是某些其他的值-当对象发生变化时它也随着改变。 如果客户端对资源进行PUT或PATCH操作，它应该包含一个ETag，该ETag位于之前的GET操作获取到的HTTP If-Match或If-None-Match头当中。 另外对于每一个资源上返回的ETag属性有：
• Redfish服务应该返回ETag头当客户端进行PUT/POST/PATCH操作时
• Redfish服务应返回ETag头当对一个独立的资源进行GET操作时 ETag头的格式如下：

  ETag W/"<string>"
  

6.2 协议版本

协议版本是从资源版本或是Redfish架构版本中分离出来的。Redfish协议的每一个版本都是强类型的。它通过Redfish服务的URI与URI所对应的资源来完成的，我们称之为服务根（ServiceRoot）。 用于表示Redfish协议的版本根URI应该是这样的“/redfish/v1/”。 在URI里面展现的是协议的主版本号，如Redfish架构定义的那样，协议的主版本号，次版本号以及修正版本号通过服务根资源的版本（Version）属性来表达。协议版本字符串格式如下： 主版本号.次版本号.修正版本号 相关的定义如下：

• 主版本号 = 整数：类中的某些内容以向后不兼容的方式发生了修改。
• 次版本号 = 整数：对应小更新。新功能可能已经被添加但没有东西被删除。在兼容性上保持与上一版本的次版本兼容。
• 修正版本号 = 整数：在先前版本中的某些内容被破坏并且需要修复。 任何通过访问根服务或任何服务或引用的资源而发现的资源，应该确保与根服务所支持的协议是相同的版本。 一个在服务"/redfish"上的GET请求应该返回如下的响应体：

  {
    "v1": "/redfish/v1/"
  }
  

6.3 Redfish已定义的（Redfish-Defined）URI和相关的URI规则

Redfish是具有一个小型的已定义的URI集合的超媒体API。所有其他资源都是透过根服务提供的不可见的URI来进行访问的。以下是一个Redfish服务所支持的已定义的URI列表：

另外上表中的结尾部分不带反斜线的URI应被重定向到关联的Redfish已定义的URI上，或与带反斜线的URI等价，如：

如果服务不选择重定向而是按相同的API来处理它们，那么所有被用于该服务相关的URI都应该从/redfish/v1/开始。

6.4 请求

本节将描述可发送给Redfish服务的请求信息。

6.4.1 请求头

HTTP定义了可以被用于请求消息中的头信息。下表定义了这些头以及它们对于Redfish服务的需求：

• 如果下表中的“需要”列的内容为“是”，那么Redfish服务应该理解并能够处理这些头内容如HTTP 1.1规范所定义的。
• 如果下表中的“需要”列的内容为“有条件的”，那么Redfish服务应该理解并能够处理这些头内容如HTTP 1.1规范所定义的，但需要注意描述中的注意条件。
• 如果下表中的“需要”列的内容为“不是”，那么Redfish服务应该理解并能够处理这些头内容如HTTP 1.1规范所定义的。（？？为什么跟Yes是一样的描述）

• 如果下表中的“被要求的”列内容为“是”，那么Redfish服务应该理解并能够处理这些头像规范定义的那样：

6.4.2 读请求（GET）

GET方法被用于获取资源的展现信息。这种展现信息既可以是单个资源也可以是一个集合。服务会在接收头中返回一个具体的媒体类型用于这个展现，对于媒体类型的主题要求可以查看媒体类型章节。如果接收头没有出现，服务将以application/json类型来返回资源的展现信息。

• HTTP GET方法应该被用于获取资源，并不应具有任何的边际效应。
• 在GET请求上，服务应该忽略请求体的内容。
• 在资源没发生外部改变时，GET操作应该被屏蔽（idempotent）。

6.4.2.1 服务根请求

用于版本号为1的Redfish服务的根URL应为“/redfish/v1/”。 用于服务的根URL要按照本规范定义来返回一个服务根（ServiceRoot）资源。

6.4.2.2 元数据问题请求

Redfish服务应该在“/redfish/v1/$metadata”的路径上公开一个元数据文档用于表述服务。该文档会描述根上可用的资源与集合，并引用附加的元数据文档来描述服务所公开的资源类型的全集。 在获取元数据文档时服务不应要求进行认证。

6.4.2.3 OData服务文档请求

Redfish服务应该在“/redfish/v1/odata”路径上公开一个OData服务文档。该文档提供了一个标准的格式用于枚举服务所公开的资源，可以启用一般的超媒体驱动(hypermedia-driven)OData客户端在服务的资源上进行导航。 在获取服务文档时服务不应要求进行认证。

6.4.2.4 资源检索请求

客户端发起一个GET请求到URI上用了请求独立资源或资源集合。用于资源或资源集合的URI可能可以通过在之前请求所返回的资源标识符属性中获取（例如，在之前返回资源的链接部分）。服务可能通过对资源的URI追加一个包含属性名的段来支持检索单独属性的惯例，但这并不是必须的。

6.4.2.4.1 查询参数

当资源地址指向的是一个集合时，客户端可以使用以下的分页查询选项来处理返回的结果集。这些分页查询选项应用到集合资源的成员属性。

• 服务应该支持$top和$skip作为查询参数。
• 任何以$符开头的查询参数不被支持时，具体实现应返回501状态码。
• 具体实现应该忽略未知的或者不被支持的查询参数，通常这些参数不是以$符开头的。

6.4.2.4.2 集合获取

获取一个集合是通过发送一个HTTP GET方法到集合的URI来完成的。响应内容会包含一个资源集合展现，它包括集合的属性和集合的成员列表。返回的成员子集被用作客户端分页查询参数。 当一系列请求使用分页查询参数长时间的请求整个成员集合时，规范并不要求具体实现总是返回一个一致的成员集合。如果多个GET请求使用分页查询来获取集合，那么可能会在返回结果中会出现元素丢失或重复的情况。

• 客户端不应该假设URI都是用于资源集合的。
• 获取的集合应该总是具有一个计数属性来指明成员的总个数。
• 如果由于客户端指定了分页查询参数或服务返回部分结果而导致只返回集合中的一部分数据，所有页面的资源总数应该在计数属性中返回。

6.4.3 HEAD

HEAD方法不同于GET方法，它一定不能返回任何的消息体信息。但是，在HTTP头中的所有相同的元数据信息与状态码将会被返回，就如被处理的GET方法一样，也包括认证检查。

• 服务可能支持HEAD方法，目的是为了返回HTTP响应头的表单里的元数据信息。
• 服务可能支持HEAD方法，目的是为了验证链接的有效性。
• 服务可能支持HEAD方法，目的是为了验证资源的可访问性。
• 服务不应该支持HEAD方法的任何其他用途。
• 对于没发生外部修改的资源来说，HEAD方法应该是幂等的。

6.4.4 数据修改请求

客户端进行创建，修改和删除资源都是通过发起适当的Create, Update, Replace或Delete操作，或是调用资源上的某个动作来完成的。如果指定的资源存在但是不支持当前的请求操作，那么服务应返回405状态码。如果客户端状态码（4xx）或服务端状态码（5xx）被返回，那么操作结果不应改变资源任何状态。

6.4.4.1 更新（PATCH）

PATCH方法比较适合用于对于已存在的资源进行更新操作。对于资源修改的内容通常放置于发送的请求体内部。如果属性没有在请求体中指定，那么就不会被PATCH请求直接改变。在更新操作完成后，响应可能既是空内容或一个资源的描述。具体实现可能会根据它的策略来拒绝确定字段上的更新操作，如果是这样的话，那就不应该再采取任何的更新请求。

• 服务应该支持PATCH方法来更新资源。如果资源没有被更新，需要返回405状态码。
• 在服务器端完成响应体内部的信息转换后，服务可能返回一个资源的描述。
• 如果请求中的属性没有被更新，如果当一个属性为只读时，200的状态码应该被返回并带有一个资源的描述。该描述包含一个注解用于具体说明这个不可更新的属性。在这个成功返回的例子中，资源内其他属性可能被更新。
• 如果客户端指定的PATCH方法与集合有冲突，服务应该返回405状态码。
• 如果资源没有发生外部改变，PATCH操作应该是幂等的，尽管原来的ETag值可能不再相匹配。

在PATCH请求内部，具有JSON数组的未修改成员可能会被描述成空JSON对象。 而在Update操作上的OData标记（资源标识符，类型，etag与链接）会被忽略。

6.4.4.2 替换（PUT）

PUT方法用于完全替换一个资源。在请求体里遗漏的那些属性会被重置会默认值。

• 服务可能支持PUT方法用于替换整个资源。如果服务没有实现该方法，应该返回405状态码。
• 在服务端完成响应体内部的信息转换后，服务可能返回一个资源的描述。
• 如果客户端指定的PUT请求违反了集合要求，那么服务应该返回405状态码。
• 在资源没有被外部改变时，PUT操作应该是幂等的，但例外的情况就是ETag的值可能会被操作改变。

6.4.4.3 创建（POST）

POST方法被用于创建一个新资源。POST请求被提交给被创建资源所在的资源集合。 提交一个POST请求到一个用于表达集合的资源等价于提交同样的请求到资源的成员属性。服务如果支持添加成员到集合上，那么也应该支持以下两种形式：

• 服务应该支持POST方法用于创建资源。如果一个服务不准备创建任何资源，那么应返回405状态码。
• POST操作不应是幂等的操作。

创建请求的请求体包含一个被创建对象的描述。服务可以忽略任何服务端控制的属性（如id），这些属性会被服务强制重写。服务应该设置位置（Location）头到新被创建资源的URI中。对于一个成功的创建请求响应是201（已创建）状态码，并且可能包含一个具有新创建资源描述的响应体。

6.4.4.4 删除（DELETE）

删除方法被用于移除一个资源。

• 对于可删除的资源，服务应支持DELETE方法。如果资源不能被删除，应返回405状态码。
• 服务可能会在响应体中返回刚刚删除资源的描述。
• 如果客户端指定的DELETE请求违反了集合要求，服务应返回405状态码。

如果资源已经被删除了，再次进行删除时服务可能会返回404状态码或是一个成功的状态码。

6.4.4.5 动作（POST）

POST方法也被用于对象的初始化操作（如动作）

• 服务应该支持POST方法用于发送动作。
• POST操作可能不是幂等的。 通过发送HTTP POST方法到动作的URI上来请求资源上的定制动作。如果带有资源的动作属性（actions property）没有被目标属性指定，那么动作的URI应是以下格式： ResourceUri/Actions/QualifiedActionName 这里的
• ResourceUri是资源的URL用于支持调用动作的。
• "Actions"是本规范中定义的属性的名字。
• QualifiedActionName是名称空间或动作的限定名的别名。

函数的第一个参数是资源，其上的动作正在被调用。剩余的参数将作为名称/值对出现在请求体中。 客户端可以直接查询一个资源来确定可用的行为与用于这些行为的有效参数值。某些参数信息可能要求客户端对资源进行与Redfish架构相符的检查。 例如，如果一个Redfish架构文档http://redfish.dmtf.org/schemas/v1/ComputerSystem.xml在ComputerSystem名称空间里定义了一个REST动作，并绑定到ComputerSystem.1.0.0.Actions类型上，如下所示：

<Schema Name="ComputerSystem">
  ...
  <Action Name="Reset" IsBound="true">
    <Parameter Name="Resource" Type="ComputerSystem.1.0.0.Actions"/>
    <Parameter Name="ResetType" Type="Resource.ResetType"/>
</Action>
...
</Schema>

并且计算机系统资源包含一个Actions属性如下：

"Actions": {
    "#ComputerSystem.Reset": {
        "target":"/redfish/v1/Systems/1/Actions/ComputerSystem.Reset",
        "[email protected]": [

                "On",
                "ForceOff",
                "GracefulRestart",
                "GracefulShutdown",
                "ForceRestart",
                "Nmi",
                "ForceOn",
                "PushPowerButton"
        ] }
}

然后下面的信息将描述一个可能的请求用于该动作：

POST /redfish/v1/Systems/1/Actions/ComputerSystem.Reset HTTP/1.1
Content-Type: application/json
Content-Length: <computed length>
OData-Version: 4.0
{
    "ResetType": "On"
}

6.5 响应

Redfish定义了四种响应类型：

• 元数据响应 - 描述服务暴露给一般客户端的资源与类型。
• 资源响应 - 一个独立资源的JSON表述。
• 资源集合响应 - 资源集合的JSON表述。
• 错误响应 - 在发送HTTP错误的情况下，作为顶层的JSON响应来提供额外的信息。

6.5.1 响应头

HTTP协议定义了头信息可以被用于响应消息中。下表定义了这些头以及它们对Redfish服务的要求。

• 如果下表的“被要求”列中标志为“是”的条目，Redfish服务应该能够返回对应的头信息，如HTTP1.1规范定义的那样。
• 如果下表的“被要求”列中标志为“否”的条目，Redfish服务应该能够返回对应的头信息，如HTTP1.1规范定义的那样。
• Redfish客户端应该能理解并能处理下表中所有的头信息，如HTTP1.1规范定义的那样。

• 如果下表中“被要求”列的值标志为“是”，Redfish服务应该理解并能够按本规范要求的处理这些头。

6.5.1.1 链接头

链接头提供被访问资源上的元数据信息，并作为HEAD或GET操作的响应返回给客户端。另外用于链接到资源，资源JSON模式的URL返回时应带有rel=describedby。 链接头应该在HEAD上被返回，而满足rel=describedby条件的链接头应在GET或HEAD上被返回。

6.5.2 状态码

HTTP规范定义了响应消息中的允许返回的状态码。 在HTTP状态码显示一次失败的地方，响应体包含一个扩展错误资源来给客户端提供更为有意义的与明确的错误语义。

• 当返回的状态码是400或500的时候，服务将根据本规范描述的在响应体中返回扩展错误资源。
• 当返回的状态码是400或者更大值时，服务应该根据本规范描述的在响应体中返回扩展错误资源。
• 在发生认证失败时，扩展错误资源一定不能提供权限的信息。

注意：有关于错误资源的安全影响请参见安全章节。 以下的表格列举了一些常用的HTTP状态码。在情况适合的时候，其他的状态码可能由服务返回。有关于状态码的描述以及本规范额外的需求请查看表中“描述”列。

• 客户端应按照HTTP1.1规范的定义以及本规范中对附加需求的约束条件定义来理解并处理下表中的状态码。
• 服务将响应带有适当的状态码给客户端。
• 操作产生的异常将被映射到HTTP状态码。
• Redfish服务不应返回100的状态码。除非是在上传超大数据的情况下，应该避免使用HTTP协议来进行多遍的数据传输。

6.5.3 元数据响应

元数据为普通用户描述资源，集合，能力以及服务依赖的行为，它包括OData客户端工具和本规范中未具体规定的应用程序。如果客户端对目标服务已经有了足够的了解，那么他们就不需要再请求元数据了， 例如根据本规范的定义来请求并解析一个资源的JSON展现内容。

6.5.3.1 服务元数据

服务元数据根据OData规范来描述顶层资源与服务的资源类型。Redfish服务的元数据表现为一个带有根元素“Edmx”的XML文档。该元素定义在http://docs.oasis-open.org/odata/ns/edmx名称空间中，并且OData的版本属性为4.0。

<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0"> <!-- edmx:Reference and edmx:Schema elements go here -->
</edmx:Edmx>

6.5.3.1.1 引用其他模式

服务元数据应包括用于每一个Redfish资源类型上的名称空间，这些名称空间沿用“RedfishExtensions.1.0.0”的方式。这些引用可能使用标准Uri来托管Redfish模式的定义（如http://redfish.dmtf.org/schema）或是一个对应Redfish模式的本地版本号的Url，该版本应与托管的版本相同。

<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/AccountService.xml"> <edmx:Include Namespace="AccountService"/>
<edmx:Include Namespace="AccountService.1.0.0"/>
</edmx:Reference>
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/ServiceRoot.xml">
    <edmx:Include Namespace="ServiceRoot"/>
    <edmx:Include Namespace="ServiceRoot.1.0.0"/>
</edmx:Reference>
...
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/VirtualMedia.xml"> <edmx:Include Namespace="VirtualMedia"/>
<edmx:Include Namespace="VirtualMedia.1.0.0"/>
</edmx:Reference>
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/RedfishExtensions.xml">
    <edmx:Include Namespace="RedfishExtensions.1.0.0" Alias="Redfish"/>
</edmx:Reference>

服务元数据应包含一个实体容器，它定义了顶层资源与集合。该实体应该扩展至ServiceRoot.1.0.0模式中定义的ServiceContainer，并且可能包含额外的资源或集合。

<edmx:DataServices>
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Service">
<EntityContainer Name="Service" Extends="ServiceRoot.1.0.0.ServiceContainer"/> </Schema>
</edmx:DataServices>

6.5.3.1.2 引用OEM扩展

元数据文档可能会引用附加的规范文档来描述服务所使用的特定的OEM扩展，例如用于附加集合的定制化类型。

<edmx:Reference Uri="http://contoso.org/Schema/CustomTypes">
    <edmx:Include Namespace="CustomTypes"/>
</edmx:Reference>

6.5.3.1.3 注解

服务可以注解集合，类型，动作和带有Redfish定义的参数或定制化的注解术语。这些注解通常位于一个独立的Annotation文件中。这些注解通过使用IncludeAnnotation指令在服务元数据文档内被引用：

<edmx:Reference Uri="http://service/metadata/Service.Annotations"> <edmx:IncludeAnnotations TermNamespace="Annotations.1.0.0"/>
</edmx:Reference>