SOE设备健康评分API文档

1. 概述

SOE设备健康评分API旨在通过查询和分析设备的历史SOE（Sequence of Events）事件数据，基于不同SOE事件的权重和发生频率，对设备的健康状况进行动态评分。本接口提供了一种快速评估设备当前健康水平的机制，帮助用户及时了解设备运行状态。

2. API路径

https://ccs.hostcache.com/devicehealth/v1.1/

3. 请求方式

支持 HTTP GET 或 HTTP POST 请求。请注意，本接口不支持 JSON POST 请求，仅支持传统的 application/x-www-form-urlencoded 格式的 POST 请求。

4. 请求参数

以下是调用SOE设备健康评分API时可以使用的请求参数：

参数名	类型	是否必选	说明
`dev_oids`	String	是	设备OID（Object Identifier），用于指定需要查询健康评分的设备。支持传入一个或多个设备OID，多个OID之间请使用英文逗号 (`,`) 分隔。示例：`dev_oids=**********123,**********456`
`time_range_hours`	Integer	否	查询SOE表的时间范围，单位为小时。API将分析此参数指定的小时数内发生的SOE事件。默认值为 `24` 小时，即查询过去24小时的SOE事件。示例：`time_range_hours=72`

请求示例 (GET)

GET https://ccs.hostcache.com/devicehealth/v1.1/?dev_oids=************123,************456&time_range_hours=48

请求示例 (POST)

POST https://ccs.hostcache.com/devicehealth/v1.1/
Content-Type: application/x-www-form-urlencoded

dev_oids=************123,************456&time_range_hours=48

5. 返回结果

API返回结果为JSON格式。

5.1. 不成功的请求

当请求参数不符合要求时，API将返回以下错误信息：

缺少 dev_oids 参数：
```
{ "success": 0, "error": "NO DEV_OIDS" }
```
错误说明：请求中未提供必需的 dev_oids 参数。
time_range_hours 参数无效：
```
{ "success": 0, "error": "invalid time_range_hours" }
```
错误说明：time_range_hours 参数必须是一个有效的整数。

5.2. 成功的请求示范

成功请求将返回一个JSON数组，其中包含每个设备的健康评分详情。每个设备对象包括设备信息、健康得分、事件统计等。

[
  {
    "event_categories": {
      // 事件类别统计，例如 "voltage_present": 2
    },
    "device_info": {
      "dev_name": "0029接地刀闸",
      "dev_oid": "[DESENSITIZED_DEV_OID_1]",
      "st_name": "10kV法拉第分布式光伏"
    },
    "total_penalty": 0,
    "health_score": "100.0",
    "total_events": 0,
    "event_details": {
      // 具体的事件详情，如果无事件则为空
    },
    "calculation_time": "2025-12-24 11:20:46",
    "health_level": "Excellent"
  },
  {
    "health_level": "Excellent",
    "calculation_time": "2025-12-24 11:20:46",
    "event_details": {
      "voltage_present": [
        {
          "weight": 1,
          "name": "开关电源侧有压",
          "time": "2025-09-20 23:22:11.234"
        },
        {
          "weight": 1,
          "name": "开关负荷侧有压",
          "time": "2025-09-20 23:22:11.234"
        }
      ]
    },
    "health_score": "98.0",
    "total_events": 2,
    "total_penalty": 2,
    "device_info": {
      "dev_oid": "[DESENSITIZED_DEV_OID_2]",
      "st_name": "35kV方村变",
      "dev_name": "10kV方寨线鲁陆支线0090开关"
    },
    "event_categories": {
      "voltage_present": 2
    }
  }
]

6. 其他说明

本API是一个基于SOE事件的动态评分接口，其评分结果只考虑指定时间范围内的SOE事件对评分带来的影响。如果需要进行全局静态评分，请参考省网健康评分标准，相关API地址为： https://smartdocs.be/manual/gz-province-health-scoring-api-doc。