文档中心
Redfish Interface Mapping Configuration Guide
更新时间： 2025/08/18
在Gitcode上查看源码

The Redfish interfaces of the openUBMC community are implemented using mapping solutions, which require commands to be configured in the JSON file. The Redfish interface mapping configuration file is in the Redfish directory of the rackmount code repository.

This section describes only the configuration rules of Redfish interfaces. For the common mechanism of interface mapping configuration, see Interface Mapping Configuration.

GET Interface Configuration ​

For the GET interface, you need to configure Type, ResourceExist, Query, RspBody, Statements, and ProcessingFlow.

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

Type (Mandatory) ​

This parameter indicates that the request type is GET.

Configuration Example ​

json
"Type": "GET"

ResourceExist (Optional) ​

If the URI contains a variable slot number, for example, /redfish/v1/Managers/, ResourceExist is required to verify the slot number.

Configuration Example ​

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

Query (Optional) ​

This refers to the query parameters of the GET interface. If a resource includes the query parameters Skip and Top, you can configure their default values using the Query parameter. For example, accessing resource /redfish/v1/Managers/1/LogServices/OperateLog/Entries without using query parameters is equivalent to accessing it with the query parameters: /redfish/v1/Managers/1/LogServices/OperateLog/Entries?$skip=0&$top=32. Here, Skip corresponds to $skip**, and **Top** corresponds to **$top.

NOTE

The Redfish interface validates query parameters using a trustlist. Any query parameters that do not start with `---

The Redfish interfaces of the openUBMC community are implemented using mapping solutions, which require commands to be configured in the JSON file. The Redfish interface mapping configuration file is in the Redfish directory of the rackmount code repository.

This section describes only the configuration rules of Redfish interfaces. For the common mechanism of interface mapping configuration, see Interface Mapping Configuration.

GET Interface Configuration ​

For the GET interface, you need to configure Type, ResourceExist, Query, RspBody, Statements, and ProcessingFlow.

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

Type (Mandatory) ​

This parameter indicates that the request type is GET.

Configuration Example ​

json
"Type": "GET"

ResourceExist (Optional) ​

If the URI contains a variable slot number, for example, /redfish/v1/Managers/, ResourceExist is required to verify the slot number.

Configuration Example ​

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

Query (Optional) ​

This refers to the query parameters of the GET interface. If a resource includes the query parameters Skip and Top, you can configure their default values using the Query parameter. For example, accessing resource /redfish/v1/Managers/1/LogServices/OperateLog/Entries without using query parameters is equivalent to accessing it with the query parameters: /redfish/v1/Managers/1/LogServices/OperateLog/Entries?$skip=0&$top=32. Here, Skip corresponds to $skip**, and **Top** corresponds to **$top.

NOTE

The Redfish interface validates query parameters using a trustlist. Any query parameters that do not start with are ignored, and any that start with `---

The Redfish interfaces of the openUBMC community are implemented using mapping solutions, which require commands to be configured in the JSON file. The Redfish interface mapping configuration file is in the Redfish directory of the rackmount code repository.

This section describes only the configuration rules of Redfish interfaces. For the common mechanism of interface mapping configuration, see Interface Mapping Configuration.

GET Interface Configuration ​

For the GET interface, you need to configure Type, ResourceExist, Query, RspBody, Statements, and ProcessingFlow.

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

Type (Mandatory) ​

This parameter indicates that the request type is GET.

Configuration Example ​

json
"Type": "GET"

ResourceExist (Optional) ​

If the URI contains a variable slot number, for example, /redfish/v1/Managers/, ResourceExist is required to verify the slot number.

Configuration Example ​

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

Query (Optional) ​

This refers to the query parameters of the GET interface. If a resource includes the query parameters Skip and Top, you can configure their default values using the Query parameter. For example, accessing resource /redfish/v1/Managers/1/LogServices/OperateLog/Entries without using query parameters is equivalent to accessing it with the query parameters: /redfish/v1/Managers/1/LogServices/OperateLog/Entries?$skip=0&$top=32. Here, Skip corresponds to $skip**, and **Top** corresponds to **$top.

NOTE

The Redfish interface validates query parameters using a trustlist. Any query parameters that do not start with `---

The Redfish interfaces of the openUBMC community are implemented using mapping solutions, which require commands to be configured in the JSON file. The Redfish interface mapping configuration file is in the Redfish directory of the rackmount code repository.

This section describes only the configuration rules of Redfish interfaces. For the common mechanism of interface mapping configuration, see Interface Mapping Configuration.

GET Interface Configuration ​

For the GET interface, you need to configure Type, ResourceExist, Query, RspBody, Statements, and ProcessingFlow.

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

Type (Mandatory) ​

This parameter indicates that the request type is GET.

Configuration Example ​

json
"Type": "GET"

ResourceExist (Optional) ​

If the URI contains a variable slot number, for example, /redfish/v1/Managers/, ResourceExist is required to verify the slot number.

Configuration Example ​

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

Query (Optional) ​

This refers to the query parameters of the GET interface. If a resource includes the query parameters Skip and Top, you can configure their default values using the Query parameter. For example, accessing resource /redfish/v1/Managers/1/LogServices/OperateLog/Entries without using query parameters is equivalent to accessing it with the query parameters: /redfish/v1/Managers/1/LogServices/OperateLog/Entries?$skip=0&$top=32. Here, Skip corresponds to $skip**, and **Top** corresponds to **$top.

NOTE

The Redfish interface validates query parameters using a trustlist. Any query parameters that do not start with are ignored, and any that start with but are not supported are blocked.

Configuration Example ​

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

RspBody (Mandatory) ​

This parameter is used to define the response body, ensuring what you see is what you get. All response bodies obtained by the GET interface are defined here.

Configuration Example ​

Assume that the response body expected to be obtained by accessing an interface is as follows:

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

The corresponding RspBody is as follows (assuming that UserName needs to be obtained from the resource tree):

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

NOTE

{{OemIentifier}} is the target field for batch field replacement. If the default configuration is used, openUBMC is loaded. For details about the meaning and configuration method, see section Batch Field Replacement in the Multi-Layer Customization.

Statements (Optional) ​

After the data is obtained, it must undergo specific processing operations to ensure readiness for use. For details, see Interface Mapping Configuration.

Configuration Example ​

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

ProcessingFlow (Optional) ​

To obtain resources from the resource tree, you must configure the resource tree mapping. For details, see Interface Mapping Configuration.

Configuration Example ​

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 Interface Configuration ​

For the PATCH interface, you need to configure Type, ResourceExist, LockdownAllow, ReqBody, Statements, and ProcessingFlow.

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

Type (Mandatory) ​

This parameter indicates that the request type is PATCH.

Configuration Example ​

json
"Type": "PATCH"

ResourceExist (Optional) ​

If the URI contains a variable slot number, for example, /redfish/v1/Managers/, ResourceExist is required to verify the slot number.

Configuration Example ​

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

LockdownAllow (Optional) ​

This parameter indicates whether operations are allowed when the system is locked. If the value is true, operations are allowed. If the value is false, operations are not allowed. If this parameter is not set, the default value is false.

Configuration Example ​

json
"LockdownAllow": false

ReqBody (Mandatory) ​

This parameter defines the request body. All request bodies sent by the PATCH interface are defined here.

Configuration Example ​

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 (Optional) ​

After the data is obtained, it must undergo specific processing operations to ensure readiness for use. For details, see Interface Mapping Configuration.

Configuration Example ​

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

ProcessingFlow (Optional) ​

To obtain resources from the resource tree, you must configure the resource tree mapping. For details, see Interface Mapping Configuration.

Configuration Example ​

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
]

Precautions ​

No Need to Define the RspBody for the PATCH Interface ​

You do not need to define the response body RspBody for the PATCH interface. The response body automatically obtains and displays the response body of the GET request in the same URI.

POST Interface Configuration ​

For the POST interface, you need to configure Type, ResourceExist, LockdownAllow, ReqBody, RspBody, Statements, and ProcessingFlow.

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

Type (Mandatory) ​

This parameter indicates that the request type is POST.

Configuration Example ​

json
"Type": "POST"

ResourceExist (Optional) ​

If the URI contains a variable slot number, for example, /redfish/v1/Managers/, ResourceExist is required to verify the slot number.

Configuration Example ​

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

LockdownAllow (Optional) ​

This parameter indicates whether operations are allowed when the system is locked. If the value is true, operations are allowed. If the value is false, operations are not allowed. If this parameter is not set, the default value is false.

Configuration Example ​

json
"LockdownAllow": false

ReqBody (Mandatory) ​

This parameter defines the request body. All request bodies sent by the POST interface are defined here.

Configuration Example ​

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 (Optional) ​

This parameter is used to define the response body, ensuring what you see is what you get. All response bodies obtained by the POST interface are defined here.

Action-Type POST Interface ​

If the URI contains Actions, for example, /redfish/v1/Managers/:managerid/Actions/Oem/openUBMC/Manager.Dump,

When the value of Type in ProcessingFlow is not task:

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

The default response body is as follows:

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."
            }
        ]
    }
}

When the value of Type in ProcessingFlow is 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"
        }
    }
]

The default response body is as follows:

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
        }
    }
}

ActionInfo must be defined for action-type POST interfaces. For details, see the following precautions.

Non-Action POST Interface ​

If the URI does not contain Actions (e.g., /redfish/v1/AccountService/Accounts),

Configuration Example ​

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 (Optional) ​

After the data is obtained, it must undergo specific processing operations to ensure readiness for use. For details, see Interface Mapping Configuration.

Configuration Example ​

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

ProcessingFlow (Mandatory) ​

To obtain resources from the resource tree, you must configure the resource tree mapping. For details, see Interface Mapping Configuration.

Configuration Example ​

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 Interface Configuration ​

For the DELETE interface, you need to configure Type, ResourceExist, LockdownAllow, ReqBody, RspBody, Statements, and ProcessingFlow.

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

Type (Mandatory) ​

This parameter indicates that the request type is DELETE.

Configuration Example ​

json
"Type": "DELETE"

ResourceExist (Optional) ​

If the URI contains a variable slot number, for example, /redfish/v1/Managers/, ResourceExist is required to verify the slot number.

Configuration Example ​

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

LockdownAllow (Optional) ​

This parameter indicates whether operations are allowed when the system is locked. If the value is true, operations are allowed. If the value is false, operations are not allowed. If this parameter is not set, the default value is false.

Configuration Example ​

json
"LockdownAllow": false

ReqBody (Mandatory) ​

This parameter defines the request body. All request bodies sent by the DELETE interface are defined here.

Configuration Example ​

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

RspBody (Optional) ​

This parameter is used to define the response body, ensuring what you see is what you get. All response bodies obtained by the DELETE interface are defined here.

Default Response Body ​

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 (Optional) ​

After the data is obtained, it must undergo specific processing operations to ensure readiness for use. For details, see Interface Mapping Configuration.

Configuration Example ​

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

ProcessingFlow (Optional) ​

To obtain resources from the resource tree, you must configure the resource tree mapping. For details, see Interface Mapping Configuration.

Configuration Example ​

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
]

Special Keywords ​

IgnoreEtags ​

For frequently changed attributes, check the change frequency during Redfish interface adaptation. If the attributes change at the minute or second level, they are considered as frequently changing attributes. The following table lists common frequently changing attributes.

Attribute Type (Attributes with Second- or Minute-Level Changes Need to be Blocked from Being Reported)
Real-time voltage, current, power, and temperature
Network port packet statistics, CPU usage, memory usage, disk usage, used memory (Buffer/Cache/Free), and network port bandwidth usage
Time/Duration/Timestamp
Rotational speed, battery capacity, battery percentage, historical power data, historical temperature data, and historical usage data
Progress, capacity, heat, and energy consumption

Pay attention to the following:

  1. The IgnoreEtags level is the same as the URI level.
  2. The attributes in IgnoreEtags must exist in RspBody.

Configuration Example ​

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": [
                        ...
                    ]
                }
            ]
        }
    ]
}

Precautions ​

ActionInfo ​

If the @Redfish.ActionInfo field is defined in RspBody, the corresponding URI must be configured. For example, if the #VirtualMedia.VmmControl/@Redfish.ActionInfo is defined in /redfish/v1/Managers/:managerid/VirtualMedia/CD, the following information must be configured: /redfish/v1/Managers/${Uri/managerid}/VirtualMedia/CD/VmmControlActionInfo.

Configuration Example ​

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": [
                {
                    ...
                }
            ]
        }
    ]
}