# 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 生成）