【已评审】新增光模块脏污检测redfish接口、资源协作属性和接口

huangjiapei_o2800 · 2025 年11 月 15 日 06:39

背景

支持光模块脏污检测，包含脏污检测初始化、脏污检测启动、脏污检测查询、脏污检测退出等流程。

关联ISSUE

[需求]: 支持基于OTDR的LPO模块光链路脏污检测流程控制

[需求]: 支持基于OTDR的ODSP模块光链路脏污检测流程控制

[需求]: 支持基于OTDR的光链路脏污检测北向接口

整体方案

1、新增脏污检测对应的redfish接口，包含脏污检测初始化、脏污检测启动、脏污检测查询、脏污检测退出。

2、新增脏污检测对应的资源协作属性、接口，包含脏污检测相关功能。

评审点

1、新增脏污检测初始化、脏污检测启动、脏污检测查询、脏污检测退出的redfish接口.

2、在光模块接口下新增脏污检测对应的资源协作属性、接口，包含脏污检测相关功能。

详细描述

评审点1 SupportedDiagnosticService属性新增取值ContaminationDetection

操作权限：ReadOnly
请求类型：GET
请求URI：/redfish/v1/Chassis/ChassisId/NetworkAdapters/networkadapteras_id/NetworkPorts/networkports_id/OpticalModule
URI：/redfish/v1/Chassis/chassis_id/Transceivers/transceivers_id
请求头：无
请求体：无
响应体:

字段	类型	说明
SupportedDiagnosticService	array	1、“PRBSTest”：支持PRBS测试 2、新增“ContaminationDetection”：支持光端面脏污检测

评审点2 DiagnosticService资源新增ContaminationDetection子资源链接，以支持脏污检测配置和查询

操作权限：ReadOnly
请求类型：GET
请求URL：/redfish/v1/Managers/ManagerId/DiagnosticService（现有）
请求头：无
请求体：无
响应体:

字段	类型	说明
ContaminationDetection	object	脏污检测接口集合资源模型的OData描述信息举例：“ContaminationDetection”: {“@odata.id”：“/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection”}

{
    "ContaminationDetection": {
        "@odata.id"："/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection"
    }
}

评审点3 新增ContaminationDetection资源

操作权限：ReadOnly
请求类型：GET
请求URL： /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection（新增）
请求头：无
请求体：无
响应体:

字段	类型	说明
@odata.context	string	脏污检测接口集合资源模型的OData描述信息
@odata.id	string	脏污检测接口集合资源的访问路径
@odata.type	string	脏污检测接口集合资源的类型
Id	string	脏污检测接口集合资源ID
Name	string	脏污检测接口集合资源名称
Detectors{	object	脏污检测对象集合资源
@odata.id	string	脏污检测对象集合资源的访问路径
}
Actions{	object	脏污检测接口集合资源
#ContaminationDetection.GetResult {	object	查询检测信息接口资源
target	string	脏污检测查询接口的访问路径
@Redfish.ActionInfo	string	脏污检测查询接口说明的访问路径
}
#ContaminationDetection.Initiate{	object	初始化检测接口资源
target	string	脏污检测初始化接口的访问路径
@Redfish.ActionInfo	string	脏污检测初始化接口说明的访问路径
}
#ContaminationDetection.Start{	object	启动检测接口资源
target	string	脏污检测启动接口的访问路径
@Redfish.ActionInfo	string	脏污检测启动接口说明的访问路径
}
#ContaminationDetection.Shutdown{	object	退出检测接口资源
target	string	脏污检测退出接口的访问路径
@Redfish.ActionInfo	string	脏污检测退出接口说明的访问路径
}
}

{
    "@odata.id": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection",
    "@odata.type": "#HwContaminationDetection.v1_0_0HwContaminationDetection",
    "@odata.context": "/redfish/v1/$metadata#HwContaminationDetection.HwContaminationDetection",
    "Id": "ContaminationDetection",
    "Name": "Contamination Detection",
    "Detectors": {
        "@odata.id": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Detectors"
    },
    "Actions": {
        "#ContaminationDetection.GetResult": {
            "target": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.GetResult",
            "@Redfish.ActionInfo": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/GetResultActionInfo"
        },
        "#ContaminationDetection.Initiate": {
            "target": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.Initiate",
            "@Redfish.ActionInfo": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/InitiateActionInfo"
        },
        "#ContaminationDetection.Start": {
            "target": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.Start",
            "@Redfish.ActionInfo": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/StartActionInfo"
        },
        "#ContaminationDetection.Shutdown": {
            "target": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.Shutdown",
            "@Redfish.ActionInfo": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/ShutdownActionInfo"
        }
    }
}

评审点4 新增Detectors集合资源

操作权限：ReadOnly
请求类型：GET
请求URL： /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection/Detectors（新增）
请求头：无
请求体：无
响应体:

字段	类型	说明
@odata.context	string	脏污检测对象集合资源信息模型的OData描述信息
@odata.id	string	脏污检测对象集合资源的访问路径
@odata.type	string	脏污检测对象集合资源的类型
Name	string	脏污检测对象集合资源名称
Members@odata.count	number	脏污检测对象的资源数量
Members[{	object	脏污检测测试对象集合
@odata.id	string	脏污检测单个对象集合资源的访问路径
}]

{
    "@odata.id": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Detectors",
    "@odata.type": "#HwDetectorCollection.HwDetectorCollection",
    "@odata.context": "/redfish/v1/$metadata#HwDetectorCollection.HwDetectorCollection",
    "Name": "Detector Collection",
    "Members@odata.count": 2, 
    "Members": [
        {
            "@odata.id": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Detectors/300001"
        },
        {
            "@odata.id": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Detectors/300002"
        }
    ]
}

评审点5 新增Detector实例资源

操作权限：ReadOnly
请求类型：GET
请求URL： /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection/Detectors/DetectorId（新增）
请求头：无
请求体：无
响应体:

字段	类型	说明
@odata.context	string	单个脏污检测对象资源模型的OData描述信息
@odata.id	string	单个脏污检测对象资源的访问路径
@odata.type	string	单个脏污检测对象资源的类型
Id	string	单个脏污检测对象资源ID
Name	string	单个脏污检测对象资源名称
Links{	object	脏污检测链接的检测资源
Transceiver{	object	脏污检测链接的光模块资源
@odata.id	string	脏污检测链接的光模块资源路径
}
}

{
    "@odata.id": "/redfish/v1/Managers/1/DiagnosticService/ContaminationDetection/Detectors/300001",
    "@odata.type": "#HwDetector.v1_0_0.HwDetector",
    "@odata.context": "/redfish/v1/$metadata#HwDetector.HwDetector",
    "Id": "300001",
    "Name": "Detector",
    "Links": {
            "Transceiver": {
               "@odata.id": "/redfish/v1/Chassis/1/Transceivers/OpticalModule_EthernetAdapterBoardPort1"
            }
    }
}

评审点6 ContaminationDetection资源新增Action（GetResult）

操作权限：DiagnoseMgmt
请求类型：POST
请求URL： /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.GetResult（新增）
请求头：无
请求体：

字段	类型	说明
Detectors		脏污检测查询的对象列表

响应体:

字段	类型	说明
@odata.type	string	脏污检测信息资源的类型
MessageId	string	消息ID
RelatedProperties	array	消息相关属性
Message	string	详细信息
MessageArgs	array	信息参数
Severity	string	严重性，Redfish支持的严重级别包括：OK、Warning、Critical
Resolution	string	解决建议
Oem{	object	oem属性
{{OemIdentifier}}{	object	自定义厂商
Detections[{	array	脏污检测对象信息列表
DetectorId	string	检测对象序列号
DetectionStatus	string	检测对象的检测状态，取值范围：Pending检测未启动，Running检测执行中，Unknown状态无法确定
Result{	object	检测结果
ContaminationDetected	string	脏污检测结果，取值范围Detected: 检测到脏污，NotDetected: 未检测到脏污，Unknown: 检测结果未确定
ContaminationDistance	number	脏污位置点与检测对象之间的距离，单位米
}
}]
}
}

请求体
{
    "Detectors": ["300001" ]
}

响应体
{
    "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.Success",
                "RelatedProperties": [],
                "Message": "Successfully Completed Request",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "None",
                "Oem": {
                    "{OemIdentifier}": {
                        "Detections": [
                            {
                                "DetectorId": "300001",
                                "DetectionStatus": "Pending",      # 取值 "Pending" - 检测未启动， "Running" - 检测正在进行， "Unknown" - 检测状态未知
                                "Result": {     
                                        "ContaminationDetected": "Detected",   # 检测结论，"Detected"， "NotDetected"， "Unknown" ；"Unknown"表示检测结论未确定
                                        "ContaminationDistance": 0.0,           # 脏污点与本端模块之间的距离，浮点类型，表示脏污点与本光模块的距离，单位米
                                }
                            }
                        ]
                    }
                }
            }
        ]
    }
}

评审点7 ContaminationDetection资源新增Action（Initiate）

操作权限：DiagnoseMgmt
请求类型：POST
请求URL： /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.Initiate（新增）
请求头：无
请求体：

字段	类型	说明
Configuration[{	array	需要下发的配置信息对象，目前最多支持8个检测对象
DetectorId	string	脏污检测对象序列号，可通过 /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection/Detectors获得
DurationSeconds	number	脏污检测超时时间，超时后检测自动终止,数字（单位：s），取值范围 60 - 900
}]

响应体:

字段	类型	说明
@odata.type	string	下发脏污检测配置资源的类型
MessageId	string	消息ID
RelatedProperties	array	消息相关属性
Message	string	详细信息
MessageArgs	array	信息参数
Severity	string	严重性，Redfish支持的严重级别包括：OK、Warning、Critical
Resolution	string	解决建议
Oem{	object	oem自定义属性
{{OemIdentifier}}{	object	自定义厂商
OperationResults[{	array	下发配置返回信息
DetectorId	string	脏污检测对象序列号
Result	string	下发配置执行结果，取值范围Success:成功，Failed:失败
}]
}
}

请求体
{
    "Configuration": [
        {
            "DetectorId": "300001",
            "DurationSecond": 300                               # 检测时长，单位秒；超时后自动退出脏污检测模式，恢复到业务模式
        }
    ]
}

响应体
{
    "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.Success",
                "RelatedProperties": [],
                "Message": "Successfully Completed Request",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "None",
                "Oem": {
                    "{OemIdentifier}": {
                        "OperationResults": [
                            {
                                "DetectorId": "300001",
                                "Result": "Success",          # 取值"Success", "failed"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

评审点8 ContaminationDetection资源新增Action（Start）

操作权限：DiagnoseMgmt
请求类型：POST
请求URL： /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.Start（新增）
请求头：无
请求体：

字段	类型	说明
Detectors	array	检测对象序列号列表

响应体:

字段	类型	说明
@odata.type	string	下发脏污检测配置资源的类型
MessageId	string	消息ID
RelatedProperties	array	消息相关属性
Message	string	详细信息
MessageArgs	array	信息参数
Severity	string	严重性，Redfish支持的严重级别包括：OK、Warning、Critical
Resolution	string	解决建议
Oem{	object	oem自定义属性
{{OemIdentifier}}{	object	自定义厂商
OperationResults[{	array	启动脏污检测配置返回信息
DetectorId	string	脏污检测对象序列号
Result	string	启动脏污检测执行结果，取值范围Success:成功，Failed:失败
}]
}
}

请求体
{
   "Detectors": [
       "300001"
    ]
}

响应体
{
    "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.Success",
                "RelatedProperties": [],
                "Message": "Successfully Completed Request",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "None",
                "Oem": {
                    "{OemIdentifier}": {
                        "OperationResults": [
                            {
                                "DetectorId": "300001",
                                "Result": "Success",          # 取值"Success", "failed"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

评审点9 ContaminationDetection资源新增Action（Shutdown）

操作权限：DiagnoseMgmt
请求类型：POST
请求URL： /redfish/v1/Managers/ManagerId/DiagnosticService/ContaminationDetection/Actions/ContaminationDetection.Shutdown（新增）
请求头：无
请求体：

字段	类型	说明
Detectors	脏污检测查询的对象	检测对象序列号列表

响应体:

字段	类型	说明
@odata.type	string	下发脏污检测配置资源的类型
MessageId	string	消息ID
RelatedProperties	array	消息相关属性
Message	string	详细信息
MessageArgs	array	信息参数
Severity	string	严重性，Redfish支持的严重级别包括：OK、Warning、Critical
Resolution	string	解决建议
Oem{	object	oem自定义属性
{{OemIdentifier}}{	object	自定义厂商
OperationResults[{	array	停止配置返回信息
DetectorId	string	脏污检测对象序列号
Result	string	停止配置执行结果，取值范围Success:成功，Failed:失败
}]
}
}

请求体
{
   "Detectors": [
       "300001"
    ]
}

响应体
{
    "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.Success",
                "RelatedProperties": [],
                "Message": "Successfully Completed Request",
                "MessageArgs": [],
                "Severity": "OK",
                "Resolution": "None",
                "Oem": {
                    "{OemIdentifier}": {
                        "OperationResults": [
                            {
                                "DetectorId": "300001",
                                "Result": "Success",          # 取值"Success", "failed"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

评审点10：新增脏污检测资源协作接口rpc方法

方案一
资源path：/bmc/kepler/Systems/:SystemID/NetworkAdapters/:ID/Ports/:ID/OpticalModule（已有）

资源interface：bmc.kepler.ContaminationDetection（新增）

变化类型：新增interface、rpc方法、属性

应用场景：用于脏污检测

方法：

方法名称	变化类型	请求签名	请求参数说明	响应签名	响应参数说明	访问权限	说明	约束
Initiate	方法	us	第一个参数DurationSeconds：脏污检测超时时间，超时后检测自动终止，取值范围 60 - 900	NA	NA	DiagnoseMgmt	初始化脏污检测
Start	方法	NA	NA	NA	NA	DiagnoseMgmt	启动脏污检测	不能重复启动脏污检测
Shutdown	方法	NA	NA	NA	NA	DiagnoseMgmt	停止脏污检测	只能停止存在的脏污检测任务

属性：

属性名称	变化类型	签名	读写&权限	持久化	变化通知	属性说明	接口约束
DetectionSupported	新增属性	b	只读，读权限：ReadOnly	无	false	是否支持脏污检测	取值范围：true（支持脏污检测）；false（不支持脏污检测）
DetectionStatus	新增属性	s	只读，读权限：ReadOnly	无	false	脏污检测状态	取值 “Pending” （检测未启动）， “Running” （检测正在进行）， “Unknown” （检测状态未知）
DetectionResult	新增属性	s	只读，读权限：ReadOnly	无	false	脏污检测结果	取值"Detected" （检测到脏污检测）， “NotDetected”（未检测到脏污检测）， “Unknown” （检测结论未确定）
ContaminationDistance	新增属性	d	只读，读权限：ReadOnly	无	false	脏污点与本端模块之间的距离	单位米

方案二
资源path：/bmc/kepler/Managers/:ManagerId/DiagnosticService/ContaminationDetection（新增）

资源interface：bmc.kepler.Managers.DiagnosticService.ContaminationDetection（新增）

变化类型：新增path、interface、rpc方法

应用场景：用于脏污检测

方法：

方法名称	变化类型	请求签名	请求参数说明	响应签名	响应参数说明	访问权限	说明	约束
GetResults	方法	as	[“300001”]，数组参数为DetectorId：测试对象序列号	a(a{ss})	[ [ {“DetectorId”, “30001”}, {“DetectionStatus”, “Pending”}, {“DetectionResult”, “Detected”}, {“ContaminationDistanceMeters”, “1.5”} ], [ {“DetectorId”, “30002”}, {“DetectionStatus”, “Pending”}, {“DetectionResult”, “Detected”}, {“ContaminationDistanceMeters”, “1.6 ”} ], ] 参数DetectorId：测试对象序列号参数DetectionStatus：脏污检测状态，取值 “Pending” （检测未启动）， “Running” （检测正在进行）， “Unknown” （检测状态未知）参数DetectionResult：脏污检测结果，取值"Detected" （检测到脏污检测）， “NotDetected”（未检测到脏污检测）， “Unknown” （检测结论未确定）参数ContaminationDistanceMeters：脏污检测污点距离	DiagnoseMgmt	查询脏污检测结果
Initiate	方法	a(sq)	[{ “300001”, 300}] 第一个参数是DetectorId：测试对象序列号第二个参数是DurationSeconds：脏污检测超时时间，单位秒，超时后自动退出脏污检测模式，恢复到业务模式	a(ss)	[ { “300001”,“Success”}]; 第一个参数DetectorId：测试对象序列号第二个参数Result：脏污检测配置的执行结果，取值"Success"、“Failed”	DiagnoseMgmt	初始化脏污检测
Start	方法	a(a{ss})	[ [ {“DetectorId”, “30001”}, {“DetectionItem”, “”} ], [ {“DetectorId”, “30002”}, {“DetectionItem”, “”} ], ] 参数DetectorId：测试对象序列号参数DetectionItem：检测子项，默认缺省代表全部测试	a(ss)	[ { “300001”,“Success”}]; 第一个参数DetectorId：测试对象序列号第二个参数Result：启动脏污检测的执行结果，取值"Success"、“Failed”	DiagnoseMgmt	开启脏污检测	不能重复启动脏污检测
Shutdown	方法	as	[“300001”]，数组参数为DetectorId：测试对象序列号	a(ss)	[ { “300001”,“Success”}]; 第一个参数DetectorId：测试对象序列号第二个参数Result：停止脏污检测的执行结果，取值"Success"、“Failed”	DiagnoseMgmt	停止脏污检测	只能停止存在的脏污检测任务

资源path: /bmc/kepler/Systems/:SystemID/NetworkAdapters/:ID/Ports/:ID/OpticalModule（已有）

资源interface: bmc.kepler.Systems.OpticalModule.Diagnose（已有）

新增属性： ContaminationDetectionSupported

属性名称	变化类型	签名	读写&权限	持久化	变化通知	属性说明	接口约束
ContaminationDetectionSupported	新增属性	b	只读，读权限：ReadOnly	无	false	此光模块是否支持脏污检测	取值范围：true（支持脏污检测）；false（不支持脏污检测）

评审结论

1、同意SupportedDiagnosticService属性新增取值ContaminationDetection
2、同意DiagnosticService资源新增ContaminationDetection子资源，以支持脏污检测配置和查询
3、同意新增ContaminationDetection 资源接口
4、同意新增Detectors 集合资源接口
5、同意新增Detector 单个检测对象资源接口
6、同意新增ContaminationDetection资源的GetResult Action
7、同意新增ContaminationDetection资源的Initiate Action
8、同意新增ContaminationDetection资源的Start Action
9、同意新增ContaminationDetection资源的Shutdown Action
10、同意新增脏污检测资源协作接口interface、rpc方法、属性
（1）脏污检测方法
资源path：/bmc/kepler/Managers/:ManagerId/DiagnosticService/ContaminationDetection（新增）
资源interface：bmc.kepler.Managers.DiagnosticService.ContaminationDetection（新增）
rpc方法：GetResults、Initiate、Start、Shutdown（新增）
（2）脏污检测属性
资源path: /bmc/kepler/Systems/:SystemID/NetworkAdapters/:ID/Ports/:ID/OpticalModule（已有）
资源interface: bmc.kepler.Systems.OpticalModule.Diagnose（已有）
新增属性： ContaminationDetectionSupported（新增）

遗留问题

1、bmc.kepler.Managers.DiagnosticService.ContaminationDetection明确挂到哪个path？
结论：该接口添加到/bmc/kepler/Managers/:ManagerId/DiagnosticService/ContaminationDetection下，通过参数区分脏污检测对象

huangjiapei_o2800 · 2025 年11 月 23 日 09:32

遗留问题

1、bmc.kepler.Managers.DiagnosticService.ContaminationDetection明确挂到哪个path？

话题		回复	浏览量
【已评审】光模块脏污检测redfish接口变更 Interface评审	1	84	2026 年2 月 9 日
【变更声明】Redfish光模块脏污检测资源的Start请求体以及GetResult响应体变更 Interface SIG 变更声明	1	48	2026 年3 月 17 日
【已评审】redfish新增标准资源LeakDetectors和Circuit Interface评审	3	169	2025 年11 月 27 日
【已评审】新增LeakDetector相关属性资源协作接口 Interface评审方案评审	1	78	2025 年11 月 27 日
[待评审] 资源协作接口新增网卡光模块信号处理类型属性 Interface评审	0	13	2026 年5 月 30 日

【已评审】新增光模块脏污检测redfish接口、资源协作属性和接口

背景

关联ISSUE

整体方案

评审点

详细描述

评审点1 SupportedDiagnosticService属性新增取值ContaminationDetection

评审点2 DiagnosticService资源新增ContaminationDetection子资源链接，以支持脏污检测配置和查询

评审点3 新增ContaminationDetection资源

评审点4 新增Detectors集合资源

评审点5 新增Detector实例资源

评审点6 ContaminationDetection资源新增Action（GetResult）

评审点7 ContaminationDetection资源新增Action（Initiate）

评审点8 ContaminationDetection资源新增Action（Start）

评审点9 ContaminationDetection资源新增Action（Shutdown）

评审点10：新增脏污检测资源协作接口rpc方法

评审结论

遗留问题

遗留问题

相关话题