【已评审】映射器新增ActionResponseBody语法，用于redfish接口自定义返回信息

Interface SIG Interface评审
1

关联issue

映射器新增ActionResponseBody语法，用于Action类型的redfish接口根据自定义response返回信息

背景

redfish协议升级，如果资源定义了Action Response，则该Action的响应体需要按照定义的Action Response进行返回

决策点

映射器新增ActionResponseBody语法，用于Action类型的redfish接口根据定义的ActionResponseBody返回信息

整体架构/方案

映射器新增ActionResponseBody语法，用于Action类型的redfish接口根据定义的ActionResponseBody返回信息

详细描述

1、方案概述：

映射器新增ActionResponseBody语法，用于Action类型的redfish接口根据定义的ActionResponseBody返回信息

2、自定义action响应体配置示例

{
    "Uri": "/redfish/v1/CertificateService/Actions/CertificateService.GenerateCSR",
    "Interfaces": [
        {
            "Type": "POST",
            "ReqBody": {
                ...
            },
            "ActionResponseBody": {
                "CSRString": "${ProcessingFlow[1]/Destination/CSRString}",
                "Certificate": "${ReqBody/Certificate}"
            },
            "Statements": {
                ...
            },
            "ProcessingFlow": [
                ...
            ]
        }
    ]
}

响应示例

{
    "CSRString": "----BEGIN CERTIFICATE REQUEST-----...----END CERTIFICATE REQUEST------",
    "Certificate": {
        "@odata.id": "/redfish/v1/Managers/BMC/NetworkProtocol/Https/Certifacates/1"
    }
}

3、redfish协议参考：https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.22.0.pdf

3.1、redfish协议描述：

3.1.1只有响应码为200或者201的action类型的Post接口才支持自定义响应体

Table 11 — POST (action) status codes

To indicate HTTP status code HTTP status code
Success, and the action’s schema definition does not contain an action response. 200 OK An error response, with a message that indicates success or any additional relevant messages. If the action was successfully processed and completed without errors, warnings, or other notifications for the client, the service should return the Success message from the Base Message Registry in the code property in the response body.
Success, and the action’s schema definition contains an action response 200 OK The response body conforms to the action response defined in the schema.
A new resource was created, and the action’s schema definition does not contain an action response. 201 Created A Location response header set to the URI of the created resource. An error response, with a message that indicates success or any additional relevant messages. If the action was successfully processed and completed without errors, warnings, or other notifications for the client, the service should return the Success message or Created message from the Base Message Registry in the code property in the response body.
A new resource was created, and the action’s schema definition contains an action response. 201 Created A Location response header set to the URI of the created resource. The response body conforms to the action response defined in the schema.
Additional time is required to process. 202 Accepted A Location response header set to the URI of a task monitor
Success, and the action’s schema definition does not contain an action response. 204 No Content No response body.

3.2、redfish协议示例：

3.2.1、通过配置schema文件来定义响应体
11.2.5.5 Action with a response body
A response body for an action shall be defined using the actionResponse term within the action definition. For example, the following definition defines the GenerateTicket action with a response that contains the definition specified by #/definitions/GenerateTicketResponse .

{
    "GenerateTicket": {
        "actionResponse": {
            "$ref": "#/definitions/GenerateTicketResponse"
        },
        "parameters": {}
    },
    "GenerateTicketResponse": {
        "additionalProperties": false,
        "description": "The response body for GenerateTicket.",
        "properties": {
            "TicketId": {
                "description": "The ticket identifier.",
                "readonly": true,
                "type": "string"
            }
        },
        "required": ["TicketId"],
        "type": "object"
    }
}

In the previous example, the following payload is an example response for the GenerateTicket action.

{
    "TicketId": "40478281bd0f6b9e7131db6c4f673438"
}

评审结论

1、同意映射器新增ActionResponseBody语法，用于Action类型的redfish接口根据定义的ActionResponseBody返回信息
2、需要添加映射器语法校验检查ActionResponseBody语法
3、社区的文档需要添加ActionResponseBody语法的解释