2023数字换流站业务交互技术规范

数字换流站业务交互技术规范 1范围本文件规定了数字换流站业务交互部分的系统构成、总体原则和技术要求，包括数据、告警、文件、日志、视频、三维、控制、卡片等业务交互接口。本文件适用于换流站的数字化建设，指导数字换流站的设计、研发、验收和应用。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T22239信息安全技术网络安全等级保护基本要求GB/T30149电网通用模型描述规范3术语和定义数字换流站digitalconverterstation运用先进数字技术、信息技术发展创新成果，统筹布局数字化基础设施，具有强化设备广泛互联、状态深度感知、数据融合贯通、管理精益高效能力的换流站。公共组件publiccomponent具备数据接入、处理、存储和分析能力，对外提供服务接口供应用调用，支撑业务应用功能实现的软件。基础应用basicapplication具备一定的生产业务处理能力，满足运行监视、运维分析、业务管控等共性数字化需求的应用软件。高级应用advancedapplication具有较强专业性或信息综合处理能力的应用软件，是基础应用的增强和补充，满足状态预测、健康评估、诊断分析等生产业务的差异化需求。4缩略语API：应用程序接口（ApplicationProgrammingInterface）CIM：公共信息模型（CommonInformationModel）JSON：数据交换格式（JavaScriptObjectNotation）MQ：消息队列（MessageQueue）URL：统一资源定位系统（UniformResourceLocator）XML：可扩展标记语言（ExtensibleMarkupLanguage）UTF-8：8位元可变长度统一码（万国码）字符编码（UnicodeTransformationFormat-8bit）5系统构成数字站公共组件由若干数据组件和业务组件组合而成，公共组件基于基础数据实现业务功能的处理和响应；作为服务端，公共组件对外提供一系列业务交互接口，支撑应用获取数据、告警、文件等信息。数字站业务交互框架如图1所示。业务交互支持本地及远方访问数字站公共组件等，业务交互应满足如下主要功能：a) 提供请求订阅实时数据的能力；b) 提供请求存储历史数据的能力；c) 提供请求订阅告警数据的能力；d) 提供请求发送文件数据的能力；e) 提供请求获取视频数据的能力；f) 提供请求获取三维模型的能力；g) 提供请求数据模型的能力；h) 提供请求设备台账数据的能力。图1数字站业务交互框架示意图6总体原则业务交互应遵循以下基本技术原则：a) 业务交互应通过微服务架构实现统一的信息访问接口；b) 交互接口参数应采用JSON格式定义；c) 交互接口应具备权限校验机制；d) 安全防护应符合GB/T22239规定，。7技术要求7.1接口交互7.1.1总体要求公共组件与应用之间使用统一的数据交互接口，数据交互内容使用UTF-8编码的JSON格式字符串，用于应用读取公共组件的实时数据、收发公共组件的告警消息、读写公共组件的历史数据、文件数据、视频数据以及三维数据等，交互数据分为请求接口输入参数和回调接口返回参数，交互时需要进行用户权限校验。7.1.2交互内容公共组件与应用之间交互的数据内容如下：a) 实时数据：包括装置上送的模拟量、相量量测、状态量的实时变化数据；b) 历史数据：包括公共组件存储的状态量、模拟量等历史数据；c) 告警数据：包括实时告警数据和历史告警数据；d) 文件数据：包括录波文件、图形文件等；e) 日志数据：包括应用运行日志、操作日志等；f) 视频数据：包括视频流、快照图片等；g) 三维数据：包括三维信息、三维画面等。7.1.3交互方式公共组件与应用之间的数据交互方式包括数据查询、数据订阅（WebSocket方式）、数据订阅（消息队列）和数据存储四种方式，要求如下：a) 数据查询：应用通过主动请求方式查询需要的数据，交互方式采用HTTP（HTTPS）协议，使用RESTful设计风格，查询的数据应支持查询条件过滤，查询的数据类型包括实时数据、历史数据、告警数据和文件数据等，数据查询交互方式如图2所示；b) 数据订阅（WebSocket方式）：应用主动向公共组件建立WebSocket连接，并向公共组件进行数据订阅，订阅后公共组件周期向应用推送订阅的数据，同时实时推送变化的数据，订阅的数据应支持查询条件过滤，数据订阅（WebSocket方式）如图3所示；c) 数据订阅（消息队列方式）：应用通过消息中间件以订阅主题的方式请求数据，公共组件通过消息中间件周期向应用推送订阅的数据，同时实时推送变化的数据，数据订阅（消息队列方式）如图4所示；d) 数据存储：应用调用公共组件提供的历史数据交互接口写入需要保存的历史数据，交互方式采用HTTP（HTTPS）协议，使用RESTful设计风格，数据存储交互方式如图5所示。图2数据查询图3数据订阅（WebSocket方式）图4数据订阅（消息队列方式）图5数据存储7.2接口定义7.2.1总体要求接口是由公共组件基于微服务框架提供的一组服务，用于读取和修改数据、收发消息、读写文件等。接口风格参照RESTfulAPI规范，以HTTP(s)URL的形式体现资源和对应的接口方法。完整的接口方法由域名（IP地址）、版本、路径（端点）、HTTP动词（GET和POST）、过滤信息（参数）、状态码、返回结果等组成。7.2.2URL接口采用的HTTP(s)URL形式，如表1所示，接口URL中各组成部分的说明如下所列，如表2所示。表1HTTP(s)URL形式序号URL组成形式1http(s)://{host}:{port}/v{n}/cs/{endpoint}表2URL组成部分序号URL组成部分说明1{host}:{port}采用http协议访问接口所需的主机地址和端口2cs固定词，表示数字站3v{n}表示版本号，如当前版本号为v14{endpoint}表示路径（端点），用于标识具体的接口采用本文件的接口URL中，{endpoint}之前的部分（即“http(s)://{host}:{port}/v{n}/cs/”或者“http(s)://{}/v{n}/cs/”）需根据数字站的情况进行组装。具体的接口内容在{endpoint}部分定义。7.2.3请求方法查询和数据获取类型的接口，采用HTTPGET方法。其他类型的接口采用HTTPPOST方法。如表3所示。表3请求方法方法描述GET读取动作POST请求动作7.2.4消息头部消息头部如表4所示。表4消息头部属性名称类型是否必选Content-Type交互类型：权限认证交互（application/x-www-form-urlencoded）、其它交互（application/json）String是Authorizationtoken令牌String是X-HW-IDAPI网关身份认证IDString否X-HW-APPKEYAPI网关身份认证KEYString否7.2.5请求体请求体为JSON格式的对象，应具有以下字段，如表5所示。表5请求体属性名称类型是否必选id请求IDInt是clientId客户端Id（应用注册时由权限认证服务提供）String是body请求内容（具体内容见各接口详细说明）Object是7.2.6返回体返回体为JSON格式的对象，应有以下字段，如表6所示。表6返回体属性名称类型是否必选id请求IDInt是code返回码（应符合表A.1）String是message返回码描述String是body返回内容（具体内容见各接口详细说明）Object是7.3接口功能7.3.1权限认证管理总体要求应符合OAuth2.0要求，应用前后端交互的权限认证宜采用客户端模式，对接口进行访问认证和安全管控。应用部署时，应在管理平台注册备案，获取两个身份识别码，客户端ID（clientid）和客户端密钥（clientsecret）。应用在调用公共组件接口时，权限认证服务通过验证令牌和白名单确保服务调用方的合法性。令牌默认有效期为24小时，超时后需要重新调用接口获取新的令牌。权限获取权限获取接口定义如表7所示，客户端请求Content-Type为application/x-www-form-urlencoded，请求参数采用表单传值方式，如表8所示，返回成功时数据格式定义如表9所示。表7权限获取接口定义请求方法POST请求地址/auth-service/oauth/token协议应用http(s)表8权限获取请求体定义属性名称类型是否必选描述grant_typeToken类型String是固定填写client_credentialsscope信号索引键String是固定填写allclient_id客户端账号String是客户端账号，由平台分配client_secret客户端密码String是客户端密码，由平台分配表9权限获取返回体定义属性名称类型描述access_token认证TokenString获取到的令牌token_typeToken类型StringToken类型expires_in过期时间Long过期时间scope权限范围String表示申请的权限范围，默认为allcode返回码String应符合表A.1message返回码描述String返回码对应的描述信息jti声明String唯一标识符权限校验权限校验接口定义如表10所示，请求参数采用表单传值方式，其定义如表11所示，校验成功时返回数据格式定义如表12所示，校验失败时返回数据格式定义如表13所示。表10权限校验接口定义请求方法POST请求地址/auth-service/oauth/check_token协议应用http(s)表11权限校验请求体定义属性名称类型是否必选描述token令牌String是待校验的令牌表12权限校验成功返回体定义属性名称类型是否必选描述client_id客户端IDString是client的配置项即客户端IDscope授权范围String[]是由请求时参数决定expaccess_token有效期Long是默认有效期为86400秒active是否有效Boolean是token是否有效sub被授权方String是一般就是当前用户IDiss授权方String是站名@授权方，示例如poyanghu@nrecuser_name当前用户名String否当前用户名（仅针对web用户）last_login上次登陆时间戳Long是如果未登陆过，则为0pri用户角色String[]是用户具备的角色集合account统一账户名String否ISC的唯一账户名（仅针对web用户）obj_id统一账户用户IDString否ISC的唯一账户用户ID（仅针对web用户） 表13权限校验失败返回数据属性名称类型描述succ是否成功Boolean是否校验成功code错误码String校验错误码message错误信息String校验错误信息path请求路径String请求路径timestamp校验时间Long校验时间用户同步用户同步接口定义如表14所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表15所示，Condition的定义如表16所示。请求成功时，返回体中body定义如表17所示，其中SysUser的结构如表18所示。请求失败时，返回体中body定义为空。表14用户同步接口定义请求方法POST请求地址sys-service/sys/user协议应用http(s)表15用户同步请求体body定义属性名称类型是否必选描述id人员主键ID列表List<String>否需查询的人员列表,为空时查所有人员信息attributes属性列表List<String>否需返回的属性列表，不填返回所有conditions检索条件List<Condition>否检索条件列表，不填无条件表16用户同步请求参数Condition定义属性名称类型是否必选描述dept_id部门IdString否所属部门Idorg_id单位IdString否所属单位Idif_effective检索值Boolean否人员是否有效，默认所有表17用户同步成功时返回体body定义属性名称类型描述values人员列表List<SysUser>查询到的人员列表表18用户同步返回参数SysUser定义属性名称类型描述obj_id人员主键String最大长度42staff_name人员姓名String最大长度60order_no显示顺序Intdept_id所属部门IdString最大长度42org_id所属单位IdString最大长度42account登录账户String最大长度50create_time创建时间String格式要求为"yyyy-MM-ddHH:mm:ss.SSS"syn_time同步时间String格式要求为"yyyy-MM-ddHH:mm:ss.SSS"cancel_time撤销时间String格式要求为"yyyy-MM-ddHH:mm:ss.SSS"if_effective是否有效Stringtrue:有效，false:无效staff_post人员岗位String最大长度50staff_subject人员专业String最大长度50staff_sex人员性别String人员性别(0:女,1:男)telphone内线电话String最大长度50cardid身份证String最大长度52source数据来源Stringisc:数据同步,owner:自身新增组织同步组织同步接口定义如表19所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表20所示，Condition的定义如表21所示。请求成功时，返回体中body定义如表22所示，其中SysOrg的结构如表23所示。请求失败时，返回体中body定义为空。表19组织同步接口定义请求方法POST请求地址sys-service/sys/org协议应用http(s)表20组织同步请求体body定义属性名称类型是否必选描述id部门主键IDString否需查询的部门根节点及其子节点,为空时查所有部门组织信息attributes属性列表List<String>否需返回的属性列表，不填返回所有conditions检索条件List<Condition>否检索条件列表，不填无条件表21组织同步请求参数Condition定义属性名称类型是否必选描述manage_level管理级别String否管理级别表22组织同步成功时返回体body定义属性名称类型描述values部门列表List<SysOrg>查询到的部门列表表23组织同步返回数据SysOrg定义属性名称类型描述obj_id部门主键String最大长度42dept_name部门名称String最大长度200dept_style部门性质String最大长度50dept_code部门编码String最大长度50p_id上级IdString最大长度42p_name上级部门名称String最大长度200order_no显示顺序Intmanage_level管理级别String最大长度20dept_simp部门简称String最大长度100create_time创建时间String格式要求为"yyyy-MM-ddHH:mm:ss.SSS"syn_time同步时间String格式要求为"yyyy-MM-ddHH:mm:ss.SSS"cancel_time撤销时间String格式要求为"yyyy-MM-ddHH:mm:ss.SSS"if_effective数据有效性Intprovince_id所属网省String最大长度42province_name所属网省名称String最大长度200municipa_id所属地市String最大长度42municipa_name所属地市名称String最大长度200county_id所属供电公司（县局）String最大长度42county_name所属供电公司名称String最大长度200dept_level单位级别String最大长度30，判断省市公司path_name组织全路径String最大长度500path_id组织全路径IdString最大长度500if_cancel是否撤销String最大长度5source数据来源Stringisc:数据同步,owner:自身新增unicode统一编码String最大长度50pms_idPMS映射主键String最大长度50station_type站的类别String最大长度17.3.2查询模型数据管理通用模型查询接口公共组件支持应用获取指定设备模型相关数据信息，设备模型应符合GB/T30149和Q/GDW10703。接口定义如表24所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表25所示。请求成功时，返回体中body定义如表26所示，其中Data结构字段以请求参数中field字段查询的数据结构为准，如表27所示。请求失败时，返回体中body定义为空。表24通用模型查询接口定义请求方法POST请求地址mdldata-service/model协议应用http(s)表25通用模型查询请求体body定义属性名称类型是否必选描述field查询的数据结构String是mrid,name,description,…。特定选择字段，多个字段时用英文逗号分隔，不允许使用*,每个datetype类型支持的field列表见模型文档。datatype数据类型String是1.Station，厂站2.Area，区域3.Voltagelevel，电压等级4.Bay，间隔5.Equipment，一次设备6.Analog，模拟量7.State，状态量8.Accumulator，遥脉量9.Assettype，设备类型10.Component，设备部件11.可根据具体场景约定扩展condition查询条件String是SQL语句的where条件，查询条件应防止SQL注入。必须指定查询条件，如不指定，则公共组件直接返回查询失败，其中analog/state/accumulator需支持按mrid（模拟量/离散量/累加量标识）、astid（所属设备资产ID）、psrid（所属设备资源ID）、astuid（所属设备通用识别码ID）、flagcode(应用标记码)进行过滤查询。表26通用模型查询成功时返回体body定义属性名称类型描述data返回数据信息Data数据表27通用模型查询返回数据Data定义属性名称类型描述mridId值Long例“4222124802768902”name名称String例“A相电压”desc描述String例“A相电压”parentid父节点String例“029020000000000002092756”dimension单位String例“kV”type类型Int例“6”calvalue值Long例“220.156”根据mrid查询数据公共组件支持应用按需根据mrid查询当前数据。接口定义如表28所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表29所示。请求成功时，返回体中body定义如表30所示。请求失败时，返回体中body定义为空。表28根据mrid查询数据接口定义请求方法POST请求地址mdldata-service/model/getByMrid协议应用http(s)表29根据mrid查询数据请求体body定义属性名称类型是否必选描述mridmridList<String>是根据mrid查询具体记录tableName表名String是根据模型规范传入表名表30根据mrid查询数据成功时返回体body定义属性名称类型描述values信号值列表List<Map>查询到的信号值列表根据mrid更新测点属性公共组件支持应用按需根据mrid更新测点的静态属性。接口定义如表31所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表32所示。请求成功/失败时，返回体中body定义为空。表31根据mrid更新测点属性接口定义请求方法POST请求地址mdldata-service/model/updateAttrsByMrid协议应用http(s)表32根据mrid更新测点属性请求体body定义属性名称类型是否必选描述datatype测点类型String是analog/statemrid测点idString是测点mridfields属性列表List<String>是需要更新的属性列表，目前支持morelowerlimit（下下限）lowerlimit（下限）upperlimit（上限）moreupperlimit（上上限）flagcode（应用标记码）属性values值List<Object>是需要更新的值列表，顺序和fields顺序保持一致7.3.3实时数据管理查询实时数据公共组件支持应用按需查询实时数据的值。接口定义如表33所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表34所示。请求成功时，返回体中body定义如表35所示，其中Data的结构如表36所示。请求失败时，返回体中body定义为空。表33查询实时数据接口定义请求方法POST请求地址realdata-service/data/realtime协议应用http(s)表34查询实时数据请求体body定义属性名称类型是否必选描述datatype数据类型String是需查询的数据类型(analog/state/accumulator),为空时不限定类型keys信号索引键List<String>是需查询的信号列表表35查询实时数据成功时返回体body定义属性名称类型描述values信号值列表List<Data>查询到的信号值列表表36查询实时数据返回数据Data定义属性名称类型描述key信号索引键String信号的mridvalue值Double信号值quality品质Int描述信号的品质，0为有效，1为无效time_stamp刷新时间String描述信号的刷新时间，格式要求为"yyyy-MM-ddHH:mm:ss.SSS"订阅实时数据（WebSocket方式）公共组件支持应用通过WebSocket方式按需或全量订阅数据，一般用于前后端交互。接口定义如表37所示。请求体中body数据的定义如表38所示。WebSocket服务端根据订阅情况，转发实时数据，数据遵循7.2中关于返回体的定义，如果是单个测点数据返回，即请求体中package为0，或者不带package属性，返回体格式如表39所示，如果是批量测点数据返回，即请求体中package为1，返回体body格式定义如表40所示，其中Data的结构如表41所示。表37订阅实时数据（WebSocket方式）接口定义请求方法WebSocket请求地址ws-service/register协议应用WebSocket表38订阅实时数据（WebSocket方式）请求体body定义属性名称类型是否必选描述token令牌String是表征鉴权令牌action动作类型String是表示执行的操作类型，subscribe订阅，unsubscribe退订subscribetype订阅类型Int否0，周期推送，1变化推送，2周期加变化推送，默认周期推送interval推送周期Int否单位秒，最小30秒，默认1800秒package是否组包Int否0组包，1不组包，默认不组包datatype数据类型String是订阅的数据类型(analog/state),为空时不限定类型keys信号索引键List<String>是需订阅（退订）的信号列表，在订阅时，如果为空则表示全部订阅表39订阅实时数据（不组包）成功时返回体body定义属性名称类型描述key信号索引键String信号的mridvalue值Object信号值quality品质Int描述信号的品质，0为有效，1为无效name名称String描述信号的名称datatype测点类型Stringanalog/statetime_stamp时间String描述信号的刷新时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSS表40订阅实时数据（组包）成功时返回体body定义属性名称类型描述values信号值列表List<Data>查询到的信号值列表reason推送原因Int0，周期推送，1变化推送，2周期加变化推送表41订阅实时数据（组包）返回数据Data定义属性名称类型描述key信号索引键String信号的mridvalue值Object信号值quality品质Int描述信号的品质，0为有效，1为无效name名称String描述信号的名称datatype测点类型Stringanalog/statetime_stamp时间String描述信号的刷新时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSS订阅实时数据（消息队列方式）消息队列方式只支持全量订阅，应用端按需处理。接口定义如表42所示，消息队列方式时，只需要按需订阅相关主题，可以使用通配的方式通过过滤key值订阅一组数据，公共组件服务端定时或按变化向消息队列发布实时数据，应用按订阅获取数据，返回body定义如表43所示。表42订阅实时数据（消息队列方式）接口定义请求方法消息队列TOPICT_DC_MQ_REALDATA协议应用消息队列组件SDK，key为信号键，支持通配符模式表43订阅实时数据（消息队列方式）成功时返回体body定义属性名称类型描述key信号索引键String信号的mrid。value值Object信号值quality品质Int描述信号的品质，0为有效，1为无效name名称String描述信号的名称datatype测点类型Stringanalog/statetime_stamp时间String描述信号的刷新时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSS存储实时数据公共组件支持应用存储更新实时数据。接口定义如表44所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表45所示，其中Data的结构如表46所示。请求成功或者失败时，返回体中body都定义为空。表44存储实时数据接口定义请求方法POST请求地址realdata-service/data/realtime/store协议应用http(s)表45存储实时数据请求体body定义属性名称类型是否必选描述datatype数据类型String是存储的数据类型(analog/state),为空时不限定类型values信号值列表List<Data>是存储的信号值列表表46存储实时数据请求参数Data定义属性名称类型描述key信号索引键String信号的mridvalue值Object信号值quality品质Int描述信号的品质，0为有效，1为无效time_stamp时间String描述信号的采集时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSSdescription信号描述String描述7.3.4关系库数据管理查询历史数据管理公共组件支持应用按需查询指定一组遥测信号的历史数据。单次查询数据返回总量不应超过10万条，超过一定量时，返回调用失败，提示采用分批多次取数据方式获取数据，以防网络拥堵。接口定义如表47所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表48所示。请求成功时，返回体中body定义如表49所示，其中HisData的结构如表50所示，HisDataVal的结构如表51所示，部分失败时对应信号的vals值为空。请求失败时，返回体中body定义为空。表47查询历史数据接口定义请求方法POST请求地址hisdata-service/data/history协议应用http(s)表48查询历史数据请求体body定义属性名称类型是否必选描述datatype数据类型String是需查询的数据类型(analog/state/accumulator),为空时不限定类型keys信号索引键List<String>是需查询的信号列表startTime开始时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSendTime结束时间String是结束时间（不含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSinterval取值间隔Int是取值间隔，如：5，表示5分钟取一个值count是否查询统计值Int否0，不返回统计值，1，返回统计值表49查询历史数据成功时返回体body定义属性名称类型描述values信号值列表List<HisData>查询到的信号值列表表50查询历史数据返回数据HisData定义属性名称类型描述key信号索引键String信号的mridvals值List<HisDataVal>历史数据列表表51查询历史数据返回数据HisDataVal定义属性名称类型是否必选描述time时刻String是采样时刻，格式要求为：yyyy-MM-ddHH:mm:ss.SSSvalue值Double是遥测值favgvalue平均值Double否（入参count为1时返回）过去5分钟平均值fmax极大值Double否（入参count为1时返回）过去5分钟极大值fmin极小值Double否（入参count为1时返回）过去5分钟极小值tmax极大值时间String否（入参count为1时返回）格式要求为：yyyy-MM-ddHH:mm:ss.SSStmin极小值时间String否（入参count为1时返回）格式要求为：yyyy-MM-ddHH:mm:ss.SSS查询关系库元数据公共组件支持应用按需查询关系库数据。接口定义如表52所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表53所示。请求成功时，返回体中body定义如表54所示。请求失败时，返回体中body只包含noun。表52查询关系库元数据接口定义请求方法POST请求地址db-service/GetMetaData协议应用http(s)表53查询关系库元数据请求体body定义属性名称类型是否必选描述nounCIM名称String是对应关系库的物理表名称表54查询关系库元数据成功时返回体body定义属性名称类型描述nounCim名称String查询表名attributes属性列表List<String>返回的属性列表查询关系库数据公共组件支持应用按需查询关系库数据。接口定义如表55所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表56所示，Condition定义如表57所示，Operator支持列表如表58所示，多个condition之间是“逻辑或”的关系，condition内部多组条件之间是“逻辑与”的关系。请求成功时，返回体中body定义如表59所示。请求失败时，返回体中body只包含noun。表55查询关系库数据接口定义请求方法POST请求地址db-service/GetData协议应用http(s)表56查询关系库数据请求体body定义属性名称类型是否必选描述nounCIM名称String是对应关系库的物理表名称attributes属性列表List<String>是需返回的属性列表conditions检索条件List<condition>是检索条件列表表57查询关系库数据请求参数Condition定义属性名称类型是否必选描述attribute属性名String是对应关系库的物理表字段名称operator比较符String是见下表value检索值String是检索值表58查询关系库数据请求参数Operator支持列表Operator含义LIKELikeEQ=NE!=GT>LT<GE>=LE<=INIn（对应值列表以英文逗号分隔）表59查询关系库数据成功时返回体body定义属性名称类型描述count记录数Int返回记录数nounCim名称String查询表名attributes属性列表List<String>返回的属性列表recs值列表List<JSON>返回的值列表存储关系库数据公共组件支持应用按需存储关系库数据。接口定义如表60所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表61所示。请求成功或失败时，返回体中body定义如表62所示。表60存储关系库数据接口定义请求方法POST请求地址db-service/PutData协议应用http(s)表61存储关系库数据请求体body定义属性名称类型是否必选描述nounCIM名称String是对应关系库的物理表名称attributes属性列表List<String>是需插入的属性列表recs值列表List<JSON>是需插入的值列表表62存储关系库数据成功时返回体body定义属性名称类型描述nounCim名称String查询表名更新关系库数据公共组件支持应用按需更新关系库数据。接口定义如表63所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表64所示。请求成功或失败时，返回体中body定义如表65所示。表63更新关系库数据接口定义请求方法POST请求地址db-service/UpdateData协议应用http(s)表64更新关系库数据请求体body定义属性名称类型是否必选描述nounCIM名称String是对应关系库的物理表名称attributes属性列表List<String>是需更新的属性列表recs值列表List<JSON>是需更新的值列表，目前只支持单条记录更新conditions条件列表List<condition>是更新条件,详见章节表65更新关系库数据成功时返回体body定义属性名称类型描述nounCim名称String查询表名7.3.5系统事件告警管理订阅实时告警（WebSocket方式）公共组件支持应用通过WebSocket方式按需或全量订阅实时告警，一般用于前后端交互。接口定义如表66所示，请求体中body数据的定义如表67所示，其中Conditions定义如表68所示，WebSocket服务端根据订阅情况，转发实时告警，返回body定义如表69所示，其中Warn的结构如表70所示。表66订阅实时告警（WebSocket方式）接口定义请求方法WebSocket请求地址ws-service/register协议应用WebSocket表67订阅实时告警（WebSocket方式）请求体body定义属性名称类型是否必选描述token令牌String是表征鉴权令牌action动作类型String是表示执行的操作类型，subscribe订阅，unsubscribe退订conditions过滤条件Conditions是用于筛选告警数据表68订阅实时告警（WebSocket方式）Conditions定义属性名称类型是否必选描述deviceId设备IDList<String>否订阅设备的编号列表level告警级别List<Int>否告警级别列表，对告警级别进行过滤,应符合表B.1type告警类型List<String>否告警类型列表，对告警类型进行过滤keywords关键词List<String>否关键词列表，对告警内容进行模糊匹配，关键词之间为或关系表69订阅实时告警（WebSocket方式）成功时返回体body定义属性名称类型描述warns告警列表List<Warn>查询到的告警列表表70订阅实时告警（WebSocket方式）返回数据Warn定义属性名称类型是否必选描述idIDString是告警id唯一标识areaid区域IDString是告警所属区域idareaname区域名称String是告警所属区域名称isreport是否含有简报Boolean是标识是否含有简报内容time时间String是告警发生时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSSsystemid主机String是所属主机redundantsystem系统String是所属系统deviceId所属设备String是告警相关设备IDlevel告警级别Int是应符合表B.1type子系统或设备String是告警类型，应符合表C.1content告警描述String是告警内容描述eventstatus动作名称String是动作名称isconfirm是否确认String是true已确认,false未确认pointId告警标识String是由告警发送端生成的告警ID订阅实时告警（消息队列方式）消息队列方式只支持全量订阅，应用端按需处理。接口定义如表71所示，消息队列方式时，只需要按需订阅相关主题，可以使用通配的方式订阅一组设备的告警，公共组件服务端定时或按变化向消息队列发布实时告警，应用按订阅获取告警，数据遵循7.2中关于返回体的定义，其body定义如表72所示，其中Warn的结构如表73所示。表71订阅实时告警（消息队列方式）接口定义请求方法消息队列TOPICT_DC_MQ_ALARM协议应用消息队列组件SDK，deviceId为设备编码，支持通配符模式表72订阅实时告警（消息队列方式）成功时返回体body定义属性名称类型描述warns告警列表List<Warn>查询到的告警列表表73订阅实时告警（消息队列方式）返回数据Warn定义属性名称类型是否必选描述time时间String是告警发生时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSSsystemid主机String是所属主机redundantsystem系统String是所属系统deviceId所属设备String是告警相关设备IDlevel告警级别Int是应符合表B.1type子系统或设备String是告警类型，应符合表C.1content告警描述String是告警内容描述eventstatus动作名称String是动作名称isconfirm是否确认String是true已确认,false未确认pointId告警标识String是由告警发送端生成的告警ID请求历史告警公共组件支持应用查询历史告警，并支持简单的筛选。接口定义如表74所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表75所示，其中conditions定义如表76所示。请求成功时，返回体中body定义如表77所示，其中Warn的结构如表78所示，请求失败时，返回体中body定义为空。表74请求历史告警接口定义请求方法POST请求地址alarm-service/warn/history协议应用http(s)表75请求历史告警请求体body定义属性名称类型是否必选描述startTime开始时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSendTime结束时间String是结束时间（不含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSpageNum当前页码数Int否查询的页码数pageSize每页显示条数Int否每页返回条目数conditions过滤条件Conditions是用于筛选告警数据表76请求历史告警请求参数Conditions定义属性名称类型是否必选描述level告警级别String否应符合表B.1，支持多个等级过滤，英文分号分隔,例如“0;1;2”redundantsystem系统Char否系统：A、B、C，eventactive值班备用Int否1值班、0备用systemid主机String否支持通配符*和多个关键字，多个关键字之间用;分隔deviceId设备String否告警相关设备ID多个设备ID之间用英文;分隔type子系统类型String是类型：“监控”/“辅控”/“高级应用”分别表示监控、辅控告警和高级应用告警content告警描述String否支持通配符*和多个关键字，多个关键字之间用;分隔eventstatus动作名称String否支持通配符*和多个关键字，多个关键字之间用;分隔isconfirm消息状态String否true已确认,false未确认pointid告警事件idString否支持通配符*和多个关键字，多个关键字之间用;分隔表77请求历史告警成功时返回体body定义属性名称类型是否必选描述data告警列表List<Warn>是查询到的告警列表,列表按照时间降序排列，最新的告警排在数组前部total返回告警数Int否返回告警总数，分页查询时返回表78请求历史告警返回数据Warn定义属性名称类型是否必选描述time时间String是告警发生时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSSsystemid主机String是所属主机redundantsystem系统String是所属系统eventactive备用Int是1值班、0备用deviceId所属设备String是告警相关设备IDlevel告警级别Int是告警级别，应符合表B.1type子系统类型String是类型：“监控”/“辅控”/“高级应用”分别表示监控、辅控告警和高级应用告警content告警描述String是告警内容描述eventstatus动作名称String是动作名称isconfirm是否确认String是true已确认,false未确认pointId告警标识String是由告警发送端生成的告警IDid告警主键idString是告警主键id查询未复归事件公共组件支持应用查询未复归事件列表，并支持按条件筛选。接口定义如表79所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表80所示，其中Conditions定义如表81所示。请求成功时，返回体中body定义如表82所示，其中Warn的结构如表83所示，请求失败时，返回体中body定义为空。表79查询未复归事件接口定义请求方法POST请求地址/alarm-service/realdata/getM2FaultList协议应用http(s)表80查询未复归事件请求体body定义属性名称类型是否必选描述startTime开始时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSendTime结束时间String是结束时间（不含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSconditions过滤条件Conditions是用于筛选告警数据表81查询未复归事件请求参数Conditions定义属性名称类型是否必选描述level告警级别String否应符合表B.1，支持多个等级过滤，英文分号分隔,例如“0;1;2”redundantsystem系统Char否系统：A、B、C，eventactive值班备用Int否1值班、0备用systemid主机String否支持通配符*和多个关键字，多个关键字之间用;分隔deviceId设备String告警相关设备ID多个设备ID之间用英文;分隔type子系统类型String是类型：“监控”/“辅控”/“高级应用”分别表示监控、辅控告警和高级应用告警content告警描述String否支持通配符*和多个关键字，多个关键字之间用;分隔eventstatus动作名称String否支持通配符*和多个关键字，多个关键字之间用;分隔isconfirm消息状态String否true已确认,false未确认pointid告警事件idString否支持通配符*和多个关键字，多个关键字之间用;分隔表82查询未复归事件成功时返回体body定义属性名称类型描述data告警列表List<Warn>查询到的告警列表表83查询未复归事件返回数据Warn定义属性名称类型是否必选描述time时间String是告警发生时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSSsystemid主机String是所属主机redundantsystem系统String是所属系统eventactive备用Int是1值班、0备用deviceId所属设备String是告警相关设备IDlevel告警级别Int是告警级别，应符合表B.1type子系统类型String是类型：“监控”/“辅控”/“高级应用”分别表示监控、辅控告警和高级应用告警content告警描述String是告警内容描述eventstatus动作名称String是动作名称isconfirm是否确认String是true已确认,false未确认pointId告警标识string是由告警发送端生成的告警ID推送应用故障告警公共组件支持接收应用发送的分析故障告警，公共组件负责处理和存储。接口定义如表84所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表85所示，其中Warn的结构如表86所示，Alarm的结构如表87所示，Report的结构如表88所示。请求成功时，返回告警主键id列表，返回体中body定义如表89所示，请求失败时，返回体中body定义为空。表84推送应用故障告警接口定义请求方法POST请求地址alarm-service/appalarm/sendalarm协议应用http(s)表85推送应用故障告警请求体body定义属性名称类型是否必选描述warns告警列表List<Warn>是存储的告警列表表86推送应用故障告警请求参数Warn定义属性名称类型是否必选描述alarm告警内容Alarm是report简报内容Report否表87推送应用故障告警请求参数Alarm定义属性名称类型是否必选描述client_id系统标识String是发送告警的系统标识time告警时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSareaid区域IDString否区域mridareaname区域名称String否stationid电站IDString否电站mridstationname电站名称String否deviceid设备IDString否设备mriddevicename设备名称String否partid部件IDString否部件mridpartname部件名称String否type子类型String否各系统内部分类eventlevel告警级别Int是应符合表B.1eventdesc事件描述String是eventaction动作名称String是isreport是否拥有简报Boolean否表88推送应用故障告警请求参数Report定义属性名称类型是否必选描述client_id系统标识String是发送告警的系统标识time告警时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSeventdesc事件描述String否eventreason告警原因String否eventhandle处理办法String否analysisdata相关数据String否analysiswave相关波形String否波形url地址analysispic相关图像String否图像url地址analysisvideo相关视频String否视频url地址analysisreport相关报告String否报告url地址alarmRect报警位置区域String否获得人员报警图像位置controllingArea管控区域String否管控区域位置信息表89推送应用故障告警成功时返回体body定义属性名称类型描述id信号值列表List<String>成功推送的告警id列表更新故障简报接口公共组件支持更新应用发送的故障简报，公共组件负责处理和存储。接口定义如表90所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表91所示，其中Warn的结构如表92所示，report的结构如表93所示。请求成功/失败时，返回体中body定义为空。表90更新故障简报接口接口定义请求方法POST请求地址alarm-service/appalarm/sendreport协议应用http(s)表91更新故障简报接口请求体body定义属性名称类型描述reports告警列表List<Report>存储的告警列表表92更新故障简报接口请求参数Report定义属性名称类型是否必选描述report简报内容Warn是表93更新故障简报接口请求参数Warn定义属性名称类型是否必选描述id告警idString是与推送返回的告警id一致cliend_id系统标识String是发送告警的系统标识time告警时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSeventdesc事件描述String否eventreason告警原因String否eventhandle处理办法String否analysisdata相关数据String否analysiswave相关波形String否波形url地址analysispic相关图像String否图像url地址analysisvideo相关视频String否视频url地址analysisreport相关报告String否报告url地址alarmRect报警位置区域String否获得人员报警图像位置controllingArea管控区域String否管控区域位置信息查询应用故障告警公共组件支持应用查询历史告警，并支持简单的筛选。接口定义如表94所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表95所示，其中conditions定义如表96所示，请求成功时，返回体中body定义如表97所示，其中Warn的结构如表98所示。请求失败时，返回体中body定义为空。表94查询应用故障告警接口定义请求方法POST请求地址alarm-service/appalarm/history协议应用http(s)表95查询应用故障告警请求体body定义属性名称类型是否必选描述startTime开始时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSendTime结束时间String是结束时间（不含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSpageNum当前页码数Int否查询的页码数pageSize每页显示条数Int否每页返回条目数conditions过滤条件Conditions是用于筛选告警数据表96查询应用故障告警Conditions定义属性名称类型是否必选描述client_id应用IDString否信息来源的系统IDareaid区域IDString否信息来源的区域IDdeviceid设备IDList<String>否订阅设备的编号列表eventlevel告警级别List<Int>否告警级别列表，对告警级别进行过滤,应符合表B.1type告警类型List<String>否告警类型列表，对告警类型进行过滤keywords关键词List<String>否关键词列表，对告警内容进行模糊匹配表97查询应用故障告警成功时返回体body定义属性名称类型描述data告警列表List<Warn>查询到的告警列表total返回告警总数Int返回告警总数，分页查询时返回表98查询应用故障告警返回数据Warn定义属性名称类型是否必选描述idIDString是告警id唯一标识client_id系统标识String是发送告警的系统标识time告警时间String是格式要求为：yyyy-MM-ddHH:mm:ss.SSSareaid区域IDString是区域mridareaname区域名称String是stationid电站IDString是电站mridstationname电站名称String是deviceid设备IDString是设备mriddevicename设备名称String是partid部件IDString是部件mridpartname部件名称String是type子类型String是各系统内部分类eventlevel告警级别Int是应符合表B.1eventdesc事件描述String是eventaction动作名称String是isconfirm是否确认String是true已确认,false未确认confirmtime确认时间String是格式要求为：yyyy-MM-ddHH:mm:ss.SSSconfirmman确认人String是isreport是否拥有简报String是查询应用故障简报公共组件支持应用查询故障简报，并支持简单的筛选。接口定义如表99所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表100所示。请求成功时，返回体中body定义如表101所示，其中report的结构如表102所示。请求失败时，返回体中body定义为空。表99查询应用故障简报接口定义请求方法POST请求地址alarm-service/appalarm/getreport协议应用http(s)表100查询应用故障简报请求体body定义属性名称类型是否必选描述idIDString是告警事件IDtime时间String否格式要求为：yyyy-MM-ddHH:mm:ss.SSS表101查询应用故障简报成功时返回体body定义属性名称类型描述report告警列表Report表102查询应用故障简报返回数据Report定义属性名称类型是否必选描述idIDLong是uuid唯一标识client_id系统标识String是发送告警的系统标识time告警时间String是格式要求为：yyyy-MM-ddHH:mm:ss.SSSeventdesc事件描述String是eventreason告警原因String是eventhandle处理办法String是analysisdata相关数据String是analysiswave相关波形String是波形url地址analysispic相关图像String是图像url地址analysisvideo相关视频String是视频url地址analysisreport相关报告String是报告url地址alarmRect报警位置区域String否获得人员报警图像位置controllingArea管控区域String否管控区域位置信息推送告警处理结果告警处理后向平台消息中间件推送处理结果，供其他第三方应用订阅。接口定义如表103所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表104所示，其中info的结构如表105所示，请求成功/失败时，返回体中body定义为空。表103推送告警处理结果定义请求方法POST请求地址alarm-service/appalarm/sendconfirminfo协议应用http(s)表104推送告警处理结果请求体body定义属性名称类型是否必选描述info告警内容Info是表105推送告警处理结果Info定义属性名称类型是否必选描述cliend_id系统标识String是发送告警的系统标识alarmid告警idString是告警的唯一标识time处理的timeString是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSman处理人String否handle处理内容String否0订阅告警处理结果告警处理后向平台消息中间件推送处理结果后，可以通过消息订阅的方式，向消息中间件订阅处理结果消息。接口定义如表106所示，消息队列方式时，只需要按需订阅相关主题，可以使用通配的方式订阅一组设备的告警处理结果，返回数据如表107所示。表106订阅告警处理结果接口定义端口和地址消息队列TOPICT_DC_MQ_ALARM_CONFIRM协议应用消息队列组件SDK表107订阅告警处理结果成功时返回体body定义属性名称类型描述cliend_id系统标识String发送告警的系统标识alarmid告警idString告警的唯一标识time处理的timeString开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSman处理人Stringhandle处理内容String1推送设备状态接口公共组件支持接收应用发送的设备状态，公共组件负责处理和存储。接口定义如表108所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表109所示，其中Data的结构如表110所示。请求成功/失败时，返回体中body定义为空。表108推送设备状态接口定义请求方法POST请求地址/alarm-service/equipment/sendstatus协议应用http(s)表109推送设备状态请求体body定义属性名称类型是否必选描述data请求内容List<Data>是表110推送设备状态请求参数Data定义属性名称类型是否必选描述cliend_id系统标识String是发送告警的系统标识equipment_id设备idString是设备资产idequipment_type设备类型Int是0：设备，1：部件status设备状态Int是设备当前状态(0：正常，1：异常，2：严重)2查询设备状态接口公共组件支持查询设备状态。接口定义如表111所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表112所示。请求成功时，返回体中body定义如表113所示，其中Status的结构如表114所示。请求失败时，返回体中body定义为空。表111查询设备状态接口接口定义请求方法POST请求地址/alarm-service/equipment/getstatus协议应用http(s)表112查询设备状态接口请求体body定义属性名称类型是否必选描述equipment_id设备idList<String>是需要设备资产id数组表113查询设备状态接口成功时返回体body定义属性名称类型是否必选描述status请求内容List<Status>是表114查询设备状态接口返回数据Status定义属性名称类型是否必选描述equipment_id设备idString是设备资产idequipment_type设备类型Int是0：设备，1：部件status设备状态Int是设备当前状态(0：正常，1：异常，2：严重)cliend_id系统标识String是发送告警的系统标识updatetime状态更新时间String是平台收到状态推送的时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSS3高级应用告警确认公共组件支持应用高级应用告警确认。接口定义如表115所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表116所示。请求成功/失败时，返回体中body定义为空。表115高级应用告警确认接口定义请求方法POST请求地址/alarm-service/appalarmconfirm协议应用http(s)表116高级应用告警确认请求体body定义属性名称类型是否必选描述attrOid告警idString是高级应用告警主键idattrTime告警时间String是高级应用告警时间,格式要求为：yyyy-MM-ddHH:mm:ss.SSSconfirmhandle处理意见String否处理结果confirmman处理人String是处理人confirmtime告警处理时间String否告警处理时间,格式样例"yyyy-MM-ddHH:mm:ss"4系统事件告警确认公共组件支持应用监控系统事件告警确认。接口定义如表117所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表118所示。请求成功/失败时，返回体中body定义为空。表117系统事件告警确认接口定义请求方法POST请求地址/alarm-service/owsalarmconfirm协议应用http(s)表118系统事件告警确认请求体body定义属性名称类型是否必选描述attrOid告警idString是监控告警的主键idconfirmTime处理时间String是监控告警处理时间,格式要求为：yyyy-MM-ddHH:mm:ss.SSSconfirmhandle处理意见String否处理结果confirmman处理人String是处理人pointid监控告警事件idString是监控告警事件id7.3.6文件数据管理查询文件数据公共组件支持应用查询文件数据，并支持简单的筛选。接口定义如表119所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表120所示，其中conditions定义如表121所示。请求成功时，返回体中body定义如表122所示，其中File的结构如表123所示。请求失败时，返回体中body定义为空。表119查询文件数据接口定义请求方法POST请求地址filedata-service/file/list协议应用http(s)全部采用全部采用表120查询文件数据请求体body定义属性名称类型是否必选描述conditions过滤条件conditions是用于筛选文件数据表121查询文件数据请求参数Conditions定义属性名称类型是否必选描述deviceId设备IDList<String>是设备的编号列表type文件类型List<String>否文件类型列表startTime开始时间String是开始时间（含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSendTime结束时间String是结束时间（不含），格式要求为：yyyy-MM-ddHH:mm:ss.SSSkeywords关键词List<String>否关键词列表，对文件名进行模糊匹配，关键词之间为或关系表122查询文件数据成功时返回体body定义属性名称类型描述files文件列表List<File>查询到的文件信息列表表123查询文件数据返回数据File定义属性名称类型描述id文件IDString系统自编文件唯一IDtime时间String文件创建时间，格式要求为：yyyy-MM-ddHH:mm:ss.SSSname文件名称String文件名称hash检验码String基于sha256或者md5算法计算的文件校验码deviceId设备编码String文件来源设备编码type文件类型String文件格式类型，如scd/xml/json/wave/png等size字节数Long文件字节大小文件下载公共组件应支持根据文件标识号码下载或文件名下载方式。根据文件标识号码下载方式接口定义如表124所示，应遵循7.2中消息头部相关定义，请求地址中的id为设备的唯一索引编码。根据文件名下载方式接口定义如表125所示，应遵循7.2中消息头部相关定义，请求地址中的name为文件的文件名。表124文件下载（根据文件标识号码）接口定义请求方法GET请求地址/file/download/deviceId/{id}协议应用http(s)表125文件下载（根据文件名）接口定义请求方法GET请求地址/file/download/name/{name}协议应用http(s)文件上传公共组件支持上传文件。接口定义如表126所示，应遵循7.2中消息头部相关定义，请求地址中的deviceId为文件来源设备编码，请求成功时，返回体中body定义如表127所示。请求失败时，返回体