【已评审】UpdateService 资源新增 MultipartHttp 方式

Interface SIG Interface评审
1

背景

  • 客户的运维场景中使用 Redfish UpdateService 资源进行固件升级，固件升级时需要支持使用 MultipartHttpPushUri 属性明确升级的方法
  • MultipartHttpPushUri 从 UpdateService 1.6.0 版本引入，在 Redfish 固件更新中相较于早期的 HttpPushUri 更清晰，行为更明确；从 openUBMC 生态角度来讲也建议进行资源升级和支持

关联ISSUE

无

整体方案

  • GET 请求：Redfish UpdateService 的 GET 请求中新增标准属性 MultipartHttpPushUri，值为固定的 URI（/redfish/v1/UpdateService/update-multipart）
  • POST 请求：对于使用 MultipartHttpPushUri 的固件更新请求 /redfish/v1/UpdateService/update-multipart，在 POST 的请求格式约束为 multipart/form-data，数据分为两部分：
    1. UpdateFile：更新的固件以及上传的格式；
    2. UpdateParameters： 一个 JSON 字符串，包含 Targets 等升级指令参数
  • 资源协作接口：对于满足后续 MultipartHttpPushUri 的定制化诉求，需要在资源协作接口中增加 MultipartUriSuffix 属性

评审点1：UpdateService 新增标准属性 MultipartHttpPushUri

资源URI ：/redfish/v1/UpdateService
资源版本 ：UpdateService.v1_16_0

属性名 类型 示例/取值约束 readonly 易变属性 实现PATCH 操作权限 描述
MultipartHttpPushUri string(URI) 取决于后端对于 MultipartUriSuffix 的配置然后进行拼接，如：/redfish/v1/UpdateService/update-multipart true 否 否 ReadOnly The URI used to perform a Redfish Specification-defined multipart HTTP or HTTPS push update to the update service.

评审点2：新增支持 MultipartHttpPushUri 的 POST 方法

注意： MultipartHttpPushUri 资源是一个字符串属性，指向的内容称为一个属性端点，不是标准的 Action，所以不需要 Action 和 Schema

资源URI：具体由 MultipartHttpPushUri 属性值指定，当前固定值为/redfish/v1/UpdateService/update-multipart
资源版本：UpdateService.v1_16_0
操作权限：BasicSetting
请求参数：

  • Request Headers： Content-Type: multipart/form-data
  • Request Body (multipart/form-data)： 至少包含两个字段：
  • UpdateFile：要上传的固件文件数据。
  • UpdateParameters：一个 JSON 字符串，包含更新指令。其结构通常如下：
{
  "Targets": ["/redfish/v1/UpdateService/FirmwareInventory/...组件URI..."],
  "@Redfish.OperationApplyTime": "OnStartUpdateRequest",
  "ForceUpdate": false,
  "Oem": {}
}

响应参数：

对于 MultipartHttpPushUri 的响应直接通过 HTTP 响应码进行体现，具体响应码说明如下：

  • 200 Accepted，请求成功，并且在响应的 header 中增加一个 Location 属性，标注当前请求任务的 Task URI（如：/redfish/v1/TaskService/Tasks/123）；请求 body 不是强制项，可以不要（待决策，完整请求体见附录1）
  • 400 Bad Request 请求无效，请求体中的字段不合法（比如：不是json格式）
  • 401 Unauthorized 未授权，请求未提供身份验证凭据
  • 403 Forbidden 禁止访问，请求权限不足
  • 404 Not Found 未找到，没有实现服务端或者URI不匹配
  • 405 Method Not Allowed 方法不允许，请求使用的是非 POST 方法
  • 413 Payload Too Large，请求体中的 multipart 的内容超过了服务支持的最大值
  • 415 Unsupported Media Type 不支持的媒体类型，请求中的 Content-Type 不是 multipart
  • 500 Internal Server Error 内部服务器错误
  • 503 Service Unavailable 服务不可用

评审点3：UpdateService 资源协作接口增加属性 MultipartUriSuffix

变更描述：当前接口表征 openUBMC 支持的升级能力，新增属性 MultipartUriSuffix 同属于升级能力的一部分，并且支持北向 Redfish 接口展示以及升级能力
接口链接： bmc.kepler.UpdateService 接口定义

变更属性

变更类型 属性名称 签名 只读 变化通知 属性描述 访问权限 属性来源 持久化类型 变更影响
新增 MultipartUriSuffix s false false 固件更新支持Multipart方式的URI后缀，默认值：update-multipart R: ReadOnly
W: BasicSetting		 掉电持久化 无影响，新增属性

附录

附录1： MultipartHttpPushUri 的响应完整体

HTTP/1.1 202 Accepted
Location: /redfish/v1/TaskService/TaskMonitors/123
...

{
  "@odata.id": "/redfish/v1/TaskService/TaskMonitors/123",
  "@odata.type": "#Task.v1_4_3.Task",
  "Id": "123",
  "Name": "Firmware Update Task",
  "TaskState": "Running",
  "StartTime": "2024-01-01T00:00:00Z",
  "PercentComplete": 0,
  "Messages": []
}

评审结论

通过，具体结论如下：

  1. 同意 Redfish UpdateService 资源新增标准属性 MultipartHttpPushUri，资源版本 UpdateService.v1_16_0；属性类型为 string，只读，非易变属性。
  2. 同意 Redfish UpdateService 新增 POST 方法，方法 URI 具体由 MultipartHttpPushUri 属性值指定，当前固定值为/redfish/v1/UpdateService/update-multipart，资源版本 UpdateService.v1_16_0；操作权限为 BasicSetting，请求和响应见评审点 2；响应采用带有响应体的方式，响应体中带有对应的 POST 请求成功的 Task 信息。
  3. 同意资源协作接口 bmc.kepler.UpdateService 新增属性 MultipartUriSuffix，表征固件更新资源属性 MultipartHttpPushUri 的后缀；属性签名为 s，属性支持读写，读权限为 ReadOnly，写权限为 BasicSetting；属性不需要发送变更通知，设置之后需要掉电持久化。

遗留问题

无

2

李四光：header 中 Location 支持定制，标准实现需要结合当前 openUBMC 的 TaskService 的 URI