【已评审】并行升级新增webreset接口评审

Interface SIG Interface评审
1

背景：为支持并行升级web人机接口，需要新增webrest接口：

评审点一： UI/Rest/BMCSettings/UpdateService接口响应体中新增UpgradeMode属性，表征当前处于哪种升级模式

说明：web页面有选择“并行模式”按钮，如果进行页面切换并切回固件管理页面后，需要知道当前是否正处于串行或并行模式中；

uri：UI/Rest/BMCSettings/UpdateService
变化类型：新增属性
操作类型： GET
应用场景：web切换到固件升级页面后，查询当前升级模式以供页面显示
详细描述：响应参数添加下表属性

属性名称 取值类型 说明 取值范围 默认值 操作权限 约束
UpgradeMode string 当前升级模式 “Serial”
“Parallel”		 “Serial” ReadOnly 无

为实现上述webrest接口，需要在UpdateService类下面新增属性

资源path：/bmc/kepler/UpdateService
资源interface：bmc.kepler.UpdateService
变化类型：新增属性
应用场景：web切换到固件升级页面后，查询当前升级模式以供页面显示，需要提供资源协作接口
持久化类型： 不持久化
操作权限：只读属性，ReadOnly
详细描述：见下表

属性名称 变化类型 签名 访问权限 持久化 变化通知 属性值来源 说明 是否允许为null 约束
UpgradeMode 新增属性 s 读：ReadOnly
写：不涉及		 无 false 组件设置 当前升级模式 否 取值：“Serial”, “Parallel”

评审点二：新增webrest接口，用于查询并行升级所有固件的升级状态及进度

说明：web界面处于并行升级模式时，需要展示各个固件的升级状态及进度等相关信息，如果每次调用只能查询一个任务的状态的话，需要反复例测10+接口，会有性能问题，故需要增加一个接口用于统一查询所有固件的升级状态信息；

uri：/UI/Rest/BMCSettings/UpdateService/UpdateProgress
变化类型：新增uri
操作类型： GET
应用场景：升级页面获取正在升级固件列表用于web展示
请求参数：{}
响应参数：见下表
操作权限：ReadOnly

属性名称 取值类型 说明 取值范围 默认值 是否允许为null 约束
UpgradeMode string 当前升级模式 “Serial”
“Parallel”		 “Serial” 否 无
UpgradeTasks array 正在升级的固件列表 json对象，具体见下表 空表 否 无

UpgradeTasks对象参数说明如下：

名称 取值 取值说明 取值样例
TaskName String 任务名称
Percentage String 升级进度（百分比） 8%
TaskState String 升级状态，具体取值如下：
Pending：挂起状态
Running：正在升级
Warning：升级异常
Completed：升级完成)		 Running
ErrorCode int32 错误码，取值如下：
1：升级固件异常
2：升级文件不存在
3：无效的升级固件
4：内存不足
8：先下电之后才能升级
9：固件版本不匹配
12：升级固件和设备类型不匹配
13：不支持升级BIOS
27：升级版本和WEB不匹配
28：设备状态不支持固件升级
70：升级固件太旧		 1
Component String 升级的固件类型 CPLD
FileName String 升级的文件名称 image.hpm

样例展示：

URL: /UI/Rest/BMCSettings/UpdateService/UpdateProgress
操作类型：GET
请求参数：{}
响应消息体举例：
{
    "UpgradeMode"：String,   // 取值范围： "Serial", "Parallel"
    "UpgradeTasks": [
        {
            "TaskName": String,
            "Percentage": String, // 示例："8%"
            "TaskState": String,   // 取值范围： "Pending", “Running", "Warning", "Completed"
            "ErrorCode": Number,
            "Component": String,
            "FileName": String
        },
        {
            "TaskName": String,
            "Percentage": String,   // 示例："8%"
            "TaskState": String,
            "ErrorCode": Number,
            "Component": String,
            "FileName": String
        },
        {
            "TaskName": String,
            "Percentage": String,   // 示例："8%"
            "TaskState": String,
            "ErrorCode": Number,
            "Component": String,
            "FileName": String
        }
    ]
}

评审点三：新增webrest统一生效接口，用于“开始生效按钮触发生效”：

说明：由于固件生效需要复位BMC、下电OS等条件，该控制动作要由用户来选择，BMC不能直接操作，故通过参数让用户做决定，本次生效可以做什么样的控制操作。

uri：/UI/Rest/BMCSettings/UpdateService/StartActive
变化类型：新增uri
操作类型： POST
应用场景：统一生效页面一键触发生效
请求参数：见下表
操作权限：有"PowerOff"选项：BasicSetting与PowerMgmt；无"PowerOff"选项：BasicSetting

属性名称 取值类型 说明 取值范围 默认值 是否允许为null 约束
ActivationActions array 生效控制方式 “ResetBMC”
“PowerOff”		 空表 否 无

响应参数：通用任务uri

示例：

// "ActivationControl"为空数组，代表为了生效固件可以复位BMC或者下电OS；ResetBMC：复位BMC；PowerOff：整机下电；
URL: /UI/Rest/BMCSettings/UpdateService/StartActive
操作类型：POST
请求参数：
{ 
    //  "ActivationActions"为可选参数，取值："ResetBMC"、"PowerOff"
     "ActivationActions": [
         "ResetBMC",
         "PowerOff"
    ]
}
响应消息体举例：
{"url":"/UI/Rest/Task/1"}

评审点四：新增查询待生效固件状态接口，用于查询有哪些待生效固件以及固件的生效状态：

uri：UI/Rest/BMCSettings/UpdateService/PendingFirmwareList
变化类型：新增uri
操作类型： GET
应用场景：生效页面获取正在生效固件列表用于web展示
请求参数：{}
响应参数：见下表
操作权限：ReadOnly

属性名称 取值类型 说明 取值范围 默认值 是否允许为null 约束
PendingFirmwareList array 待生效的固件列表 json对象，具体见下表 空表 否 无

样例展示：

UI/Rest/BMCSettings/UpdateService/PendingFirmwareList
操作类型：GET
请求参数：
{}
响应消息体举例：
{
    "PendingFirmwareList": [
        {
            "SystemId": 1,
            "FirmwareType": "firmware_type", // 固件类型
            "ActiveStatus": "active_status", // 生效状态
            "ActiveAction": "active_action", // 生效动作
        }
    ]
}

PendingFirmwareList对象参数说明如下：

属性名字段 取值 中文
SystemId number(0~255)
FirmwareType BMC/CPLD/BIOS/VRD/MCU -
ActiveStatus ToBeActivated/Activating/Activated 待生效/生效中/已生效
ActiveAction ResetBMC/PowerOff 重启BMC/整机下电

评审结论

通过，具体结论如下：

  • 评审点1：同意在webrest接口 UI/Rest/BMCSettings/UpdateService 响应中新增属性 UpgradeMode，同意在资源协作接口bmc.kepler.UpdateService下新增属性UpgradeMode， 取值范围均限定为 ["Serial", "Parallel"]
  • 评审点2：同意在webrest接口 /UI/Rest/BMCSettings/UpdateService/UpdateProgress GET操作的响应中增加并行升级的子任务信息属性 UpgradeTasks，类型为 数组
  • 评审点3：同意在webrest接口 /UI/Rest/BMCSettings/UpdateService/StartActive POST操作的请求中增加可选参数 ActivationActions，类型为 数组，请求中不包含ActivationActions时按照全部取值处理（即同时包含"ResetBMC"、“PowerOff”）
  • 评审点4：同意新增待生效固件列表webrest接口 UI/Rest/BMCSettings/UpdateService/PendingFirmwareList，操作类型为 GET