文档中心
Redfish接口映射配置指南
更新时间：2025/08/18
在Gitcode上查看源码

openUBMC社区的Redfish接口采用接口映射配置方案实现，需要将命令配置到json文件中。Redfish接口的接口映射配置文件在rackmount代码仓的redfish路径下。

本篇指导仅介绍Redfish接口独有的配置规则，接口映射配置公共机制可见《接口映射配置》。

GET接口配置 ​

对于GET接口，所需要配置的为Type、ResourceExist、Query、RspBody、Statements、ProcessingFlow。

json
{
    "Uri": "/redfish/v1/Managers/:managerid/DiagnosticService/WorkRecord",
    "Interfaces": [
        {
            "Type": "GET",
            "ResourceExist": {
            },
            "Query": {
            },
            "RspBody": {
            },
            "Statements": {
            },
            "ProcessingFlow": [
            ]
        }
    ]
}

Type（必须配置） ​

表示配置的是GET请求。

配置示例 ​

json
"Type": "GET"

ResourceExist（非必须配置） ​

当Uri中存在可变的槽位号时，如：/redfish/v1/Managers/，需要使用ResourceExist对槽位号进行检查。

配置示例 ​

json
"ResourceExist": {
    "${Statements/IsValidManagersId()}": true
}

Query（非必须配置） ​

表示GET接口的查询参数。 当资源中存在查询参数Skip、Top时，使用Query配置查询参数默认值。 例如不使用查询参数访问资源/redfish/v1/Managers/1/LogServices/OperateLog/Entries时，等效于使用查询参数： /redfish/v1/Managers/1/LogServices/OperateLog/Entries?$skip=0&$top=32，其中Query中的Skip与Top分别对应接口中的skip、top

NOTE

当前Redfish接口查询参数使用白名单校验，将忽略不以$开头的查询参数，以$开头的不支持的查询参数会被拦截

配置示例 ​

json
"Query": {
    "Skip": 0,
    "Top": 32
}

RspBody（必须配置） ​

响应体的定义，做到所见即所得。GET接口所获得的响应体均在此定义。

配置示例 ​

假设访问某接口预期获取到响应体为：

json
{
    "odata.context": "/redfish/v1/$metedata#AccountService/Accounts/Members/$entity",
    "Name": "User Account",
    "UserName": "Administrator",
    "Oem": {
        "openUBMC": {
            "LoginRule": null
        }
    }
}

其对应的RspBody配置为（假设UserName需要从资源树中获取）:

json
{
    "odata.context": "/redfish/v1/$metedata#AccountService/Accounts/Members/$entity",
    "Name": "User Account",
    "UserName": "${ProcessingFlow[1]/Destination/UserName}",
    "Oem": {
        "{{OemIentifier}": {
            "LoginRule": null
        }
    }
}

NOTE

{{OemIentifier}}为批量字段替换的目标替换字段，实际使用时如默认配置，会加载为openUBMC（具体含义和配置方法可见《接口多层级定制》批量字段替换章节）

Statements（非必须配置） ​

数据处理：拿到数据之后，需要做一些加工操作才能使用。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"Statements": {
    "Prop": {
        "Input": "${var}",
        "Step": [
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            },
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            }
        ]
    }
}

PrecessingFlow（非必须配置） ​

当需要访问资源树获取资源时，需要进行资源树映射配置。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"ProcessingFlow": [
    {
        "Type": "Property/Method/List/Task/Paging",
        "Path": "xx",
        "Interface": "xxx",
        "Name" : "xxx",
        "Params": [xxx],
        "Destination": {xxx},
        "Source": {xxx},
        "CallIf": {xxx},
        "Foreach": "xxx"
    },
    xxx
]

PATCH接口配置 ​

对于PATCH接口，所需要配置的为Type、ResourceExist、LockdownAllow、ReqBody、Statements、ProcessingFlow。

json
{
    "Uri": "/redfish/v1/Managers/:managerid/DiagnosticService/WorkRecord",
    "Interfaces": [
        {
            "Type": "PATCH",
            "LockdownAllow": true,
            "ResourceExist": {
            },
            "ReqBody": {
            },
            "Statements": {
            },
            "ProcessingFlow": [
            ]
        }
    ]
}

Type（必须配置） ​

表示配置的是PATCH请求。

配置示例 ​

json
"Type": "PATCH"

ResourceExist（非必须配置） ​

当Uri中存在可变的槽位号时，如：/redfish/v1/Managers/，需要使用ResourceExist对槽位号进行检查。

配置示例 ​

json
"ResourceExist": {
    "${Statements/IsValidManagersId()}": true
}

LockdownAllow（非必须配置） ​

表示配置系统锁定打开状态下操作是否允许的配置选项。 值为true代表操作允许，值为false表示不允许，未配置的默认值为false。

配置示例 ​

json
"LockdownAllow": false

ReqBody（必须配置） ​

请求体定义。PATCH接口所发出的请求体均在此定义。

配置示例 ​

json
"ReqBody": {
    "Type": "object",
    "Required": true,
    "Properties": {
        "UserName": {
            "Type": "string",
            "Required": true,
            "Validator": [
                {
                    "Type": "Enum",
                    "Formula": ["Adminstrator", "root"]
                }
            ]
        },
        "Locked": {
            "Type": "boolean"
        },
        "Oem": {
            "Type": "object",
            "Properties": {
                "openUBMC" {
                    "Type": "object",
                    "Properties": {
                        "LoginInterface": {
                            "Type": "string"
                        }
                    }
                }
            }
        }
    }
}

Statements（非必须配置） ​

数据处理：拿到数据之后，需要做一些加工操作才能使用。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"Statements": {
    "Prop": {
        "Input": "${var}",
        "Step": [
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            },
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            }
        ]
    }
}

PrecessingFlow（非必须配置） ​

当需要访问资源树获取资源时，需要进行资源树映射配置。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"ProcessingFlow": [
    {
        "Type": "Property/Method/List/Task/Paging",
        "Path": "xx",
        "Interface": "xxx",
        "Name" : "xxx",
        "Params": [xxx],
        "Destination": {xxx},
        "Source": {xxx},
        "CallIf": {xxx},
        "Foreach": "xxx"
    },
    xxx
]

注意事项 ​

PATCH接口无需定义响应体RspBody ​

PATCH接口无需定义响应体RspBody,其响应体会自动获取相同Uri中GET请求的响应体进行展示。

POST接口配置 ​

对于POST接口，所需要配置的为Type、ResourceExist、LockdownAllow、ReqBody、RspBody、Statements、ProcessingFlow。

json
{
    "Uri": "/redfish/v1/Managers/:managerid/Actions/Oem/openUBMC/Manager.Dump",
    "Interfaces": [
        {
            "Type": "POST",
            "LockdownAllow": true,
            "ResourceExist": {
            },
            "ReqBody": {
            },
            "RspBody": {
            },
            "Statements": {
            },
            "ProcessingFlow": [
            ]
        }
    ]
}

Type（必须配置） ​

表示配置的是POST请求。

配置示例 ​

json
"Type": "POST"

ResourceExist（非必须配置） ​

当Uri中存在可变的槽位号时，如：/redfish/v1/Managers/，需要使用ResourceExist对槽位号进行检查。

配置示例 ​

json
"ResourceExist": {
    "${Statements/IsValidManagersId()}": true
}

LockdownAllow（非必须配置） ​

表示配置系统锁定打开状态下操作是否允许的配置选项。 值为true代表操作允许，值为false表示不允许，未配置的默认值为false。

配置示例 ​

json
"LockdownAllow": false

ReqBody（必须配置） ​

请求体定义。POST接口所发出的请求体均在此定义。

配置示例 ​

json
"ReqBody": {
    "Type": "object",
    "Required": true,
    "Properties": {
        "Type": {
            "Type": "string",
            "Required": true,
            "Validator": [
                {
                    "Type": "Enum",
                    "Formula": ["Adminstrator", "root"]
                }
            ]
        },
        "Content": {
            "Type": "string",
            "Required": true,
            "Sensitive": true
        }
    }
}

RspBody（非必须配置） ​

响应体的定义，做到所见即所得。POST接口所获得的响应体均在此定义。

action型POST接口 ​

Uri中带有Actions的接口，例如/redfish/v1/Managers/:managerid/Actions/Oem/openUBMC/Manager.Dump

其中，当ProcessingFlow中的Type不为task时

json
"ProcessingFlow": [
    {
        "Type": "Method",
        "Path": "/bmc/kepler/UpdateService",
        "Interface": "bmc.kepler.UpdateService",
        "Name": "Rollback",
        "Params" [
            1,
            "ActiveBMC"
        ]
    }
]

默认响应体为：

json
{
    "error": {
        "code": "Base.1.0.GeneralError",
        "message": "A general error has occurred, See ExtendedInfo for more information.",
        "@Message.ExtendedInfo": [
            {
                "@odata.type": "#Message.v1_0_0.Message",
                "MessageId": "Base.1.0.AccountRemoved",
                "RelatedProperties": [],
                "Message": "The account was successfully removed.",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "No resolution is required."
            }
        ]
    }
}

其中，当ProcessingFlow中的Type为task时

json
"ProcessingFlow": [
    {
        "Type": "Task",
        "Path": "/bmc/kepler/Managers/1/LogServices",
        "Interface": "bmc.kepler.Managers.LogServices",
        "Name": "Dump",
        "Params" [
            0,
            "${ReqBody/Content}"
        ],
        "Destination": {
            "TaskId": "TaskId"
        }
    }
]

默认响应体为：

json
{
    "@odata.context": "/redfish/v1/$metadata#TaskService/Tasks/Members/$entity",
    "@odata.type": "#Task.v1_0_2.Task",
    "@odata.id": "/redfish/v1/TaskService/Task/1",
    "Id": "1",
    "Name": "Export Dump File Task",
    "TaskState": "Running",
    "StartTime": "2017-05-09T16:57:14+00:00",
    "Message": [],
    "Oem": {
        "openUBMC": 
        {
            "TaskPercentage": null
        }
    }
}

action型POST接口必须要进行ActionInfo的定义，具体见下文注意事项中。

非action型POST接口 ​

Uri中不带用Actions的接口，例如/redfish/v1/AccountService/Accounts

配置示例 ​

json
"RspBody": {
    "@odata.context": "/redfish/v1/$metedata#ManagerAccount.ManagerAccount",
    "@odata.id": "/redfish/v1/AccountService/Accounts/${ProcessingFlow[1]/Destination/AccountId}",
    "@odata.type": "#ManagerAccount.v1_0_2.ManagerAccount",
    "Id": "${Statements/Id()}",
    "Name": "User Account",
    "Password": null,
    "UserName": "${ProcessingFlow[2]/Destination/UserName}",
    "RoleId": "${Statements/RoleId()}",
    "Reauthkey": "null",
    "Locked": "${ProcessingFlow[2]/Destination/Locked}",
    "Enabled": "${ProcessingFlow[2]/Destination/Enabled}"
}

Statements（非必须配置） ​

数据处理：拿到数据之后，需要做一些加工操作才能使用。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"Statements": {
    "Prop": {
        "Input": "${var}",
        "Step": [
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            },
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            }
        ]
    }
}

PrecessingFlow（必须配置） ​

当需要访问资源树获取资源时，需要进行资源树映射配置。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"ProcessingFlow": [
    {
        "Type": "Property/Method/List/Task/Paging",
        "Path": "xx",
        "Interface": "xxx",
        "Name" : "xxx",
        "Params": [xxx],
        "Destination": {xxx},
        "Source": {xxx},
        "CallIf": {xxx},
        "Foreach": "xxx"
    },
    xxx
]

DELETE接口配置 ​

对于DELETE接口，所需要配置的为Type、ResourceExist、LockdownAllow、ReqBody、RspBody、Statements、ProcessingFlow。

json
{
    "Uri": "/redfish/v1/AccountService/Accounts/:accountid",
    "Interfaces": [
        {
            "Type": "DELETE",
            "LockdownAllow": true,
            "ResourceExist": {
            },
            "ReqBody": {
            },
            "RspBody": {
            },
            "Statements": {
            },
            "ProcessingFlow": [
            ]
        }
    ]
}

Type（必须配置） ​

表示配置的是DELETE请求。

配置示例 ​

json
"Type": "DELETE"

ResourceExist（非必须配置） ​

当Uri中存在可变的槽位号时，如：/redfish/v1/Managers/，需要使用ResourceExist对槽位号进行检查。

配置示例 ​

json
"ResourceExist": {
    "${Statements/IsValidManagersId()}": true
}

LockdownAllow（非必须配置） ​

表示配置系统锁定打开状态下操作是否允许的配置选项。 值为true代表操作允许，值为false表示不允许，未配置的默认值为false。

配置示例 ​

json
"LockdownAllow": false

ReqBody（必须配置） ​

请求体定义。DELETE接口所发出的请求体均在此定义。

配置示例 ​

json
"ReqBody": {
    "Type": "object",
    "Required": true,
    "Properties": {
        "UserName": {
            "Type": "string",
            "Required": true,
            "Validator": [
                {
                    "Type": "Enum",
                    "Formula": ["Adminstrator", "root"]
                }
            ]
        }
    }
}

RspBody（非必须配置） ​

响应体的定义，做到所见即所得。DELETE接口所获得的响应体均在此定义。

默认响应体 ​

json
{
    "error": {
        "code": "Base.1.0.GeneralError",
        "message": "A general error has occurred, See ExtendedInfo for more information.",
        "@Message.ExtendedInfo": [
            {
                "@odata.type": "#Message.v1_0_0.Message",
                "MessageId": "Base.1.0.AccountRemoved",
                "RelatedProperties": [],
                "Message": "The account was successfully removed.",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "No resolution is required."
            }
        ]
    }
}

Statements（非必须配置） ​

数据处理：拿到数据之后，需要做一些加工操作才能使用。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"Statements": {
    "Prop": {
        "Input": "${var}",
        "Step": [
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            },
            {
                "Type": "xxxx",
                "Formula": "xxxx"
            }
        ]
    }
}

PrecessingFlow（非必须配置） ​

当需要访问资源树获取资源时，需要进行资源树映射配置。 具体配置方法见《接口映射配置》。

配置示例 ​

json
"ProcessingFlow": [
    {
        "Type": "Property/Method/List/Task/Paging",
        "Path": "xx",
        "Interface": "xxx",
        "Name" : "xxx",
        "Params": [xxx],
        "Destination": {xxx},
        "Source": {xxx},
        "CallIf": {xxx},
        "Foreach": "xxx"
    },
    xxx
]

特殊关键字 ​

IgnoreEtags ​

对于频繁变化的属性，在对redfish进行接口适配时需要确认属性变化的频度，如果是分钟级/秒级变化，那么就可以认定为频繁变化的属性。常见的频繁变化属性如下表所示。

属性类型(秒级/分钟级变化的属性需要屏蔽上报)
实时电压、实时电流、实时功率、实时温度
网口报文统计信息、CPU占用率、内存占用率、磁盘占用率、内存占用大小（Buffer/Cache/Free）、网口带宽占用率
时间/时长/时间戳
转速、电池容量、电池电量百分比、功率历史数据、温度历史数据、占用率历史数据
进度、容量、热量、能耗

其中要注意的是： 1、IgnoreEtags的层级与Uri层级相同。 2、IgnoreEtags中的属性必须存在于RspBody中。

配置示例 ​

json
{
    "Resources": [
        {
            "Uri": "/redfish/v1/Managers/:managerid/LogServices/OperateLog",
            "IgnoreEtags": [
                "DataTime"
            ],
            "Interfaces": [
                {
                    "Type": "GET",
                    "ResourceExist": {
                        "${Statements/IsValidManagersId()}": true
                    },
                    "RspBody": {
                        ...
                        "DataTime": "${ProcessingFlow[3]/Destination/DataTime}",
                        ...
                    },
                    "Statements": {
                        ...
                    },
                    "ProcessingFlow": [
                        ...
                    ]
                }
            ]
        }
    ]
}

注意事项 ​

ActionInfo ​

当在RspBody中定义了@Redfish.ActionInfo字段后，必须配置相对应的Uri。 举例：/redfish/v1/Managers/:managerid/VirtualMedia/CD中定义了#VirtualMedia.VmmControl/@Redfish.ActionInfo字段，那么就要配置 /redfish/v1/Managers/${Uri/managerid}/VirtualMedia/CD/VmmControlActionInfo信息。

配置示例 ​

json
{
    "Resources": [
        {
            "Uri": "/redfish/v1/Managers/:managerid/VirtualMedia/CD",
            "Interfaces": [
                {
                    "Type": "GET",
                    "RspBody": {
                        ...
                        "Oem": {
                            "openUBMC": {
                                "Actions": {
                                    "#VirtualMedia.VmmControl": {
                                        "target": "/redfish/v1/Managers/${Uri/managerid}/VirtualMedia/CD/Oem/openUBMC/Actions/VirtualMedia.VmmControl",
                                        "@Redfish.ActionInfo": "/redfish/v1/Managers/${Uri/managerid}/VirtualMedia/CD/VmmControlActionInfo"
                                    }
                                }
                            }
                        }
                    }
                }
            ]
        },
        {
            "Uri": "/redfish/v1/Managers/:managerid/VirtualMedia/CD/VmmControlActionInfo",
            "Interfaces": [
                {
                    ...
                }
            ]
        }
    ]
}
上一篇映射器接口定位指导
下一篇Web Rest接口映射配置指南
版权所有 © 2025 openUBMC 保留一切权利粤A2-20044005号-293
隐私政策|法律声明|关于cookies