配网设备健康度评分 API 帮助文档

欢迎使用配网设备健康度评分 API！本 API 旨在提供配网设备 (FTU) 的实时健康度评估，帮助您快速了解设备运行状态，辅助预测性维护决策。

健康度评分范围为 0-100分，分数越高代表设备健康度越好。

API 概述

该 API 通过分析 FTU 设备的遥测数据（如电流、电压、功率因数等），自动计算并返回设备的健康度评分及相关指标。

API 地址：

https://metry.hostcache.com/healthscore/v1.0/

请求方法：

为确保数据传输的稳定性和可扩展性，我们推荐使用 **POST** 方法。

**推荐：** POST
**兼容：** GET (请注意，GET 请求在传输大量 ftukey 时可能受到 URL 长度限制)

请求参数

API 接受一个名为 ftukey 的参数，用于指定您希望查询的设备 ID。

参数名称	类型	是否必需	描述	示例值
`ftukey`	字符串 / 数字	是	要查询的 FTU 设备 ID。单个查询：直接传入一个 FTU 设备的数字 ID。批量查询：传入多个 FTU 设备的数字 ID，使用英文逗号 `,` 分隔。	`66` 或 `66,77,88`

请求示例 (POST)

使用 curl 命令发送 POST 请求：

curl -X POST "https://metry.hostcache.com/healthscore/v1.0/" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "ftukey=66,77,88"

请求示例 (GET)

直接在浏览器中访问或使用 curl 发送 GET 请求：

curl "https://metry.hostcache.com/healthscore/v1.0/?ftukey=66,77,88"

或直接在浏览器地址栏输入：

https://metry.hostcache.com/healthscore/v1.0/?ftukey=66,77,88

返回结果

API 将返回一个 JSON 对象，包含查询结果和状态信息。res 字段现在是一个数组，确保了返回结果的排序。

成功响应示例：

{
    "status":"OK",
    "res":[
        ["77","FTU f8c062 on XTU c1e6a5","41","45.28","47.36","6.17"],
        ["66","FTU d677f8 on XTU 24b2da","40","45.23","49.05","6.38"],
        ["88","FTU 8b610d on XTU 0b9284","39","44.68","49.01","6.66"]
    ]
}

响应字段说明：

字段名	类型	描述
`status`	字符串	API 请求的处理状态。 `"OK"`：表示请求成功处理。 `"ERROR"`：表示在处理请求过程中发生了某种错误。
`res`	数组	一个包含多个数组的列表。每个内部数组代表一个 FTU 设备的健康度详情，且已按照健康评分降序排列。如果查询的某个 `ftukey` 没有找到数据，它将不会出现在此数组中。

`res` 数组内部参数说明 (顺序)：

每个内部数组的元素按以下顺序排列：

**[0]** 设备ID (字符串): FTU 设备 ID。
**[1]** 设备名称 (字符串): 设备的友好名称。
**[2]** 健康评分 (字符串): 该设备的健康度评分，范围 0-100，整数。
**[3]** 参数超限率(%) (字符串): 设备关键参数超出正常范围的百分比，保留两位小数。
**[4]** 平均电流不平衡度(%) (字符串): 设备平均电流不平衡度的百分比，保留两位小数。
**[5]** 平均电压不平衡度(%) (字符串): 设备平均电压不平衡度的百分比，保留两位小数。

错误响应示例：

如果请求参数无效或服务器内部发生错误，status 字段将为 "ERROR"，并且响应中可能包含 res 字段来提供更详细的错误信息。

{
    "status": "ERROR",
    "res": "NO FTUKEY"
}

或

{
    "status": "ERROR",
    "res": "An internal server error occurred during database query."
}

注意： 返回的数值类型（如健康评分、百分比）在 JSON 中以**字符串**形式呈现，请在客户端进行相应的类型转换。

联系我们

如果您在使用过程中遇到任何问题或有改进建议，请随时联系我们的技术支持团队。