Welcome to Firefly
Switch language
Switch language
Firefly Docsss
Last Updated: 2026-08-26 17:51:06

升级管理资源

升级管理资源用于查询固件和升级任务、上传本地固件，以及对 BMC 或子板执行固件升级。

认证与权限

本页接口支持 HTTP Basic Auth 和会话 Token。Token 通过请求头 X-Xsrf-Token 携带。升级任务、BMC 自升级和分片上传等操作需要 OemUpgrade 权限。

2 升级操作

2.1 查询升级队列 ActionInfo

项目内容
方法GET
路径/redfish/v1/UpdateFwService/Actions/UpdateFwServiceActionInfo
成功状态码200 OK
使用 Token 查询升级队列参数
curl --header 'X-Xsrf-Token: <token>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/Actions/UpdateFwServiceActionInfo'

响应示例

200 OK·实机响应
{
  "@odata.id": "/redfish/v1/UpdateFwService/Actions/UpdateFwServiceActionInfo",
  "@odata.type": "#ActionInfo.v1_1_2.ActionInfo",
  "Id": "UpdateFwServiceActionInfo",
  "Name": "UpdateFwService Action Info",
  "Parameters": [
    {
      "DisallowedInput": false,
      "AllowablePattern": "",
      "DataType": "String",
      "Name": "ImageURI",
      "Required": true
    },
    {
      "DisallowedInput": false,
      "AllowablePattern": "",
      "DataType": "StringArray",
      "Name": "Targets",
      "Required": true
    },
    {
      "DisallowedInput": false,
      "AllowablePattern": "",
      "AllowableValues": [
        "CIFS",
        "FTP",
        "SFTP",
        "HTTP",
        "HTTPS",
        "SCP",
        "TFTP",
        "NFS",
        "LOCAL"
      ],
      "DataType": "String",
      "Name": "TransferProtocol",
      "Required": false
    },
    {
      "DisallowedInput": false,
      "AllowablePattern": "",
      "AllowableValues": [
        "Rockchip",
        "Novauto",
        "Qualcomm",
        "M_Nvidia",
        "Spacemit"
      ],
      "DataType": "String",
      "Name": "Platform",
      "Required": true
    },
    {
      "DisallowedInput": false,
      "AllowablePattern": "",
      "DataType": "Boolean",
      "Name": "RewriteMac",
      "Required": false
    }
  ]
}

响应字段

字段类型说明
@odata.idstringActionInfo 资源路径。
@odata.typestringActionInfo 资源类型。
IdstringActionInfo 资源标识。
NamestringActionInfo 资源名称。
Parametersarray升级队列操作的参数列表。
Parameters[].DisallowedInputboolean是否禁止输入该参数。
Parameters[].AllowablePatternstring参数允许的匹配模式。
Parameters[].AllowableValuesarray参数可选值；仅部分参数返回。
Parameters[].DataTypestring参数数据类型。
Parameters[].Namestring参数名。
Parameters[].Requiredboolean是否必填。

2.2 添加升级队列任务

项目内容
方法POST
路径/redfish/v1/UpdateFwService/Actions/UpdateFwService.SimpleUpdate
所需权限OemUpgrade
成功状态码200 OK
使用 Token 添加本地升级任务
curl --request POST \
  --header 'X-Xsrf-Token: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "ImageURI": "<firmware-file-name>",
    "Targets": ["<target-id>"],
    "TransferProtocol": "LOCAL",
    "Platform": "<platform>",
    "RewriteMac": false
  }' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/Actions/UpdateFwService.SimpleUpdate'

请求字段

字段类型必填说明
ImageURIstring是固件文件名或网络 URI。具体形式由 TransferProtocol 决定。
Targetsarray是升级目标 ID 列表，例如 bmc 或 sub01。
TransferProtocolstring否传输协议：CIFS、FTP、SFTP、HTTP、HTTPS、SCP、TFTP、NFS 或 LOCAL。
Platformstring是目标平台。必须从 2.1 当前实机返回的 AllowableValues 中选择。
RewriteMacboolean否是否重写 MAC 地址的请求值。当前后端还会根据目标设备是否存在已分配 MAC 地址决定实际行为。

响应示例

以下为实机返回的 V1 成功响应。本次使用空 Targets 数组验证响应格式，未创建实际升级任务。

200 OK·实机响应
{
  "error": {
    "@Message.ExtendedInfo": [
      {
        "@odata.type": "#Message.v1_1_1.Message",
        "Message": "UpdateFwService Interface Collection",
        "MessageArgs": [],
        "MessageId": "Base.1.11.0.Success",
        "MessageSeverity": "OK",
        "Resolution": "None"
      }
    ],
    "code": "code",
    "message": "#Message.v1_1_1.Message"
  }
}

响应字段

字段类型说明
errorobjectV1 兼容响应容器。虽然字段名为 error，但内部 MessageId 表示成功。
error.@Message.ExtendedInfoarrayRedfish Message 详细信息。
error.@Message.ExtendedInfo[].@odata.typestringRedfish Message 类型。
error.@Message.ExtendedInfo[].Messagestring升级队列操作消息。
error.@Message.ExtendedInfo[].MessageArgsarray消息参数。
error.@Message.ExtendedInfo[].MessageIdstring消息标识；成功时为 Base.1.11.0.Success。
error.@Message.ExtendedInfo[].MessageSeveritystring消息严重程度。
error.@Message.ExtendedInfo[].Resolutionstring后续处理建议。
error.codestringV1 兼容代码，当前固定返回 code。
error.messagestringV1 兼容消息类型。

Targets 不得为空

当前后端只校验 Targets 字段是否存在，空数组也会返回成功，但不会为任何目标添加升级任务。客户端必须在请求前校验数组非空。

2.3 查询 BMC 自升级 ActionInfo

项目内容
方法GET
路径/redfish/v1/UpdateFwService/Actions/UpdateFwServiceSelfUpdateActionInfo
成功状态码200 OK
使用 Token 查询 BMC 自升级参数
curl --header 'X-Xsrf-Token: <token>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/Actions/UpdateFwServiceSelfUpdateActionInfo'

响应示例

200 OK·实机响应
{
  "@odata.id": "/redfish/v1/UpdateFwService/Actions/UpdateFwServiceSelfUpdateActionInfo",
  "@odata.type": "#ActionInfo.v1_1_2.ActionInfo",
  "Id": "UpdateFwServiceActionInfo",
  "Name": "UpdateFwService Action Info",
  "Parameters": [
    {
      "DisallowedInput": false,
      "AllowablePattern": "",
      "DataType": "String",
      "Name": "ImageURI",
      "Required": true
    }
  ]
}

响应字段

字段类型说明
@odata.idstringActionInfo 资源路径。
@odata.typestringActionInfo 资源类型。
IdstringActionInfo 资源标识。
NamestringActionInfo 资源名称。
ParametersarrayBMC 自升级参数列表。
Parameters[].DisallowedInputboolean是否禁止输入该参数。
Parameters[].AllowablePatternstring参数允许的匹配模式。
Parameters[].DataTypestring参数数据类型。
Parameters[].Namestring参数名，当前为 ImageURI。
Parameters[].Requiredboolean是否必填。

2.4 执行 BMC 自升级

项目内容
方法POST
路径/redfish/v1/UpdateFwService/Actions/UpdateFwService.SelfUpdate
所需权限OemUpgrade
成功状态码200 OK
使用 Token 执行 BMC 自升级
curl --request POST \
  --header 'X-Xsrf-Token: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "ImageURI": "<locally-visible-firmware-path>"
  }' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/Actions/UpdateFwService.SelfUpdate'

请求字段

字段类型必填说明
ImageURIstring是BMC 本机可直接访问的固件文件路径。后端会查询文件所在块设备、UUID 和挂载点。

成功响应结构

成功时返回与 2.2 相同的 V1 嵌套 Message 结构。由于该操作会写入引导配置并触发 BMC 升级，本次未执行成功路径。

200 OK·后端成功响应结构
{
  "error": {
    "@Message.ExtendedInfo": [
      {
        "@odata.type": "#Message.v1_1_1.Message",
        "Message": "UpdateFwService Interface Collection",
        "MessageArgs": [],
        "MessageId": "Base.1.11.0.Success",
        "MessageSeverity": "OK",
        "Resolution": "None"
      }
    ],
    "code": "code",
    "message": "#Message.v1_1_1.Message"
  }
}

响应字段

响应字段与 2.2 的“响应字段”相同。

实机失败路径已验证

传入不存在的 ImageURI 时，实机返回 400 Bad Request，error.@Message.ExtendedInfo 为 the file path is not natively visible。

高风险操作

执行升级可能重启目标设备或中断当前服务。提交前必须先查询 ActionInfo，确认镜像、平台、传输协议和目标设备匹配。

1 升级状态与固件

1.1 查询升级任务列表

查询 BMC 和各子板当前的升级任务状态以及整体进度。

项目内容
方法GET
路径/redfish/v1/UpdateFwService/UpdateFwServiceTasksLists
认证HTTP Basic Auth 或 X-Xsrf-Token
所需权限OemUpgrade
成功状态码200 OK
查询升级任务列表
curl --user '<username>:<password>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/UpdateFwServiceTasksLists'

响应示例

以下是实机返回的核心字段节选。当前设备还包含 sub02 至 sub10，它们的结构与 sub01 相同。

200 OK·真实响应节选
{
  "TasksLists": {
    "bmc": {
      "Target": "",
      "TaskUID": 0,
      "TaskState": {
        "En": "",
        "Zh_CN": ""
      },
      "StartTime": "",
      "TaskPercentage": 0,
      "Message": null
    },
    "sub01": {
      "Target": "",
      "TaskUID": 0,
      "TaskState": {
        "En": "",
        "Zh_CN": ""
      },
      "StartTime": "",
      "TaskPercentage": 0,
      "Message": null
    }
  },
  "TaskPercentage": 0
}

响应字段

字段类型说明
TasksListsobject按目标 ID 组织的升级任务映射。
TasksLists.{target}object指定目标的升级任务信息，例如 bmc 或 sub01。
TasksLists.{target}.Targetstring任务目标 ID；无任务时为空字符串。
TasksLists.{target}.TaskUIDinteger升级任务唯一标识；无任务时为 0。
TasksLists.{target}.TaskStateobject多语言任务状态。
TasksLists.{target}.TaskState.Enstring英文任务状态。
TasksLists.{target}.TaskState.Zh_CNstring中文任务状态。
TasksLists.{target}.StartTimestring任务开始时间。
TasksLists.{target}.TaskPercentageinteger指定目标的任务进度，范围为 0～100。
TasksLists.{target}.Messagearray | null升级日志消息列表；无任务时可为 null。
TaskPercentageinteger当前所有可计算任务的平均进度。

1.2 查询指定目标升级状态

项目内容
方法GET
路径/redfish/v1/UpdateFwService/{target-id}/Actions/Oem/Firefly/UpdateFwService.ServiceInfo
路径参数target-id，例如 bmc 或 sub01
所需权限OemUpgrade
成功状态码200 OK
使用 Token 查询 BMC 升级状态
curl --header 'X-Xsrf-Token: <token>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/bmc/Actions/Oem/Firefly/UpdateFwService.ServiceInfo'

响应示例

200 OK·实机响应
{
  "Target": "",
  "TaskUID": 0,
  "TaskState": {
    "En": "",
    "Zh_CN": ""
  },
  "StartTime": "",
  "TaskPercentage": 0,
  "Message": null
}

响应字段

字段类型说明
Targetstring升级目标 ID。
TaskUIDinteger升级任务标识。
TaskStateobject多语言任务状态。
TaskState.Enstring英文任务状态。
TaskState.Zh_CNstring中文任务状态。
StartTimestring任务开始时间。
TaskPercentageinteger任务进度，范围为 0～100。
Messagearray | null升级日志消息列表。

1.3 查询本地固件列表

项目内容
方法GET
路径/redfish/v1/UpdateFwService/LocalFirmwareLists
成功状态码200 OK
使用 Token 查询本地固件列表
curl --header 'X-Xsrf-Token: <token>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/LocalFirmwareLists'

响应示例

200 OK·实机响应
{
  "FirmwareLists": [
    {
      "name": "CS-B1-3576-JD4-SUB-MINIMAL_Rk3576_debug_260602.img"
    },
    {
      "name": "CS-B1-rk3576-jd4-sub_Android14_HDMI_260605.img"
    }
  ],
  "Types": null
}

响应字段

字段类型说明
FirmwareListsarrayBMC 本地固件目录中的文件列表。
FirmwareLists[].namestring固件文件名，可用于本地升级或删除操作。
Typesarray | null固件类型列表；当前实现返回 null。

1.4 查询可用升级固件路径

查询升级上传目录中的 .img 文件。该接口与 1.3 读取的固件目录不同，两个响应不一定一致。

项目内容
方法GET
路径/redfish/v1/UpdateFwService/Actions/UpdateFwService.FirmwarePath
所需权限OemUpgrade
成功状态码200 OK
使用 Token 查询可用升级固件路径
curl --header 'X-Xsrf-Token: <token>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/Actions/UpdateFwService.FirmwarePath'

响应示例

200 OK·实机响应
{
  "Id": "UpdateFwServiceActionInfo",
  "Name": "UpdateFwService Action Info",
  "Parameters": []
}

响应字段

字段类型说明
Idstring资源标识。
Namestring资源名称。
Parametersarray可用固件列表。每个元素包含 Path 和 Name；当前实机目录为空。
Parameters[].Pathstring固件文件的绝对路径。
Parameters[].Namestring固件文件名。

1.5 删除本地固件

项目内容
方法DELETE
路径/redfish/v1/UpdateFwService/LocalFirmwareLists/{firmware-id}
路径参数firmware-id，从 1.3 返回的 FirmwareLists[].name 获取
请求体无
成功状态码200 OK
使用 Token 删除本地固件
curl --request DELETE \
  --header 'X-Xsrf-Token: <token>' \
  '<protocol>://<device-ip>:<port>/redfish/v1/UpdateFwService/LocalFirmwareLists/<firmware-id>'

响应示例

200 OK
{
  "@odata.type": "#Message.v1_1_1.Message",
  "Timestamp": "1785836138",
  "MessageId": "Base.1.11.0.Success",
  "Message": "The request completed successfully.",
  "MessageArgs": [],
  "MessageSeverity": "OK",
  "Severity": "",
  "Oem": null,
  "RelatedProperties": null,
  "Resolution": "None"
}

响应字段

字段类型说明
@odata.typestringRedfish Message 类型。
Timestampstring服务端生成消息时的时间戳。
MessageIdstring成功消息标识。
Messagestring操作结果描述。
MessageArgsarray消息参数。
MessageSeveritystring消息严重程度。
Severitystring兼容严重程度字段。
Oemobject | nullOEM 扩展信息。
RelatedPropertiesarray | null相关资源属性。
Resolutionstring后续处理建议。

删除不可恢复

接口会直接删除 BMC 上的固件文件，并尝试清理关联的解包缓存。本次仅使用不存在的文件名验证了路由和错误响应，未删除现有固件。

Switchs资源

Previous Page

On this page

升级管理资源
2 升级操作
2.1 查询升级队列 ActionInfo
响应示例
响应字段
2.2 添加升级队列任务
请求字段
响应示例
响应字段
2.3 查询 BMC 自升级 ActionInfo
响应示例
响应字段
2.4 执行 BMC 自升级
请求字段
成功响应结构
响应字段
1 升级状态与固件
1.1 查询升级任务列表
响应示例
响应字段
1.2 查询指定目标升级状态
响应示例
响应字段
1.3 查询本地固件列表
响应示例
响应字段
1.4 查询可用升级固件路径
响应示例
响应字段
1.5 删除本地固件
响应示例
响应字段