公共安全视频图像系统运维技术规范 第2部分：接口 
公共安全视频图像系统运维技术规范 第2部分：接口
ICS 35.240 CCS L 77 3502 福 建 省 厦 门 市 地 方 标 准 DB3502/T 072.2—2021 公共安全视频图像系统运维技术规范 第 2 部分：接口 Technical specification for operation and maintenance of video and image system for public security—Part2:Interfaces 2021 - 12 - 21 发布 2022 - 01 - 03 实施 厦门市市场监督管理局 发 布 DB3502/T 072.2—2021 目 次 前言 ................................................................................. II 引言 ................................................................................ III 1 范围 ............................................................................... 1 2 规范性引用文件 ..................................................................... 1 3 术语和定义 ......................................................................... 1 4 缩略语 ............................................................................. 1 5 接口分类与协议结构 ................................................................. 1 6 接口功能 ........................................................................... 2 7 接口资源描述 ....................................................................... 3 8 接口 ............................................................................... 3 附录 A（资料性） REST 架构协议模型 ................................................... 39 附录 B（资料性） 告警 ................................................................ 42 附录 C（资料性） 资源 URI ............................................................ 44 I DB3502/T 072.2—2021 前 言 本文件按照GB/T 1.1—2020《标准化工作导则 第1部分：标准化文件的结构和起草规则》的规定 起草。 本文件为DB3502/T 072《公共安全视频图像系统运维技术规范》的第2部分。DB3502/T 072已发布 了以下部分： ——第 1 部分：总体要求； ——第 2 部分：接口； ——第 3 部分：数据元。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。 本文件由厦门市安全技术防范协会提出。 本文件由厦门市公安局归口。 本文件起草单位：厦门市公安局、厦门市安全技术防范协会、厦门市标准化研究院、苏州科达科技 股份有限公司、厦门凯迪空间电子有限公司、杭州海康威视数字技术股份有限公司、罗普特科技集团股 份有限公司。 本文件主要起草人：李童、覃智泉、林三达、张茂林、庄毅滨、郭流流、陆通、柳少英、崔晓琳、 李钊茜、夏莉、李庚、陈耿斌。 II DB3502/T 072.2—2021 引 言 公共安全视频图像系统在打击犯罪、治安防控、社会治理以及服务民生方面发挥了重要的作用，公 共安全视频图像系统运维管理平台建设的统一和规范，将进一步提升公共安全视频图像系统运维的服 务水平，有利于视频图像行业的专业化、规范化发展。DB3502/T 072《公共安全视频图像系统运维技术 规范》旨在确立公共安全视频图像系统运维管理平台总体设计、接口、数据元的技术标准，为视频图像 系统运维管理平台的建设提供基础规范。 DB3502/T 072拟由三个部分构成： ——第 1 部分：总体要求。目的在于确立公共安全视频图像系统运维管理平台关键技术路线和软 件系统的组织形式，确保总体架构满足服务范围内公共安全视频图像系统运维需求，明确主 要功能模块和模块间的逻辑关系，避免“过度建设”并确保“必要建设”。 ——第 2 部分：接口。目的在于将公共安全视频图像系统运维管理平台对外接口标准化，明确接 口在安全性、完备性、一致性、易用性、稳定性方面的要求，并从本级一机一档管理系统、 下级公共安全视频图像系统运维管理平台、前端智能箱系统及其他应用系统接入等方面，明 确接入的实现方式，为保障建设质量及拓展应用范围提供技术支撑。 ——第 3 部分：数据元。通过标准化描述公共安全视频图像系统运维管理平台的数据元和数据模 型，构建标准化的数据环境，为建设数据共享、标准统一的公共安全视频图像运维管理体系 提供基础规范。 III DB3502/T 072.2—2021 公共安全视频图像系统运维技术规范 第 2 部分：接口 1 范围 本文件规定了公共安全视频图像系统运维管理平台的接口分类与协议结构、接口功能、接口资源描 述、接口等技术要求。 本文件适用于公共安全视频图像系统运维管理平台的规划设计、软件开发及接口协议的符合性测 试。 2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件， 仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本 文件。 GB/T 28181 公共安全视频监控联网系统信息传输、交换、控制技术要求 GA/T 1400.4 公安视频图像信息应用系统 第4部分：接口协议要求 DB3502/T 072.1 公共安全视频图像系统运维技术规范 第1部分：总体要求 IETF RFC 2616 超文本传输协议-HTTP/1.1（Hypertext Transfer Protocol-HTTP/1.1） 3 术语和定义 GB/T 28181、GA/T 1400.4、DB3502/T 072.1界定的术语和定义适用于本文件。 4 缩略语 下列缩略语适用于本文件。 REST:表述性状态传递（Representational State Transfer） SNMP:简单网络管理协议（Simple Network Management Protocol） URI：统一资源标识符(Uniform Resource Identifier) 5 接口分类与协议结构 接口分类 公共安全视频图像系统运维管理平台接口为运维管理平台和各应用系统专业运维节点的对接接口。 一机一档管理系统作为资源汇聚中心，提供统一运维对象开放接口，各类接口交互实体关系见图1，接 口分类说明如下： ——运维系统对接接口用于公共安全视频图像系统运维管理平台和本级一机一档管理系统专业运 维节点、下级公共安全视频图像系统运维管理平台、前端智能箱系统专业运维节点及其他应 用系统专业运维节点之间的数据交互； 1 DB3502/T 072.2—2021 ——统一运维对象开放接口用于一机一档管理系统和公共安全视频图像系统运维管理平台、前端 智能箱系统专业运维节点及其他应用系统专业运维节点之间的数据交换。 统一运维对象 开放接口 统一运维对象 开放接口 本级一机一档 统一运维对象开放接口 运维系统对接接口 运维系统对接接口 前端智能箱系统对接接口 前端智能箱系统 专业运维节点 其它应用系统 专业运维节点 视频图像系统运维管理平台 运维系统对接接口 运维系统对接接口 统一运维对象开放接口 下级一机一档 下级视频图像系统运维管理平台 下级应用系统 专业运维节点 运维系统对接接口 图1 接口交互实体关系图 协议结构 5.2.1 所有接口交互信息定义为 REST 架构下的资源，使用 URI 唯一标识。 5.2.2 接口交互连接方式应支持 HTTP 长连接和短连接，实现机制应符合 IETF RFC 2616 中的相关规 定。 5.2.3 应用系统接口访问形式应符合附录 A 中的 A.3。 6 接口功能 公共功能 6.1.1 功能要求 应用系统专业运维节点对接运维管理平台应支持注册、心跳、告警通知、状态订阅、状态订阅通知 等公共功能。专有设备管理系统专业运维节点、前端智能箱系统专业运维节点对接运维管理平台，应支 持公共功能。其中： ——注册失败时，应延迟 300s 内的随机时间后重新注册； ——注册成功后，在 10s 内未交互信息则进行心跳保活； ——应用系统专业运维节点汇聚本系统相关的服务器、服务实例、子系统的异常告警及前端设备 告警，应上报运维管理平台。 2 DB3502/T 072.2—2021 6.1.2 告警 应用系统专业运维节点，汇聚对接应用系统的告警异常，应对通用应用服务异常告警进行抽象定义， 本文件定义部分通用告警类型： ——应用系统专业运维节点代理多个子系统时，各子系统对告警类型定义不完全一致情况下，和 运维管理平台对接时，应用系统专业运维节点在保证告警码在系统内唯一的前提下，可上报 自定义的告警类型； ——通用告警类型见附录 B 中的 B.1； ——告警属性见附录 B 中的 B.2； ——告警级别见附录 B 中的 B.3； ——告警来源分为应用系统专业运维节点内告警和邻近系统告警。 专用功能 6.2.1 运维系统对接接口 6.2.1.1 应用系统专业运维节点应支持服务实例维护，前端智能箱系统专业运维节点、专有设备管理 系统专业运维节点可不支持服务实例维护。应用系统内部服务实例有变更时，应调用服务实例增加、删 除或修改接口。 6.2.1.2 可按需提供应用系统专业运维节点之间系统间告警订阅、系统间告警订阅通知和状态订阅。 6.2.2 前端智能箱系统对接接口 6.2.2.1 应支持设备列表查询功能，运维管理平台通过接口查询前端智能箱系统关联的智能箱列表， 和一机一档管理系统的设备信息进行比对分析，查找是否存在设备冲突。 6.2.2.2 应支持智能控制功能，对前端智能箱系统管理的智能箱进行重启、开关电等操作。 6.2.3 统一运维对象开放接口 6.2.3.1 应支持向一机一档管理系统查询设备信息，响应一机一档管理系统状态结果通知。 7 接口资源描述 资源 URI 7.1.1 运维系统资源 URI 见附录 C 中的 C.1。 7.1.2 应用系统资源 URI 见附录 C 中的 C.2。 7.1.3 一机一档管理系统资源 URI 见附录 C 中的 C.3。 8 接口 运维系统对接接口 8.1.1 注册 8.1.1.1 交互流程 注册交互流程见图2，信令流程描述如下： 3 DB3502/T 072.2—2021 a) b) 应用系统专业运维节点向运维管理平台 POST 发送/nms/v1/register 请求。应用系统专业运维 节点可以是前端智能箱系统专业运维节点、下级运维管理平台、专有设备管理系统专业运维节 点等运维节点； 运维管理平台将注册成功与否的响应返回给发起者。 专业运维节点 运维管理平台 1 POST /nms/v1/register 2 response 图2 注册交互流程图 8.1.1.2 流程示意图 注册流程示意图见图3。 专业运维节点 向运维管理平台发送 /nms/v1/register 进行注册 注册处理 注册失败 注册成功 注册完成 图3 注册流程示意图 8.1.1.3 注册功能描述 注册功能描述见表1。 4 专业运维节点注 册异常处理 DB3502/T 072.2—2021 表1 注册功能描述表 URI /nms/v1/register 功能 注册 HTTP 方法 POST { "id" : "35020000001370000218", 请求消息体 "password" : "xxxx" } （R）id：一机一档管理系统分配应用系统专业运维节点国标id 请求说明 （O）password：加密后的ID BASE64编码 { "code" : 0, "data" : { "token" : "a.b.c", 返回结果 }, "message" : "" } Token payload 内容为 { "exp":1554821260, -- 过期时间 "iat":1547608753 结果说明 -- 生成时间 } 在过期时间之前调用方需要重新调用register接口获取新的token Token值放入后续请求header的authorization字段中标记已经登录过 Authorization:Bearer a.b.c 注： R为必选项，O为可选项。 8.1.2 心跳 8.1.2.1 交互流程 心跳交互流程见图4，信令流程描述如下： a) 应用系统专业运维节点定时向运维管理平台 GET 发送/nms/v1/heartbeat/{id}请求； b) 运维管理平台将心跳成功与否的响应返回给发起者。 5 DB3502/T 072.2—2021 专业运维节点 运维管理平台 1 GET /nms/v1/heartbeat/{id} 2 response 图4 心跳交互流程图 8.1.2.2 流程示意图 心跳流程示意图见图5。 专业运维节点 向运维管理平台发送 /nms/v1/heartbeat/{id} 未接收到心跳 数据或心跳失 败 运维管理平台接 收心跳数据情况 心跳成功 结束 图5 心跳流程示意图 8.1.2.3 心跳功能描述 心跳功能描述见表2。 6 专业运维节点心 跳保活异常处理 DB3502/T 072.2—2021 表2 心跳功能描述表 URI /nms/v1/heartbeat/{id} 功能 应用系统专业运维节点心跳接口 HTTP 方法 GET 请求参数 id 请求消息体 无 请求说明 (R)id：一机一档管理系统分配应用系统专业运维节点国标 id { "code" : 0, 返回结果 "message" : "" } 结果说明 注册后，定时向运维管理平台发送心跳保活消息，建议 10 秒一次 注： R为必选项，O为可选项。 8.1.3 服务实例维护 8.1.3.1 交互流程 服务实例维护交互流程见图6，信令流程描述如下： a) 应用系统专业运维节点向运维管理平台发送/nms/v1/serviceInstance 增加、修改、删除请求； b) 运维管理平台将操作成功与否的响应返回给发起者。 专业运维节点 运维管理平台 1 POST/PUT/DELETE /nms/v1/serviceInstance 2 response 图6 服务实例维护交互流程图 8.1.3.2 流程示意图 服务实例维护流程示意图见图7。 7 DB3502/T 072.2—2021 专业运维节点 向运维管理平台发送 /nms/v1/serviceInstance 增删改请求 处理失败 运维管理平台接收 服务实例维护处理 专业运维节点服务 实例维护异常处理 处理成功 结束 图7 服务实例维护流程示意图 8.1.3.3 增加服务实例功能描述 增加服务实例功能描述见表3。 表3 增加服务实例功能描述表 URI /nms/v1/serviceInstance 功能 增加服务实例，可批量添加 HTTP 方法 POST [{ "hardwareID": "xxxx", 请求消息体 "systemID": "xxxx", "name": "流媒体微服务" }] （R）hardwareID：服务所属设备 ID 请求说明 （O）systemID：服务所属系统 ID （R）name：服务名称 { "code": 0, "data": [{ 返回结果 "hardwareID": "xxxx", "systemID": "xxxx", "id": "xxxxxxxx" 8 DB3502/T 072.2—2021 表3（续） }], 返回结果 "message": "" } （R）id：一机一档管理系统分配 ID 结果说明 （R）hardwareID：服务所属设备 ID （O）systemID：服务所属系统 ID 注： R为必选项，O为可选项。 8.1.3.4 修改服务实例功能描述 修改服务实例功能描述见表4。 表4 修改服务实例功能描述表 URI /nms/v1/serviceInstance 功能 修改服务实例，只允许修改 hardwareID（即服务和硬件设备对应关系） HTTP 方法 PUT [{ "id": "xxxx", "hardwareID": "xxxx", 请求消息体 "systemID": "xxxx", "name": "流媒体微服务" }] （R）id：服务实例 ID（一机一档管理系统分配） （R）hardwareID：服务所属设备 ID 请求说明 （O）systemID：服务所属系统 ID （R）name：服务名称 { "code" : 0, 返回结果 "message" : "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.3.5 删除服务实例功能描述 删除服务实例功能描述见表5。 9 DB3502/T 072.2—2021 表5 删除服务实例功能描述表 URI /nms/v1/serviceInstance/{id} 功能 删除服务实例 HTTP 方法 请求消息体 请求说明 DELETE id （R）id：服务实例 ID（一机一档管理系统分配） { "code" : 0, "data" : { 返回结果 "id" : "xxxxxxxx" }, "message" : "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.4 告警通知 8.1.4.1 交互流程 告警通知交互流程见图8，信令流程描述如下： a) 应用系统专业运维节点向运维管理平台发送/nms/v1/alarm 告警通知； b) 运维管理平台将操作成功与否的响应返回给发起者。 专业运维节点 运维管理平台 1 POST /nms/v1/alarm 2 response 图8 告警通知交互流程图 10 DB3502/T 072.2—2021 8.1.4.2 流程示意图 告警通知流程示意图见图9。 专业运维节点 向运维管理平台发送 /nms/v1/alarm 运维管理平台 接收告警通知 处理失败 专业运维节点告 警通知异常处理 处理成功 结束 图9 告警通知流程示意图 8.1.4.3 告警通知功能描述 告警通知功能描述见表6。 表6 告警通知功能描述表 URI /nms/v1/alarm 功能 告警通知接口 HTTP 方法 POST { "timestamp" : 15427016032, "alarmMsgs" : [{ "id":"31010600001320000009", "name": "kafka 实例", "sourceId": "31010600005200000009", 请求消息体 "sourceName": "人脸检测系统专业运维节点", "alarmCode": 70001, "alarmLevel": 1, "alarmStatus":1, "alarmTime": 13234343, "ip": "设备 IP", 11 DB3502/T 072.2—2021 表6（续） "alarmDesc": "告警描述", "alarmDeal": "处理建议" "noticePerson": 0, 请求消息体 "attachment": "6Ieq5a6a5LmJ5pWw5o2u" }] } (R) id：运维对象 ID，可以是系统运维节点 ID、系统 ID、后端服务器设备 ID、服务实例 ID 或 前端设备 ID (R)name：运维对象名称 (O)sourceId：运维节点 ID，如果告警对象就是运维节点，该字段可不填写 (O)sourceName：运维节点名称 (R)alarmCode：告警码 (R)alarmLevel：告警级别（见附录表 B.3） 请求说明 (R)alarmStatus：告警状态（0：恢复/ 1：告警） (R)alarmTime：告警时间 (O)ip: 设备 IP (R)alarmDesc：告警描述 (O)alarmDeal：处理建议 (O)noticePerson：是否通知到人 (O)attachment：附加运维信息，需要 Base64 编码 { "code" : 0, 返回结果 "message" : "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.5 状态订阅 8.1.5.1 交互流程 状态订阅交互流程见图10，信令流程描述如下： a) 运维管理平台向应用系统专业运维节点发送/subsystem/v1/subscirbe 订阅请求； b) 应用系统专业运维节点将操作成功与否的响应返回给运维管理平台。 12 DB3502/T 072.2—2021 运维管理平台 专业运维节点 1 POST /subsystem/v1/subscirbe 2 response 图10 状态订阅交互流程图 8.1.5.2 流程示意图 状态订阅流程示意图见图11。 运维管理平台 向专业运维节点发送 /subsystem/v1/subscirbe 专业运维节点 状态订阅处理 处理失败 运维管理平台状 态订阅异常处理 处理成功 结束 图11 状态订阅流程示意图 8.1.5.3 状态订阅功能描述 状态订阅功能描述见表7。 13 DB3502/T 072.2—2021 表7 状态订阅功能描述表 URI /subsystem/v1/subscirbe 功能 运维管理平台订阅应用系统专业运维节点状态，通过订阅通知 URI 通知给运维管理平台 HTTP 方法 POST { 请求消息体 "notifyURI": "http://ip:port/xxxxx" } 请求说明 notifyURI：订阅通知 URI，见 8.1.6 { "code": 0, 返回结果 "message": "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.6 状态订阅通知 8.1.6.1 交互流程 状态订阅通知交互流程见图12，信令流程描述如下： a) 应用系统专业运维节点向运维管理平台发送状态通知，实时通知运维对象状态，包括应用系统 专业运维节点关联的应用系统、服务器、服务实例或管理设备的状态； b) 运维管理平台将操作成功与否的响应返回给应用系统专业运维节点。 专业运维节点 运维管理平台 1 POST "notifyURI": "http://ip:port/xxxxx" 2 response 图12 状态订阅通知交互流程图 8.1.6.2 流程示意图 状态订阅通知流程示意图见图13。 14 DB3502/T 072.2—2021 专业运维节点 向运维管理平台发送状态订阅接口 中notifyURI定义的状态通知接口 运维管理平台 接收状态订阅通知 处理失败 专业运维节点状态 订阅通知异常处理 处理成功 结束 图13 状态订阅通知流程示意图 8.1.6.3 状态订阅通知功能描述 状态订阅通知功能描述见表8。 表8 状态订阅通知功能描述表 URI "notifyURI": "http://ip:port/xxxxx" 功能 应用系统专业运维节点向运维管理平台推送状态变化通知 HTTP 方法 POST [{ "id": "xxxx", "runStatus": 0, 请求消息体 "description": "转发服务异常", "timestamp": 1629860811 }] (R)id：设备 ID，可以是系统 ID、后端服务器设备 ID、服务 ID 或前端设备 ID (R)runStatus：运行状态（0：异常/ 1：正常） 请求说明 (O)description：运行状态描述 (R)timestamp：事件时间 { "code": 0, 返回结果 "message": "" } 结果说明 — 注： R为必选项，O为可选项。 15 DB3502/T 072.2—2021 8.1.7 系统间告警订阅 8.1.7.1 交互流程 系统间告警订阅交互流程见图14，信令流程描述如下： a) 应用系统专业运维节点向运维管理平台发送/nms/v1/subscirbe/alarm 请求； b) 运维系统将操作成功与否的响应返回给应用系统专业运维节点。 专业运维节点 运维管理平台 1 POST /nms/v1/subscirbe/alarm 2 response 图14 系统间告警订阅交互流程图 8.1.7.2 流程示意图 系统间告警订阅流程示意图见图15。 专业运维节点 向运维管理平台发送 /nms/v1/subscirbe/alarm 运维管理平台接 收系统间告警订阅 处理失败 专业运维节点系统间 告警订阅异常处理 处理成功 结束 图15 系统间告警订阅流程示意图 16 DB3502/T 072.2—2021 8.1.7.3 系统间告警订阅功能描述 系统间告警订阅功能描述见表9。 表9 系统间告警订阅功能描述表 URI /nms/v1/subscirbe/alarm 功能 系统专业运维节点间告警订阅 HTTP 方法 POST { "ids": ["xxxxx", "xxxxx"], "alarmCodes": [70001, 70002], 请求消息体 "alarmLevels": [1, 2], "notifyURI": "http://ip:port/xxxxx" } (O)ids：订阅应用系统专业运维节点 id，可订阅多个运维节点，不填表示订阅所有应用系统运 维节点产生的告警（包括运维管理平台） 请求说明 (O)alarmCodes：订阅告警码，可订阅多个告警码，不填表示订阅所有告警码 (O)alarmLevels：订阅告警级别，可订阅多个告警级别，不填表示订阅所有告警级别 (R)notifyURI：订阅通知 URI，见 8.1.8 { "code": 0, 返回结果 "message": "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.8 系统间告警订阅通知 8.1.8.1 交互流程 系统间告警订阅通知交互流程见图16，信令流程描述如下： a) 运维管理平台向应用系统专业运维节点发送告警通知； b) 应用系统专业运维节点将操作成功与否的响应返回给运维管理平台。 17 DB3502/T 072.2—2021 运维管理平台 专业运维节点 1 POST "notifyURI": "http://ip:port/xxxxx" 2 response 图16 系统间告警订阅通知交互流程图 8.1.8.2 流程示意图 系统间告警订阅通知流程示意图见图17。 运维管理平台 向专业运维节点发送 系统间告警订阅接口中notifyURI 定义的告警通知接口 专业运维节点接收 系统间告警订阅通知 处理失败 运维管理平台系统间 告警通知异常处理 处理成功 结束 图17 系统间告警订阅通知流程示意图 8.1.8.3 系统间告警订阅通知功能描述 系统间告警订阅通知功能描述见表10。 18 DB3502/T 072.2—2021 表10 系统间告警订阅通知功能描述表 URI "notifyURI": "http://ip:port/xxxxx" 功能 系统专业运维节点间告警订阅通知 HTTP 方法 POST { "timestamp" : 15427016032, "alarmMsgs" : [{ "id":"31010600001320000009", "name": "kafka 实例", "sourceId": "31010600005200000009", "sourceName": "人脸检测系统专业运维节点", "alarmCode": 70001, 请求消息体 "alarmLevel": 1, "alarmStatus":1, "alarmTime": 13234343, "ip": "设备 IP", "alarmDesc": "告警描述", "alarmDeal": "处理建议", "attachment": "6Ieq5a6a5LmJ5pWw5o2u" }]} (R)id：运维对象 ID，可以是系统专业运维节点 ID、系统 ID、后端服务器设备 ID、服务实例 ID 或前端设备 ID (R)name：运维对象名称 (O)sourceId：运维节点 ID，如果告警对象就是运维节点，该字段可不填写 (O)sourceName：运维节点名称 (R)alarmCode：告警码 请求说明 (R)alarmLevel：告警级别（1：致命，2：严重，3：一般） (R)alarmStatus：告警状态（0：恢复/ 1：告警） (R)alarmTime：告警时间 (O)ip: 设备 IP (R)alarmDesc：告警描述 (O)alarmDeal：处理建议 (O)attachment：附加运维信息，需要 Base64 编码 19 DB3502/T 072.2—2021 表10（续） { "code": 0, 返回结果 "message": "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.9 系统间状态订阅 8.1.9.1 交互流程 系统间状态订阅交互流程见图18，信令流程描述如下： a) 应用系统专业运维节点向运维管理平台发送/nms/v1/subscribe/status 请求； b) 运维管理平台将操作成功与否的响应返回给应用系统专业运维节点。 专业运维节点 运维管理平台 1 POST /nms/v1/subscribe/status 2 response 图18 系统间状态订阅交互流程图 8.1.9.2 流程示意图 系统间状态订阅流程示意图见图19。 20 DB3502/T 072.2—2021 专业运维节点 向运维管理平台发送 /nms/v1/subscribe/status 运维管理平台接 收系统间状态订阅 处理失败 专业运维节点系统间 状态订阅异常处理 处理成功 结束 图19 系统间状态订阅流程示意图 8.1.9.3 系统间状态订阅功能描述 系统间状态订阅功能描述见表11。 表11 系统间状态订阅功能描述表 URI /nms/v1/subscribe/status 功能 应用系统专业运维节点订阅运维管理平台运行信息 HTTP 方法 POST { "ids": ["xxxxx", "xxxxx"], 请求消息体 "notifyUrl": "http://ip:port/xxxxx" } (O)ids：订阅运维对象 ID（目前仅支持订阅系统专业运维节点 ID），可订阅多个系统专业运维 请求说明 节点，不填表示订阅所有运维对象运行状态 (R)notifyUrl：订阅通知 URL，见 8.1.10 { "code": 0, 返回结果 "message": "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.10 系统间状态订阅通知 21 DB3502/T 072.2—2021 8.1.10.1 交互流程 系统间状态订阅通知交互流程见图20，信令流程描述如下： a) 运维管理平台向应用系统发送应用系统专业运维节点自定义订阅通知请求； b) 应用系统专业运维节点将操作成功与否的响应返回给运维管理平台。 运维管理平台 应用系统 1 POST "notifyURI": "http://ip:port/xxxxx" 2 response 图20 系统间状态订阅通知交互流程图 8.1.10.2 流程示意图 系统间状态订阅通知流程示意图见图21。 运维管理平台 向应用系统发送应用系统专业运 维节点状态订阅接口中notifyURI 定义的状态通知接口 专业运维节点 接收系统间状态订 阅通知 处理失败 运维管理平台系统间 状态通知异常处理 处理成功 结束 图21 系统间状态订阅通知流程示意图 22 DB3502/T 072.2—2021 8.1.10.3 系统间状态订阅通知功能描述 系统间状态订阅通知功能描述见表12。 表12 系统间状态订阅通知功能描述表 URI "notifyUrl": "http://ip:port/xxxxx" 功能 订阅通知接口，由应用系统专业运维节点实现 HTTP 方法 POST [{ "id": "xxxx", "runStatus": 0, 请求消息体 "description": "转发服务异常" "timestamp":1341234123 }] (R)id：设备 ID，可以是系统 ID、后端服务器设备 ID、服务 ID 或前端设备 ID (R)runStatus：运行状态（0：异常/ 1：正常） 请求说明 (O)description：运行状态描述 (O)timestamp：状态变化时间 { "code": 0, 返回结果 "message": "" } 结果说明 — 注： R为必选项，O为可选项。 8.1.11 工单报告 8.1.11.1 交互流程 运维对象发现故障，通过工单方式上报运维管理平台，交互流程见图22，信令流程描述如下： a) 应用系统专业运维节点向运维管理平台发工单报告； b) 运维管理平台将操作成功与否的响应返回给应用系统专业运维节点。 23 DB3502/T 072.2—2021 专业运维节点 运维管理平台 1 POST /nms/v1/order 2 response 图22 工单报告交互流程图 8.1.11.2 流程示意图 工单报告流程示意图见图23。 专业运维节点 向运维管理平台发送 /nms/v1/order 运维管理平台接 收工单报告处理 处理失败 专业运维节点工 单报告异常处理 处理成功 结束 图23 工单报告流程示意图 8.1.11.3 工单报告功能描述 工单报告功能描述见表13。 24 DB3502/T 072.2—2021 表13 工单报告功能描述表 URI /nms/v1/order 功能 工单上报接口 HTTP 方法 POST { "timestamp" : 15427016032, "notifyUrl" : "http://x.x.x.x:xxxx/orderNty", "orderMsgs" : [{ "username":"user1", "devName": "湖滨南路厦禾路路口", "devGbid": "32010000112000001", "sourceId": "31010600005200000009", 请求消息体 "sourceName": "人脸检测系统专业运维节点", "alarmCode": 10002, "alarmLevel": 1, "alarmDeal": "告警处理建议", "alarmDesc": "设备图像在夜间非常模糊", "attachment": "6Ieq5a6a5LmJ5pWw5o2u" }] } (R)notifyUrl：工单反馈回调 URL，由专业运维节点实现 (O)username：报修用户，非必填 (R)devName：运维对象名称 (R)devGbid：运维对象国标 ID (O)sourceId：运维节点 ID，如果告警对象就是运维节点，该字段可不填写 请求说明 (O)sourceName：运维节点名称 (O)alarmCode: 故障码 (R)alarmLevel：故障级别 (R)alarmDeal：故障处理建议 (R)alarmDesc：故障描述 (O)attachment：附加运维信息，需要 Base64 编码 25 DB3502/T 072.2—2021 表13（续） { "code": 0, "data": [{ "orderID": "xxxxxxxx", 返回结果 "message": "设备不存在，工单上报失败！" }], "message": "" } (R)orderID：工单编号，为空说明报修失败 结果说明 (R)message：异常描述 工单编号不为空，说明工单上报接口调用成功，但并不代表工单已经报修成功，需要根据 8.1.12 备注 工单反馈接口中复检结果来判断，复检通过代表工单报修成功，复检不通过代表工单报修失败。 注： R为必选项，O为可选项。 8.1.12 工单反馈 8.1.12.1 交互流程 工单反馈交互流程见图24，信令流程描述如下： a) 运维管理平台向应用系统专业运维节点发送工单反馈； b) 应用系统专业运维节点将操作成功与否的响应返回给运维管理平台。 运维管理平台 专业运维节点 1 POST "notifyURI":"http://ip:port/xxxxx" 2 response 图24 工单反馈交互流程图 8.1.12.2 流程示意图 工单反馈流程示意图见图25。 26 DB3502/T 072.2—2021 运维管理平台 向专业运维节点发送 工单报告接口中notifyURI定义的 工单反馈接口 专业运维节点 接收工单反馈 处理失败 运维管理平台工 单反馈异常处理 处理成功 结束 图25 工单反馈流程示意图 8.1.12.3 工单反馈功能描述 工单反馈功能描述见表14。 表14 工单反馈功能描述表 URI "notifyUrl": "http://ip:port/xxxxx" 功能 工单反馈 HTTP 方法 POST { "timestamp" : 15427016032, "orderMsgs" : [{ "orderID":"xxxxxxxx", 请求消息体 "optType": 0, "optTime": 15427016032, "username": "user1" }] } (R)orderID：工单编号 (R)optType：0：维修完成；1：复检通过（表示工单报修成功）；2：复检不通过（表示工单报 请求说明 修失败） (R)optTime：工单修复时间 (O)username：报修用户 27 DB3502/T 072.2—2021 表14（续） { "code": 0, 返回结果 "message": "" } 结果说明 — 注： R为必选项，O为可选项。 前端智能箱系统对接接口 8.2.1 设备列表查询 8.2.1.1 交互流程 设备列表查询交互流程见图26，信令流程描述如下： a) 运维管理平台向前端智能箱系统专业运维节点发送/subsystem/v1/device-list 请求； b) 前端智能箱系统专业运维节点将操作成功与否的响应返回给运维管理平台。 前端智能箱系统 专业运维节点 运维管理平台 1 POST /subsystem/v1/device-list 2 response 图26 设备列表查询交互流程图 8.2.1.2 流程示意图 设备列表查询流程示意图见图27。 28 DB3502/T 072.2—2021 运维管理平台 向前端智能箱系统专业运维节点发送 /subsystem/v1/device-list 前端智能箱系统专业运维 节点接收设备列表查询请求 处理失败 运维管理平台设备 列表查询异常处理 处理成功 结束 图27 设备列表查询流程示意图 8.2.1.3 设备列表查询功能描述 设备列表查询功能描述见表15。 表15 设备列表查询功能描述表 URI /subsystem/v1/device-list?page_num=1&page_size=1000 功能 查询前端智能箱系统关联设备列表 HTTP 方法 请求消息体 POST 无 (O)page_num：页号，从 1 开始 请求说明 (O)page_size：分页大小 如果不传参数，表示查询所有 { "code": 0, "message": "", "data": { "total": 100, "deviceList": [{ 返回结果 "id": "c798deacbf82496d9531eab642caf1cd", "name": "湖滨南路厦禾路路口智能箱 1", "manufacturer": "test", "ip": "172.16.66.66", "port": 9000, "subnetMask": "255.255.255.0", 29 DB3502/T 072.2—2021 表15（续） "gateway": "172.16.66.222", "mac": "00-FF-ED-03-37-EE", "softwareVersion": "v1r1 20190722", "firmwareVersion": "phoenix", "sensorlist": [{ "id": "e7ed2213017c4326be7775c5ac45017f", 返回结果 "name": "湖滨南路厦禾路路口摄像机 1", "manufacturer": "kedacom", "ip": "172.16.64.22" }] }] } } (R)total：根据总数组织后续页码的查询 (R)deviceList：设备列表，包括前端智能箱设备和前端智能箱下挂前端传感器设备 (R)deviceList.id：前端智能箱设备 id，前端智能箱 id 需要和一机一档管理系统前端智能箱 id 保持一致 (R)deviceList.name：名称 (R)deviceList.manufacturer：厂商 (R)deviceList.ip：ip 地址 (O)deviceList.port：端口 (O)deviceList.subnetMask：子网掩码 结果说明 (O)deviceList.gateway：网关 (O)deviceList.mac：mac 地址 (R)deviceList.softwareVersion：软件版本号 (O)deviceList.firmwareVersion：硬件版本号 (R)sensorlist：前端智能箱下挂传感器设备列表 (R)sensorlist.id：设备 id，需要和一机一档管理系统的设备 id 保持一致 (R)sensorlist.name：名称 (R)sensorlist.manufacturer：厂商 (O)sensorlist.ip：ip 地址 注： R为必选项，O为可选项。 30 DB3502/T 072.2—2021 8.2.2 前端智能箱控制 8.2.2.1 交互流程 前端智能箱控制交互流程见图28，信令流程描述如下： a) 运维管理平台向前端智能箱系统专业运维节点发送/subsystem/v1/device/{id}请求； b) 前端智能箱系统专业运维节点将操作成功与否的响应返回给运维管理平台。 前端智能箱系统 专业运维节点 运维管理平台 1 POST /subsystem/v1/device/{id} 2 response 图28 前端智能箱控制交互流程图 8.2.2.2 流程示意图 前端智能箱控制流程示意图见图29。 运维管理平台 向前端智能箱系统专业运维节点发送 /subsystem/v1/device/{id} 前端智能箱系统专业运 维节点接收设备控制请求 处理失败 运维管理平台前端智 能箱控制异常处理 处理成功 结束 图29 前端智能箱控制流程示意图 31 DB3502/T 072.2—2021 8.2.2.3 前端智能箱控制功能描述 前端智能箱控制功能描述见表16。 表16 前端智能箱控制功能描述表 URI /subsystem/v1/device/{id} 功能 控制前端智能箱 HTTP 方法 POST { "sensorid" : "xxx", 请求消息体 "cmd" : "reboot" } id：前端智能箱 id 请求说明 (O)sensorid：前端智能箱下挂传感器设备 id，不填，表示对前端智能箱进行控制 (R)cmd：reboot-重启，poweroff-关闭供电，poweron-开启供电 { "code" : 0, 返回结果 "message" : "" } 结果说明 注： R为必选项，O为可选项。 统一运维对象开放接口 8.3.1 查询设备信息 8.3.1.1 交互流程 查询设备信息交互流程见图30，信令流程描述如下： a) 应用系统向一机一档管理系统发送/kiop-gateway-core/现场网关/queryDeviceInfo 请求； b) 一机一档管理系统将操作成功与否的响应返回给应用系统。 32 DB3502/T 072.2—2021 应用系统 一机一档 1 POST /kiop-gateway-core/现场网关/queryDeviceInfo 2 response 图30 查询设备信息交互流程图 8.3.1.2 流程示意图 查询设备信息流程示意图见图31。 应用系统 向一机一档发送 /kiop-gateway-core/现场网关 /queryDeviceInfo 一机一档接收 查询设备信息请求 处理失败 应用系统进行设备 信息查询异常处理 处理成功 结束 图31 查询设备信息流程示意图 8.3.1.3 查询设备信息功能描述 查询设备信息功能描述见表17。 33 DB3502/T 072.2—2021 表17 查询设备信息功能描述表 URI /kiop-gateway-core/现场网关/queryDeviceInfo 功能 根据授权码、设备类型标识、其他查询条件查询设备信息 HTTP 方法 POST { "apikey":"xxxxxxxx", "key": "xxxxxxxx", "deviceType": "IPC", 请求参数 "code": "xxxx", "pageNo": 1, "pageSize": 20 } (R)apikey：一机一档管理系统授权码（apikey） (R)key：授权码（apikey） (R)deviceType：设备类型标识 请求说明 (O)code：授权用例编码，如果没有权限查询当前设备类型的全部数据，则此参数必传 (O)pageNo：页码，默认值为 1 (O)pageSize：每页条数，默认值为 20，pageSize 不能大于 10000 { "f_eq_deviceAttr.ipc.securityboxId": 'db9b47bedab747c0a249c13a49420ae7', "f_like_name": "测试", "f_in_civilCode": "350211,350205", 请求消息体 "f_not_gbid"："35020000001370000218", "f_notnull_longitude": 1, "f_isnull_latitude": 1 } 查询方式说明： 支持以下几种查询模式：“f_eq”、“ f_like”、 “ f_in”、“ f_not”、“ f_notnull”、“f_isnull”。 请求说明 说明： (1) f_eq_ deviceAttr.ipc.securityboxId = 'db9b47bedab747c0a249c13a49420ae7'，等同于 sql : …… where deviceAttr.ipc.securityboxId = 'db9b47bedab747c0a249c13a49420ae7'； 34 DB3502/T 072.2—2021 表17（续） (2) f_like_name = “测试”，等同于 sql： …… where name like '%测试%'; (3) f_in_civilCode = “350211,350205”, 等同于 sql： …… where civilCode in ('350211','350205'); (4) f_not_gbid = “35020000001370000218”, 等同于 sql： …… where gbid != '35020000001370000218'; (5) f_notnull_longitude = 1，等同于 sql： …… where longitude is not null; (6) f_isnull_latitude = 1，等同于 sql： 请求说明 …… where latitude is null; 查询的是： 所属前端智能箱(deviceAttr.ipc.securityboxId)的值为 'db9b47bedab747c0a249c13a49420ae7'、设备名称（name）中包含“测试”字符串、行政区域 （civilCode）为集美区（350211）和海沧区（350205）、国标 ID（gbid）不等于 “35020000001370000218”、经度（longitude）不为空、纬度（latitude）值为空的设备数 据。 注： deviceAttr.ipc.securityboxId字段是网络摄像机（视图传感器）设备类型的私有字段，网 络摄像机（视图传感器）的设备类型标识（deviceType）为IPC， deviceAttr.ipc中的ipc 为该设备类型标识的toLowerCase()形式。所有以deviceAttr开头的字段均为某个指定设备 类型的私有字段，deviceAttr后面跟着的就是该设备类型的标识的全小写形式。 { "code": "0", "status": 0, "timestamp": 1603431996, "timeElapsed": 35, "result": { 返回结果 "data": [{ "gbid": "32200000001320000011", "name": "测试设备数据 1", "deviceAttr": { "ipc": { "runStatus": ["1"], 35 DB3502/T 072.2—2021 表17（续） "pointType": 1 } } }], "pageNo": 0, 返回结果 "pageSize": 20, "total": 2, "totalPages": 1 } } (R)code：接口返回的结果码 (R)status：接口请求状态 (R)timestamp：时间戳 (R)timeElapsed：响应时间 由于开放的设备属性权限不一致，所以返回的 data 的数据格式不固定。 以仅开放“设备名称”、“国标 ID”、“设备运行状态”、“视频点位类型”为例，数据格式为： (R)result.data.gbid：国标 ID 结果说明 (R)result.data.name：设备名称 (O)result.data.deviceAttr.ipc.runStatus：运行状态 (O)result.data.deviceAttr.ipc.pointType：点位类型 (R)result.pageNo：页码 (R)result.pageSize：每页条数 (O)result.total：设备总数 (R)result.totalPages：总页码数 放在 deviceAttr 中的为设备私有属性，ipc 为网络摄像机（视图传感器）的设备类型标识 备注 （deviceType=IPC）的全小写形式，说明 runStatus 为网络摄像机（视图传感器）的私有属性。 注： R为必选项，O为可选项。 8.3.2 状态结果通知 8.3.2.1 交互流程 状态结果通知交互流程见图32，信令流程描述如下： a) 一机一档管理系统向应用系统发送状态通知请求，URI 由一机一档管理系统配置； b) 应用系统将操作成功与否的响应返回给一机一档管理系统。 36 DB3502/T 072.2—2021 一机一档 应用系统 1 POST http://ip:port/xxxxx 2 response 图32 状态结果通知交互流程图 8.3.2.2 流程示意图 状态结果通知流程示意图见图33。 一机一档 向应用系统发送状态通知请求， 接口URI由一机一档配置 应用系统接收 状态通知请求 处理失败 一机一档状态结 果通知异常处理 处理成功 结束 图33 状态结果通知流程示意图 8.3.2.3 状态结果通知功能描述 状态结果通知功能描述见表18。 37 DB3502/T 072.2—2021 表18 状态结果通知功能描述表 URI http://ip:port/xxxxx 功能 一机一档管理系统向应用系统推送状态变化通知 HTTP 方法 POST { "deviceMsgs": [{ "id": "fcf9e2f27e8d4defa3a0b2ed02092588", "gbid": "10000001031321006703", 请求消息体 "status": 0 }], "operateType": 1, "timestamp": 1574153902002 } (R)deviceMsgs.id：设备 ID (R)deviceMsgs.gbid：国标 ID，全网唯一，应用方根据当前属性进行判定设备的存在与否 (R)deviceMsgs.status：状态（0: 在用/在线；1: 在用/离线；2: 维修；3: 拆除；4: 禁用； 请求说明 99: 空闲） (R)operateType：操作类型（默认值为 1，代表设备状态更新） (R)timestamp：操作时间（时间戳） { "code": 0, 返回结果 "message": "" } 结果说明 注： R为必选项，O为可选项。 38 DB3502/T 072.2—2021 A A 附 录 A （资料性） REST 架构协议模型 A.1 REST 概述 REST是一种通过采用统一方式将所有信息抽象为资源来创建服务的方法，任何能够被命名的信息 都能够作为一个资源。REST使用一个资源标识符（URI）来标识组件之间交互所涉及到的特定资源。REST 组件通过以下方式在一个资源上执行动作：使用一个资源表述来捕获资源的当前或预期的状态、在组件 之间传递该表述，一个表述是一个字节序列，以及描述这些字节序列的表述元数据。 A.2 REST 和 HTTP 方法 REST服务通过HTTP的方法动词来实现，见表A.1。说明如下： ——GET 调用不能改变系统状态，这表示该调用只返回数据给请求者而不会产生任何副作用； ——POST 只能用于添加原先不存在的资源的场合； ——PUT 一般用于更新已经存在资源的场合，但如果指定的资源不存在，也可以创建该资源。 表A.1 HTTP 方法动词表 HTTP 方法 操作(CRUD 操作) POST 创建资源(Create) GET 读取资源(Retrieve) PUT 更新资源(Update) DELETE 删除资源(Delete) A.3 接口访问形式 HTTP URL格式的一般形式为：