【变更声明】TelemetryService调整遥测接口及事件报文格式

Interface SIG
1

变更声明

为修正早期 TelemetryService 部分接口响应及指标报告事件报文与 Redfish Schema 定义不一致的问题，openUBMC 对相关数据格式进行规范化调整，同时在 TelemetryService 资源中新增 OEM 扩展属性 SchemaComplianceMode，支持在标准格式与历史兼容格式之间切换。

该属性默认取值为 Standard，按照 Redfish Schema 定义输出相关数据；对于依赖历史字段或数据结构的存量客户端，可设置为 Oem，保留历史格式。**本次变更同时涉及接口查询响应和 MetricReport 事件报文，存量上层网管及遥测接收端需评估适配影响。

受影响的版本

  • openUBMC 26.09

变更描述

规格变化

新增遥测数据格式的模式切换能力，具体属性及格式差异见“外部接口变化”。

外观变化

不涉及。

外部接口变化

一、TelemetryService 新增格式控制属性

相关 URI：

/redfish/v1/TelemetryService

变化点： GET 响应中新增属性，并支持通过 PATCH 修改。属性定义如下，参见 [Redfish 遥测服务使用指导][telemetry-guide]。

项目 说明
属性路径 Oem.{{OemIdentifier}}.SchemaComplianceMode
数据类型 String
访问方式 读写
默认值 Standard
Standard 标准模式，按照 Redfish Schema 定义输出相关数据
Oem 历史兼容模式，保留 openUBMC 历史字段及数据结构
作用范围 TelemetryService 相关资源响应及 MetricReport 事件报文

变更后的响应节选：

{
  "Oem": {
    "{{OemIdentifier}}": {
      "SchemaComplianceMode": "Standard"
    }
  }
}

其中，{{OemIdentifier}} 为厂商标识占位符，实际调用时应替换为目标 BMC 使用的 OEM 标识。

二、调整遥测资源查询响应格式

涉及以下接口：

GET /redfish/v1/TelemetryService/MetricDefinitions/{MetricDefinitionId}

GET /redfish/v1/TelemetryService/MetricReports/{MetricReportId}

变更前后及兼容模式的差异如下，参见 [Redfish 遥测服务使用指导][telemetry-guide]。

接口属性 变更前／Oem 模式 变更后 Standard 模式
MetricDefinition.MetricProperties 对象数组格式 URI 字符串数组
MetricReport.MetricReportDefinition 对象数组格式 单个资源链接对象

Standard 模式下，MetricProperties 的格式示例：

{
  "MetricProperties": [
    "/redfish/v1/Chassis/1/Sensors/CPU0Temp#/Reading"
  ]
}

客户端应直接读取数组中的 URI 字符串，不再按照历史对象结构访问数组成员。

Standard 模式下，MetricReportDefinition 的格式示例：

{
  "MetricReportDefinition": {
    "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/CPU0TempReport"
  }
}

客户端应通过 MetricReportDefinition["@odata.id"] 获取关联资源 URI，不再将该属性作为数组处理。

三、调整 MetricReport 事件报文格式

通过事件订阅向接收端推送的 MetricReport 报文随模式切换调整，具体差异如下，参见 [Redfish 遥测服务使用指导][telemetry-guide]。

报文字段 变更前／Oem 模式 变更后 Standard 模式
@odata.id 历史路径格式 /redfish/v1/TelemetryService/MetricReports/{MetricReportId}
Id 数字编号 指标报告 ID
指标值数组 GeneratedMetricReportValues MetricValues
EventType 保留 不包含
MetricReportName 保留 不包含

接收端适配标准模式时，应按照 MetricReport 资源结构解析报文，读取 MetricValues 获取指标数据；需要报告名称时，应读取标准属性 Name，不再依赖 MetricReportName。同时，Id 应按字符串标识处理，不应继续假定其为数字类型或递增事件序号。

安装方式变化

不涉及

兼容性说明

BMC 固件兼容性

本次变更包含响应属性结构、报文字段名称及标识格式的调整，不能视为对所有存量客户端透明的变更。依赖历史格式的客户端在接收标准格式后，可能出现字段读取失败、类型校验失败或报告关联异常，需通过客户端适配或使用 Oem 模式处理。

openUBMC 和 BMC SDK 兼容性

对自行维护遥测资源映射、报文生成逻辑或接口数据模型的产品，建议同步检查相关实现是否支持两种模式，以及组件之间的格式处理是否一致。

具体 SDK 配套要求及最低版本，需根据实际发布版本确认，本声明暂不指定 SDK 升级版本。

BMC 与上层网管的兼容性

新对接系统建议使用标准格式；依赖历史结构的系统可先采用兼容模式过渡，再完成标准格式适配。由于格式控制属性位于 TelemetryService 服务资源，切换前应统一评估该 BMC 对接的查询客户端和遥测接收端，不能只验证其中一个接收端。

Oem 模式用于保留历史行为，不应据此认定历史格式满足标准 Schema 校验要求；有标准一致性要求的场景，应使用 Standard 模式并执行相应验证。两种模式的定义参见 [Redfish 遥测服务使用指导][telemetry-guide]。

文档影响

上述内容涉及以下文档变化：

文档 涉及内容
Redfish 接口文档 新增属性的路径、类型、取值、默认值、读写方式及作用范围；相关资源的响应结构
Redfish 遥测服务使用指导 两种模式的差异、模式切换方法及兼容性注意事项
遥测接收端对接文档及示例 标准报文解析方式、历史字段迁移

建议动作

1. 升级前完成客户端依赖检查

排查是否依赖对象数组形式的 MetricProperties、数组形式的 MetricReportDefinition，以及历史推送字段、数字类型的 Id 和历史路径格式。

2. 未完成标准适配的存量系统，先配置兼容模式

在支持该属性的固件上，通过以下请求切换为历史兼容格式。

PATCH /redfish/v1/TelemetryService
Content-Type: application/json

{
  "Oem": {
    "{{OemIdentifier}}": {
      "SchemaComplianceMode": "Oem"
    }
  }
}

实际调用时，应将 {{OemIdentifier}} 替换为目标 BMC 使用的 OEM 标识。

3. 完成适配后切换标准模式，并验证查询与推送两条链路

使用同一接口将属性值修改为 Standard；随后查询当前模式，验证指标定义、指标报告的响应解析。