SecMPS/doc/对接文档/MC4.0对外API.md

MC4.0 对外 API 文档

1. 引言

本接口文档详尽描述服务对外提供的 HTTP API，遵循以下规范以确保与服务端正确通信和数据交互。

1.1 目标与范围

为第三方开发者提供安全、稳定、高效的数据交换通道，采用 JSON 格式传输数据，所有接口均采用 HTTP 协议通信。

1.2 基本约定

• 所有接口请求方法均使用HTTP POST

• 数据格式统一为JSON，Content-Type设置为application/json

• 连接端口：3000

1.3 通讯数据格式

请求数据格式（Request）

{

 // 具体的数据内容

}

响应数据格式（Response）

{

 "code": 0,    // 结果码，0为成功，其他为错误

 "msg": "",    // 结果描述

 "data": {}    // 结果数据，具体数据内容

}

---

2. 接口列表（响应结果只标出 data 段）

2.1 通用接口

2.1.1 用户登录验证配置接口

登录前调用，确认用户密码是否需要 MD5 加密

• Endpoint：/api/central/auth/conf/get

• Method：POST

• Request Body：{}

• Response：

{

 "encrypt": true    // 用户密码是否需要用md5加密

}

注：返回结果码 4（未找到）也认为密码不需要 MD5 加密

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -d '{}' http://10.0.1.101:3000/api/central/auth/conf/get

2.1.2 用户登录接口

• Endpoint：/api/central/auth/login

• Method：POST

• Request Body：

{

 "account": "string",    // 用户名

 "password": "string"    // 用户密码

}

• Response：

{

 "token": "string",    // 后续接口访问，置于headers的token字段

 "id": 0,

 "account": "string",

 "name": "string",     // 用户名

 "option": {}          // 预留信息

}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -d '{"account":"admin","password":"d46060ea3d655f9b4fd31ac1bf1dc21b"}' http://10.0.1.101:3000/api/central/auth/login

2.1.3 用户注销接口

• Endpoint：/api/central/auth/logout

• Method：POST

• Request Body：{}

• Response：{}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token: 7b8c8225-f0744ab3-a086-89ef855da41c" -d '{}' http://10.0.1.101:3000/api/central/auth/logout

2.1.4 获取对象树

• Endpoint：/api/central/object/tree

• Method：POST

• Request Body：{}

• Response：

\[

 {

   "id": 0,              // 区域或者设备id

   "name": "string",     // 对象名称

   "type": 0,            // 对象类型 1-区域 2-设备

   "objectType": 0,      // 设备类型，自定义

   "tag": "",            // 设备标签

   "option": {},         // 自定义字段

   "children": \[]        // 子设备或区域，递归结构

 }

]

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:7b8c8225-f074-4ab3-a086-89ef855da41c" -d '{}' http://10.0.1.101:3000/api/central/object/tree

2.1.5 获取设备点表

• Endpoint：/api/central/device/point/get

• Method：POST

• Request Body：

{

 "id": 0    // 设备id

}

• Response：

\[

 {

   "index": 0,        // 点索引

   "type": 0,         // 点类型

   "tag": "string",   // 标签

   "name": "string",  // 点名称

   "desc": "string",  // 点描述

   "unit": "string",  // 单位

   "option": {}       // 自定义字段

 }

]

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:7b8c8225-f074-4ab3-a086-89ef855da41c" -d '{"id":1001463}' http://10.0.1.101:3000/api/central/device/point/get

2.1.6 控制设备点值

• Endpoint：/api/central/point/value/set

• Method：POST

• Request Body：

{

 "id": 0,       // 设备id

 "index": 0,    // 点索引

 "value": 0     // 设置值

}

• Response：{}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:7b8c8225-f074-4ab3-a086-89ef855da41c" -d '{"id":1001463,"index":10,"value":0}' http://10.0.1.101:3000/api/central/point/value/set

2.1.7 获取设备点值 - 按设备

• Endpoint：/api/central/device/point/value/get

• Method：POST

• Request Body：

{

 "id": 0    // 设备id

}

• Response：

\[

 {

   "index": 0,               // 点索引

   "value": 0,               // 点值

   "time": "2006-01-02 15:04:05",    // 点值更新时间

   "interval": 0             // 距离上一次采集间隔，毫秒

 }

]

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:7b8c8225-f074-4ab3-a086-89ef855da41c" -d '{"id":1001463}' http://10.0.1.101:3000/api/central/device/point/value/get

2.1.8 获取设备点值 - 按设备点

• Endpoint：/api/central/point/multi/value/get

• Method：POST

• Request Body：

{

 "points": \[

   {

     "id": 0,       // 查询的id

     "index": 0     // 查询的点索引

   }

 ]

}

• Response：

\[

 {

   "id": 0,                  // 设备id

   "index": 0,               // 点索引

   "value": 0,               // 点值

   "time": "2006-01-02 15:04:05",    // 点值更新时间

   "interval": 0             // 距离上一次采集间隔，毫秒

 }

]

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:7b8c8225-f074-4ab3-a086-89ef855da41c" -d '{"points":\[{"id":1001463,"index":2}]}' http://10.0.1.101:3000/api/central/point/multi/value/get

---

2.2 告警

2.2.1 确认告警

• Endpoint：/api/central/alarm/confirm

• Method：POST

• Request Body：

{

 "id": "string",    // 告警id

 "option": {}       // 其他参数

}

• Response：{}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ce4d927b-5d51-458b-b142-983af12075e5" -d '{"id":"111","option":{}}' http://10.0.1.101:3000/api/central/alarm/confirm

2.2.2 结束告警

• Endpoint：/api/central/alarm/end

• Method：POST

• Request Body：

{

 "id": "string",    // 告警id

 "option": {}       // 其他参数

}

• Response：{}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ce4d927b-5d51-458b-b142-983af12075e5" -d '{"id":"111","option":{}}' http://10.0.1.101:3000/api/central/alarm/end

2.2.3 查询告警

• Endpoint：/api/central/alarm/query

• Method：POST

• Request Body：

{

 "sids": \[1,2,3],          // 告警源id，为空表示全部

 "types": \[1,2,3,4],       // 告警类型，为空表示全部

 "confirmState": 0,        // 0-所有，1-未确认，2-已确认

 "endState": 0,            // 0-所有，1-未结束，2-已结束

 "level": \[1,2,3,4],       // 告警等级，为空表示全部

 "from": "2024-03-11 10:32:30",    // 开始时间，必填

 "to": "2024-03-11 11:32:30",      // 结束时间，必填

 "sort": 0,                // 0-升序，1-降序

 "dischargeState": 1,      // 0-不过滤，1-放电告警，2-非放电告警

 "skip": 0,                // 分页，跳过数量

 "limit": 0                // 分页，查询数量

}

• Response：

{

 "total": 0,    // 告警数量

 "list": \[

   {

     "sid": 1001863,

     "sno": 0,

     "coption": null,

     "ctime": "0001-01-01 00:00:00",

     "cuser": "",

     "desc": "\[列头柜]\[B2电压]\[17.04V]",

     "engDesc": "\[]\[B2 Voltage]\[17.04V]",

     "engTName": "",

     "eoption": {

       "value": 6.82

     },

     "etime": "2024-03-01 10:33:07",

     "id": "2183fda3-9e32-48ae-b433-f807cc81a237",

     "isDischarge": 0,

     "level": 1,

     "soption": {

       "typeName": "CPU使用过大1",

       "value": 17.04

     },

     "spi": 6,

     "state": 3,

     "stime": "2024-03-01 10:33:04",

     "tName": "",

     "type": 1011

   }

 ]

}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ce4d927b-5d51-458b-b142-983af12075e5" -d '{"from":"2024-03-01 10:32:30","to":"2024-03-11 10:32:30","skip":0,"limit":10}' http://10.0.1.101:3000/api/central/alarm/query

2.2.4 查询待处理告警数量

• Endpoint：/api/central/alarm/custom_query_count

• Method：POST

• Request Body：

{

 "sids": \[1,2,3],    // 设备id，空返回所有

 "state": 0,         // 0-所有，1-未确认，2-已确认

 "level": \[1,2,3]    // 告警等级，空返回所有

}

• Response：

{

 "total": 0    // 告警数量

}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ce4d927b-5d51-458b-b142-983af12075e5" -d '{"sids":\[],"state":0,"level":\[]}' http://10.0.1.101:3000/api/central/alarm/custom\_query\_count

2.2.5 查询待处理告警记录

• Endpoint：/api/central/alarm/custom_query

• Method：POST

• Request Body：

{

 "sids": \[1,2,3],    // 设备id，空返回所有

 "state": 0,         // 0-所有，1-未确认，2-已确认

 "level": \[1,2,3],   // 告警等级，空返回所有

 "skip": 0,          // 分页，跳过数量

 "limit": 0          // 分页，查询数量

}

• Response：同 2.2.3

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ce4d927b-5d51-458b-b142-983af12075e5" -d '{"sids":\[],"state":0,"level":\[],"skip":0,"limit":10}' http://10.0.1.101:3000/api/central/alarm/custom\_query

2.2.6 根据点查询告警记录

• Endpoint：/api/central/alarm/get_by_point

• Method：POST

• Request Body：

{

 "id": 1,       // 设备id

 "index": 1     // 设备点索引

}

• Response：告警列表数组

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ce4d927b-5d51-458b-b142-983af12075e5" -d '{"id":1,"index":1}' http://10.0.1.101:3000/api/central/alarm/get\_by\_point

2.2.7 查询告警记录

• Endpoint：/api/central/alarm/get

• Method：POST

• Request Body：

{

 "id": "111"    // 告警id

}

• Response：单条告警详情

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ce4d927b-5d51-458b-b142-983af12075e5" -d '{"id":"2183fda3-9e32-48ae-b433-f807cc81a237"}' http://10.0.1.101:3000/api/central/alarm/get

2.2.8 查询历史告警

• Endpoint：/api/central/his_alarm/query

• Method：POST

• Request Body：

{

 "sids": \[1,2,3],        // 设备id，空返回所有

 "types": \[1,2,3,4],     // 告警类型，空表示全部

 "startTime": "2024-03-10 12:00:00",

 "endTime": "2024-03-11 12:00:00",

 "skip": 0,

 "limit": 10

}

• Response：同 2.2.3

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:ae64a1d3-ad9e-4ddd-b577-754985fad4f1" -d '{"startTime":"2024-03-10 12:00:00","endTime":"2024-03-11 12:00:00","skip":0,"limit":10}' http://10.0.1.101:3000/api/central/his\_alarm/query

2.2.9 查询被收敛的告警

• Endpoint：/api/central/report/alarm/convergence/query

• Method：POST

• Request Body：

{

 "id": "aaaa"    // 告警id

}

• Response：收敛告警列表

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:6874ea3b-6461-467d-9ba1-acf79c3e6b12" -d '{"id":"2183fda3-9e32-48ae-b433-f807cc81a237"}' http://10.0.1.101:3000/api/central/report/alarm/convergence/query

---

2.3 告警类型

2.3.1 添加告警类型

• Endpoint：/api/central/alarm/type/add

• Method：POST

• Request Body：

{

 "name": "",            // 告警类型名称

 "desc": "",            // 告警类型描述

 "engName": "",         // 副语言名称

 "engDesc": "",         // 副语言描述

 "level": 0,            // 1-提示，2-普通，3-重要，4-紧急

 "genCondition": 0,     // 产生条件 1-< 2-== 3-> 4-<= 5->= 6-!=

 "genValue": 0,         // 产生比较值

 "endCondition": 0,     // 结束条件

 "endValue": 0,         // 结束比较值

 "startDelay": 0,       // 产生延时

 "endDelay": 0,         // 结束延时

 "enabled": 1,          // 1-启用，0-禁用

 "option": {}

}

• Response：

{

 "type": 0    // 新增告警类型id

}

• 请求示例：

curl -s -X POST -H "Content-Type: application/json" -H "token:170af07e-5b84-444e-a2c2-518ca8c1e2b2" -d '{"name":"新的告警","desc":"","engName":"","level":1,"genCondition":2,"engDesc":"","genValue":1,"endCondition":6,"endValue":1,"startDelay":0,"endDelay":0,"enabled":1,"option":{}}' http://10.0.1.101:3000/api/central/alarm/type/add

2.3.2 修改告警类型

• Endpoint：/api/central/alarm/type/set

• Method：POST

• Request Body：含type字段的同添加结构

• Response：{}

• 请求示例：略

2.3.3 删除告警类型

• Endpoint：/api/central/alarm/type/del

• Method：POST

• Request Body：

{

 "type": 0    // 告警类型

}

• Response：{}

• 请求示例：略

2.3.4 查询告警类型

• Endpoint：/api/central/alarm/type/list

• Method：POST

• Request Body：

{

 "types": \[1,2,3]    // 空查全部

}

• Response：告警类型列表

• 请求示例：略

---

2.4 配置

2.4.1 设置系统配置

• Endpoint：/api/central/manager/config/set

• Method：POST

• Request Body：

{

 "key": "",

 "value": {}

}

• Response：{}

• 请求示例：略

2.4.2 获取系统配置

• Endpoint：/api/central/manager/config/get

• Method：POST

• Request Body：{"key":""}

• Response：配置内容

• 请求示例：略

2.4.3 备份数据库

• Endpoint：/api/central/manager/db/backup

• Method：POST

• Request Body：{"path":"/tmp/backup.tar.gz"}

• Response：{}

• 请求示例：略

2.4.4 还原数据库

• Endpoint：/api/central/manager/db/restore

• Method：POST

• Request Body：含路径、内容、用户名、原因

• Response：{}

• 请求示例：略

2.4.5 还原日志查询

• Endpoint：/api/central/manager/db/log

• Method：POST

• Request Body：时间范围 + 分页

• Response：日志列表

• 请求示例：略

2.4.6 备份历史数据库

• Endpoint：/api/central/manager/hisdb/backup

• Method：POST

• Request Body：备份路径

• Response：{}

• 请求示例：略

2.4.7 还原历史数据库

• Endpoint：/api/central/manager/hisdb/restore

• Method：POST

• Request Body：还原路径

• Response：{}

• 请求示例：略

2.4.7 清除历史点值数据

• Endpoint：/api/central/manager/hisdb/clear

• Method：POST

• Request Body：{}

• Response：{}

• 请求示例：略

2.4.8 清除抓拍图片

• Endpoint：/api/central/manager/picture/clear

• Method：POST

• Request Body：{}

• Response：{}

• 请求示例：略

2.4.9 清除抓拍视频

• Endpoint：/api/central/manager/video/clear

• Method：POST

• Request Body：{}

• Response：{}

• 请求示例：略

---

3. 结果码说明

结果码	英文描述	中文描述
0	OK	成功
-1	UNKNOWN	未知错误
0x1	NOT_SUPPORT	不支持的命令
0x2	PARAM_ERROR	参数错误
0x3	CONNECTION_ERROR	连接错误
0x4	NOT_FOUND	未找到
0x5	NOT_LOGIN	未登录
0x6	NOT_HAVE_PRIVILEGE	没有权限
0x7	VALID_FAILED	验证失败
0x8	PWD_ERROR	密码错误
0x9	UNKNOW_DEVICE_NMODEL	未知设备类型
0x10	OTHER	其他错误
0x101	SEARCHING	搜索中

---

4. 固有自定义对象类型

值定义	描述
1	区域
23	机柜
50	通用设备
58	短信模块
59	极易短信模块
60	cacs 门禁控制器
61	门 (cacs)
62	http 门禁控制器
63	门 (http)
100	网关
108	资产主机 (大平台)
109	资产条 (大平台)
113	通用门
114	指纹读卡器
115	人脸识别门
116	海康一体化指纹门禁
117	西墨人脸门禁一体机
118	一卡门禁一体机
119	海康人脸识别门
120	海康控制器 (SDK 对接)
121	海康控制器门
122	微耕控制器
123	微耕门
201	NVR
202	IPC
301	资产主机
302	资产条
310	pcs 储能管理服务
311	pcs 储能管理服务控制单元

---

5. 版本控制与更新记录

序号	更新人	更新时间	更新内容	审核人
1	william	2024-03-08	协议文档初版制定	-
2	william	2024-03-12	完善告警及配置对外接口	-

---

使用前请仔细阅读文档，疑问或获取最新文档请联系技术支持团队。

我可以帮你把这份 Markdown 生成可直接下载的.md 文件，你一键保存即可使用，需要吗？

（注：文档部分内容可能由 AI 生成）