《2023数字换流站业务交互技术规范.docx》由会员分享，可在线阅读，更多相关《2023数字换流站业务交互技术规范.docx（58页珍藏版）》请在课桌文档上搜索。
1、数字换流站业务交互技术规范目次前言借误!未定义书婪.I范围3I规范性引用文件34缩略语37技术要求4附；1（规范性）返回码56附录B规范性）告警级别58附录C（规范性）告警类型5911数字换流站业务交互技术规范1范围本文件规定了数字换流站业务交互部分的系统构成、总体原则和技术要求，包括数据、告警，文件、日志、视频、三维、控制、卡片等业务交互接口。本文件适用于换流站的数字化建设，指导数字换流站的设计、研发、验收和应用。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注H期的引用文件，仅该日期对应的版本适用于本文件：不注日期的引用文件，其最新版本(包括所TF的
2、修改单)适用于本文件。GB/T22239信息安全技术网络安全等级保护基本要求GB/T30149电网通用模型描述规范3术语和定义3.1数字换流站digitalconverterslation运用先进数字技术、信息技术发展创新成果，统等布同数字化基础设施.具有强化设普广泛互联、状态深度感知、数据融合贯通、管理精益高效能力的换流站。公共组件publiccomponent具备数据接入、处理、存储和分析能力，对外提供服务接口供应用调用，支撑业务应用功能实现的敢件。3.3基础应用basicapplication具备定的生产业务处理能力，满足运行腔视、运维分析、业务管控等共性数字化需求的应用软件。3.4 .
3、高级应用advancedapplication具有较强专业性或信息综合处理能力的应用软件，是基础应用的增强和补充，满足状态预测、健康评估、诊断分析等生产业务的差异化需求。4B语API:应用程序接口(ApplicationProgrammingInterface)CIM：公共信息模型(CommonInformalionModel)JSON：数据交换格式(JavaScriptObjectNotation)MQ：消息队列(MessageQueue)URL：统资源定位系统(UniformResourceLocator)XML：可扩展标记语言(ExtensibleMarkupLanguage)UTF-8
4、：8位元可变长度统码(万国码)字符编码(UniCOdCTransformationFormat-8bit)5系统构成数字站公共组件由若干数据组件和业务组件组合而成，公共组件基于基础数据实现业务功能的处理和响应；作为服务端，公共组件对外提供一系列业务交互接II,支撑应用获取数据、告警、文件等信息。数字站业务交互框架如图1所示。业务交互支持本地及远方访问数才站公共组件等，业务交互应满足如下主要功能:提供请求订阅实时数据的能力：提供请求存储历史数据的能力：提供请求订阅告警数据的能力：提供清求发送文件数据的能力：提供请求获取视频数据的能力：提供请求获取二维模型的能力：提供请求数据模型的能力:星*白图1
5、数字站业务交互框架示意图提供请求设备台账数据的能力.6总体原则业务交互应遵循以下基本技术原则:a) b)c) d)业务交互应通过微服务架构实现统的信息访问接口*交互接口参数应采用JSON格式定义：交互接口应具备权限校验机制J:安全防护应符合GB/T22239规定，。7技术要求7.1 接口交互7.1.1 总体要求公共组件与应用之间使用统一的数据交互接口，数据交互内容使用17F-8编码的JSON格式字符串，用于应用读取公共组件的实时数据、收发公共组件的告警消息、读写公共组件的历史数据、文件数据、视频数据以及三维数据等，交互数据分为请求接口输入参数和回调接口返回参数，交互时需要进行用户权限校验。7.
6、12 交互内容公共组件与应用之间交互的数据内容如下：Hb Cd ef B实时数据：包括装置上送的模拟量、相量量测、状态量的实时变化数据；历史数据：包括公共组件存储的状态量、模拟量等历史数据：告警数据：包括实时告警数据和历史告警数据；文件数据：包括录波文件、图形文件等:日志数据：包括应用运行日志、操作日志等：视频数据：包括视频流、快照图片等；三维数据：包括三维信息、三维画面等。7.13 3交互方式公共组件与应用之间的数据交互方式包括数据查询、数据订阅（WebSockel方式）、数据订阅（消息队列）和数据存储四种方式，要求如Ma）数据查询：应用通过主动请求方式查询需要的数据，交互方式采用HTTP（
7、HTTPS）协议，使用RESTful设计风格，查询的数据应支持查询条件过港，查询的数据类型包括实时数据.历史数据、告警数据和文件数据等，数据查询交互方式如图2所示：b）数据订阅（WebSoCkel方式）：应用主动向公共组件建立WebSoCkel连接，并向公共组件进行数据订阅，订阅后公共组件周期向应用推送订阅的数据，同时实时推送变化的数据，订阅的数据应支持查询条件过泄，数据订阅CebSoCket方式）如图3所示:c）数据订阅（消息队列方式）：应用通过消息中间件以订阅主题的方式请求数据，公共组件通过消息中间件周期向应用推送订阅的数据，同时实时推送变化的数据，数据订阅（消息队列方式）如图4所示:d）
8、数据存储：应用调用公共组件提供的历史数据交互接口写入需要保存的历史数据，交互方式采用HTTP（HTTPS）协议，使用RESTfUl设计风格，数据存储交互方式如图5所示。图3数据订阅（WebSoCket方式）图4数据订阅(消息队列方式)图5数据存储7.2 接口定义7.2.1 2.1总体要求接口是由公共组件基于微服务框架提供的一组服务.用于读取和修改数据、收发消息、读写文件等口接口风格参照RESTfUIAPI规范.以HTTP(三)URL的形式体现资源和对应的接口方法。完整的接口方法由域名(IP地址)、版本、路径(端点)、HTTP动词(GET和POST)、过i信息(参数)、状态码、返回结果等组成。7
9、.2.2URL接口采用的HTTP(s)URL形式，如表1所示，接口URL中各组成部分的说明如下所列，如表2所示.表1HTTP(s)URL形式序号URL组成形式1http(s):/host:IportJv(ncs(endpoint表2URL组成部分序号URLffl成部分说明1host:!port采用http协仪访问接【I所需的主机地址和端112CS固定词，表示数字站.3n表示版本号，如当前版本号为Vl4(endpoint表示路径(端点)，用于标设具体的接口采用本文件的接11URL中,endpoint之前的部分(BP,*http(s)host:port)v(ncsw或者“Mtp(s)/dO/vn)
10、/cs/D需根据数字站的情况进行组装。具体的接口内容在endpoint部分定义。7.2.3 请求方法直询和数据获取类型的接口，采用InTPGET方法。其他类型的接口采用HTTPPOST方法。如表3所示。表3请求方法方法描述GET读取动作POST请家动作7.2.4 消息头部消息头部如表4所示。表4消息头部属性名称类型是否必选Content-Type交互类型：权限认证交互(application-mform-urlencoded)其它交互(application/json)String是Authorizationtoken令牌String是X-HW-IDAH网关身份认证IDString否X-Iff
11、i-APPKEYAPI网关身份认证KEYString否7.2.5 请求体请求体为JSON格式的对象，应具有以下字段，如表5所示。表5请求体属性名称类型是否必选id请求IDInt是clientId客户端Id（应用注册时由权限认证服务提供）String是body请求内容（具体内容见各接I1详细说明）Object是7.2.6返回体返回体为JSoN格式的对象.应有以下字段，如表6所示。表6返回体属性名称类咀是否必选Id请求IDInt是code返回妈（应符合表A.DString是message返回码描述String是body返回内容（具体内容冗各接H洋细说明）Object是7.3 接口功能7. 31权限
12、认证管理7.3.1.1总体要求应符合OAUth2.0要求，应用前后端交互的权限认证宜采用客户端模式，对接口进行访问认证和安全管控。应用部署时，应在管理平台注册备案，获取两个身份识别码.客户端ID（clientid）和客户端密钥（clientsecret）.应用在调用公共组件接口时，权限认证服务通过验证令牌和白名单确保服务调用方的合法性。令牌默认有效期为24小时，超时后需要重新调用接口获取新的令牌。7.31.2权限获取权限获取接口定义如表7所示，客户端请求Content-Type为application/xnww-forrUrlencodecl,请求参数采用表单传值方式，加表8所示，返回成功时数
13、据格式定义如表9所示。表7权限获取接口定义请求方法FOST请求地址Zauth-ServiceZoauthZtoken协议应用http(s)表8权限获取请求体定义属性名称类型是否必选描述grant-lypeTOken类型String是固定填写client-credentilsscope信号索引String是固定填写allClient_id客户端账号String是客户端账号，由平台分配clicnt-secrct客户端密码String是客户端密码，由平台分配表9权限获取返回体定义属性名称奥型描述accesstoken认证TokenString获取到的令牌token.typeToken类型String
14、Token烫型eKpires_in过期时间Long过期时间scope权眼范困StrinR表示申请的权限范困，默认为allcode返回码String应符合表A.】message返回码描述String返回码对应的描述信息jti声明String唯一标识符7.3.1.3权限校哈权限校验接口定义如表10所示，请求参数采用表取传值方式，其定义如表11所示，校验成功时返回数据格式定义如表12所示，校验失败时返回数据式定义如表13所示。表10权限校验接口定义请求方法POST请求地址/auth-service/oauth/check_token依议应用http(s)表11权限校验请求体定义璃性名称类型是否必选描
15、述token令牌String是特校验的令牌表12权限校验成功返回体定义属性名称类型是否必选描述clicnt_id客户端IDString是client的配置项即客户端IDscope授权爸围Strig是由请求时参数决定CXpacccss_token有效期LonX是默认有效期为86400秒active是否有效Boolean是token是否有效sub被授权方String是一般就是当麓用户IDISS授权方String是站名0授权方，示例如PoyHnghutnrecuser_name当前用户名String否当前用户名（仅针对Web用户）last-logi上次霞Mi时间IaLong是如果未登Pt过，则为0P
16、ri用户角色Strig是用户具备的角色集合account统滕户名String否ISC的唯微户名（仅计对IIeb用户）obj.id统一账户用户IDSlrinR否ISC的唯一账户用户ID（仅针对WCb用户）表13权限校验失败返回数据属性名称类型描述SUCC是否成功Boolean是否校验成功code槽误码String校验悟码ucssane错误信息StrinR校验错误信息path请求路径String语求路径timostaMp校验时间L削喀校验时间7.31.4用户同步用户同步接11定义如表14所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表15所示，Conditio
17、n的定义如表16所示.清求成功时，返回体中body定义如表17所示，其中SySUSOr的结构如表18所示。请求失败时，返问体中body定义为空.表14用户同步接口定义请求方法POST请求地境sys-service/sys/uscr协议应用http（E）表15用户同步请求体body定义属性名称类型是否必选描述id人员主健ID列表List否帝查询的人员列表，为空时查所有人员信息attributes属性列表List否需返回的属性列表，不填返回所有conditions椅素条件List否检素条件列表，不填无条件表16用户同步请求参数COnditiQn定义属性名称类型是否必选描述dcpt_id部门IdSt
18、ring否所属部门Idorg_id单位IdString否所同单位Idifeffective检索值Boolean否人员是否有效，默认所有表17用户同步成功时返回体body定义膈性名称类型描述values人员列表List杳询到的人员列衣表18用户同步返回参数SySUSer定义属性名称类型描述obj_id人员生健String最大长度42sUffna11M?人员姓名Strinx最大长度60CTder-no显示1r序Intdeptid所属部门IdStrinx依大长度42org_id所属单位IdString最大长度42account登录账户Strinx最大长度50create_t.ie创建时间String
19、格式要求为*yyyy-MM-ddHH:i:ss.SSS*syntine同步时间String格式要求为y,yy-MW-ddHH:ma:ss.SSS*cancel_tix撤销时间String格式要求为yyyyTM-ddHH：m：ss.SSS*ineffective是否有效Stringtrue:有效,false:无效staff_post人员岗位String最大长度50staffsubject人员专业String最大长度50Staff-SeX人M性别String人员性用（0:女,1:男）teiphone内钱电话String最大长度50cardid身份证String最大长度52source数据来海Str
20、ingIsc:数据同步.OWner:自身新增7.31.5组织同步组织同步接口定义如表19所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表20所示，COndilion的定义如表21所示.请求成功时，返回体中body定义如表22所示，其中SySorg的结构如表23所示.请求失败时，返回体中body定义为空。表19组织同步接口定义请求方法POST请求地址sys-service/sys/org孙议应用http(s)表20组织同步请求体body定义属性名称类型是否必选描述id部门主键IDString否需交询的部门根节点及其子节点，为空时查所有部门组织信息attrib
21、utes属性列表List否需返回的属性列表.不填返ISI所有conditions检索条件List否检索条件列表，不填无条件表21组织同步请求参数Condition定义属性名称类型是否必选描述managelevel管理级别String否管理级别表22组织同步成功时返回体body定义属性名称类型描述values部门列表List杳询到的部门列表表23组织同步返回数据SySOrg定义属忤名称类型描述bjid部门生逞String最大长度42dept_name部门名称String最大长度200(iept_style都门性质String最大长度50deptcode部门摘码String最大长度50p_id上级
22、IdStrine最大长度42p_name上级部门名称StringJa大长度200order_no显示顺序Intmunagelevel管理级别String最大长度20depJsimp部门简称String最大长度100crent-time创建时间String格式要求为yyyy-MMYdHH:mm:ss.SSSrsyn-tie同步时间String格式要求为yyyy-MM-ddIIH:mm:ss.SSS*cancel-time撤怖时间String格式要求为yyyy-MMddI11111m:ss.SSS*ineffective数据有效性IntIl属性名称类型描述province_id所夙网省String
23、最大长度42provincenae所属网否名称StringJR大长度200municipa_id所属地市String最大长度42nuicipa-nae所属地市名称StrinJB大长度200county-id所属供电公司（县同）String最大长度42countyname所属供电公司名称String级大长度200deptlevel单位级别String最大长度30.判断省市公司path_IWmC铝投全路径Strinx最大长度500path_id组织全路轻IdString城大长度500if_canccl是否撤销String最大长度5source数据来源Stringisc:数抵同步,OWner:自身新
24、增Unicode统一编码Strin最大长度50PaLS_idPMS映射士城String最大长度50Stationtypc站的类别SIrinR最大长度17.32查询模型数据管理7.3,2.1通用模型查询接口公共组件支持应用获取界定设备模型相关数据信息.设备模型应符合GB/T30149和Q/GDW10703.接口定义如表24所示，应遵循7.2中消息头部、请求体、返回体的相关定义.诘求体中body数据的定义如表25所示。诺求成功时，返回体中body定义如表26所示，其中Data结构字段以请求参数中field字段杳询的数据结构为准，如表27所示.请求失败时，返回体中body定义为空.表24通用模型查询
25、接口定义请求方法P05T请求地址mdldatiiservice/nodel协议应用https表25通用模型查询清求体body定义属性名称娄型是否必选描述field杳询的数据结构String是mridrname,description,.特定选择字段，多个字段时用英文迅号分隔，不允许使用*.每个Chtetype类型支持的field列表见模型文档。datatype数据类型StrinR是!.Station*厂站2. Area,区域3. Voltagelevelt电乐等级4. Bay,间隔5. Equipment.次设拜6. Analog,模拟*7. State.状态量8. AccuMilator.遥
26、脉崎9. Asseltype,设备类型10. Cnmponent.改备部件IL可根据具体场景的定/展condition杳询条件String是SQL语句的Where条件.查询条件应防止SQL注入。必缜指定查询条件.如不指定.则公共组件直接返回我询失败，其中analog/stateccumuIator需支持按mrd（模报量/高散氏崇加仅桃识八Mtid（所用设番资产ID）、PSrid（所属设符资源ID）、BBtuid（所属设备通用识别码nn、flaRcodc（应用标记码）进行过渔变询。表26通用模型查询成功时返回体body定义属性名称类型描述data返回数据信息Data数据表27通用模型查询返回数据
27、Data定义典性名称类型描述ridIdffiLong例m4222124802768902hname名称String例“A相电压desc描述String例“A相电压parentid父节点Strin例“029020000000000002092756”dimension单位String例“kV”tyg类型Int例Wcalvalue值IQng例j220.I5S117.3,2.2根据mrid查询数据公共组件支持应用按需根据nrid查询当前数据。接口定义如表28所示，应遵循7.2中消息头部、请求体、返回体的相关定义.请求体中body数据的定义如表29所示.请求成功时.返回体中body定义如表30所示.i
28、求失败时，返回体中body定义为空.表28根据mrid查询数据接口定义请求方法POST请求地址dldata-scrvicc/modcl/RctByMiid协议应用http(s)表29根据mrid查询数据请求体body定义属性名称类型是否必选描述mridBridList是根据mrid直询具体记录IableName表名String是根据模型规耗传入表名表30根据mrid查询数据成功时返回体body定义属性名称类型描述values信号值列表List查询到的信号值列表7.3.2.3根据Erid更新测点属性公共组件支持应用按斋根据mrid更新测点的静态属性。接口定义如表31所示，应遵循7.2中消息头部、
29、请求体、返回体的相关定义.请求体中bdy数据的定义如表32所示。请求成功/失败时，返回体中body定义为空。表31根据mrid更新测点属性接口定义请求方法POST请求地址Hidldata-Servicemdel/UpdaLeAttrsByMrid协汉应用http(s)表32根据mrid更新测点属性请求体body定义属性名称类型是否必逸描述datatype货I点类型String是analog/statemrid测点idString是需点IIridfields属性列表List是隔要史新的屈性列表，目前支持IlOrCIOWoriilIit（下下限Iowerlimit（下限）upperlimit（上限
30、）nreupperliait（上上眼Clagcode（应用标记码）属性values值List是需要更新的值列表，顺序和fields顺序保持致7.3.3 实时数据管理7.33.1查询实时数据公共组件支持应用按需直询实时数据的值。接口定义如表33所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表34所示.请求成功时，返回体中Mdy定义如表35所示，其中Daui的结构如表36所示.请求失败时，返回体中body定义为空.33查询实时数据接口定义请求方法POST请求地址rea1data-service/data/rcaItimc协议应用http(s)表34查询实时数据
31、请求体body定义属性名称类型是否必选描述datatype敷据类型String是需杳询的数据类T（analog/state/accumulator）r为空时不限定类型keys信号索引犍List是需查询的信号列表表35查询实时数据成功时返回体body定义屈性名称类型描述values信号值列表List查询到的信号值列表表36查询实时数据返回数据Data定义税性名称交型描述key信号索引健String信号的ridvalue值Double信号捎quality品质Int描述信号的品质，0为有效.1为无效tie-stamp刷新时间String描述信号的刷新时间格式要求为yyyy-*W-ddm：mm:ss.
32、SS57.3.3.2订阅实时数据（WebSOCket方式）公共组件支持应用通过WebSOCket方式按需或全量订阅数据，般用于前后端交互.接口定义如表37所示。请求体中body数据的定义如表38所示。WcbSockct服务端根据订阅情况，转发实时数据，数据遵循7.2中关于返回体的定义，如果是单个测点数据返回，即请求体中PKkagC为0,或者不带PaCkage属性，返回体格式如表39所示，如果是批量测点数据返回，即请求体中PaCkage为L返回体body格式定义如表40所示，JH1Daca的结构如表41所示。表37订阅实时数据（WebSoCket方式）接口定义请求方法IebSocket请求地址w
33、s-serviceregistert议应用IebSocket表38订阅实时数据（WebSgket方式）请求体body定义属性名称类型是否必选描述token令牌String是表征鉴权令牌action动作类型String是表示执行的操作类型.SUbSCribe订阅.IInSUbSCribe退订Subscribetypc订间类型Int否0,周期推送，1变化推送，2周期加变化推送，默认周期推送interval推送周期Int否单位秒，最小30秒，默认1800秒package是否统包Int否0组包.1不组包.默认不组包datatype数据类型StrinK是订阅的数据类型U三k/statc）,为空时不限定类
34、型keys信号索引雄List是需订阅退订）的信号列我，在订阅时，如果为空则表示全部g表39订阅实时数据（不组包）成功时返回体body定义属性宕称类型描述key信号索引键String信号的aridvalue值Object信号值Quality品质Int描述信号的品质，Q为有效，1为无效nune名称String描述信号的名称datatype测点类型Stringanalog/Statetiae_5taiDp时间String描述信号的刷新时间格式要求为：yyy）TM-ddIilkrrm:ss.SSS表40订阅实时数据（组包）成功时返回体body定义隔性名称炎型描述values信号值列表List查询到的倍
35、号值列表reason推送原因Int0,周期推送，1变化推送，2周期加变化推送表41订阅实时数据（组包）返回数据Data定义.属性名称类型描述key信号索引健String信号的mridvalue值Object信号值quality品质Int描述信号的品质，Q为有效，1为无效nume名称String描述信号的名称datatype测点类型Stringanalog/statetie-stamp时间String描述信号的刷新时间.格式要求为：yyyjrMMddHH:nn:ss.SSS73.3.3订阅实时数据（消息队列方式）消息队列方式只支持全量订阅，应用端按需处理。接口定义如表42所示，消息队列方式时，只
36、需要按需订阅相关主3B，可以使用通配的方式通过过滤key值订阅一组数据，公共组件服务端定时或按变化向消息队列发布实时数据，应用按订阅获取数据，返回body定义如表43所示。表42订阅实时数据（消息队列方式）接口定义请求方法消息队列TOPICDCMQRealdatat办议应用消息队列组件SDK,key为信号犍.支持通配符模式表43订阅实时数据（消息队列方式）成功时返回体body定义屈性名称类型描述key信号索引键Strinx信号的mrid。value值Object信号值quality品而Int描述信号的品质.0为有效，1为无效name名称String描述信号的名称datatype测点类型Stri
37、nxanalog/statetiestamp时间String描述信号的刷新时间.格式要求为：yyyy-MM-ddIflkrrm:ss.SSS7.3.3.4存储实时数据公共组件支持应用存储更新实时数据。接口定义如表44所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表45所示，其中Dala的结构如表46所示。请求成功或者失败时，返问体中body都定义为空。表44存储实时数据接口定义请求方法POST请求地城rcaldata-scrvice/data/roaltincstore协议应用http(s)表45存储实时数据请求体body定义局性名称类型是否必选描述dat
38、atype数据类型String是存储的数据类里QrUIIOg/state）.为空时不限定类型属性名称类型是否必选描述values侑号值列表List是存储的信号值列表衰46存储实时数据请求参数DaS定义属性名称类型描述key信号索引键StrinK信号的ridvalue值Object伯号值quality品质Int描述信号的品质.0为有效，1为无效tine一StamP时间String描述信号的采集时间，格式要求为：yyyy-MM-ddHH:n*:ss.SSSdescription信号描述String描述7.3.4 关系库数据管理7.3.5 34.1查询历史数据管理公共组件支持应用按需查询指定一组遥测
39、信号的历史数据。单次查询数据返回总量不应超过10万条.超过一定屈时，返回调用失败，提示采用分批多次取数据方式获取数据，以防网络拥堵.接口定义如表47所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中body数据的定义如表48所示.清求成功时，返回体中body定义如表19所示，其中HisData的结构如表50所示，HisDataVaI的结构如表51所示.部分失败时对应信号的vals值为空。请求失败时，返回体中body定义为空。表47查询历史数据接口定义请求方法POST请求地址hisdata-service/data/historyt办议应用http(4表48查询历史数据请求体bod
40、y定义属性名称类型是否必选描述datatype数据类型String是需杳询的数据类型(aalogstateaccumIator),为空时不限定类型keys信号索引雄List是需杳血的信号列表StartTiae开始时间String是开始时间(#)*格式要求为：yyyy-MM-ddIDI:Mn:ss.SSSendTime结束时间String是结束时间(不含),格式要求为：yyyy-MM-ddHH：nw:ss.SSSinterval取值间隔Int是取值间隔，如：5.表示5分钟取一个值count是否查词统计值Int否0.不返回统il值1,返回统计值表49查询历史数据成功时返回体body定义膈性名称类型描述values信号值列表List杳询到的信号的列丧表50查询历史数据返回数据HiSData定义属性名称类型描述keyf号素引械String信号的Bridvals值LisKHisDataVaP历史数据列表表51查询历史数据返回数据HiSDataVal定义属性名称类型是否必选描述time时刻String是.采样时刻，格式要求为：yyyy-MM-ddHH:mm:ss.SSSvalue值
