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

数字换流站业务交互技术规范目次前言借误!未定义书婪.I范围3I规范性引用文件34缩略语37技术要求4附；1（规范性）返回码56附录B规范性）告警级别58附录C（规范性）告警类型5911数字换流站业务交互技术规范1范围本文件规定了数字换流站业务交互部分的系统构成、总体原则和技术要求，包括数据、告警，文件、日志、视频、三维、控制、卡片等业务交互接口。本文件适用于换流站的数字化建设，指导数字换流站的设计、研发、验收和应用。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注H期的引用文件，仅该日期对应的版本适用于本文件：不注日期的引用文件，其最新版本(包括所TF的修改单)适用于本文件。GB/T22239信息安全技术网络安全等级保护基本要求GB/T30149电网通用模型描述规范3术语和定义3.1数字换流站digitalconverterslation运用先进数字技术、信息技术发展创新成果，统等布同数字化基础设施.具有强化设普广泛互联、状态深度感知、数据融合贯通、管理精益高效能力的换流站。公共组件publiccomponent具备数据接入、处理、存储和分析能力，对外提供服务接口供应用调用，支撑业务应用功能实现的敢件。3.3基础应用basicapplication具备定的生产业务处理能力，满足运行腔视、运维分析、业务管控等共性数字化需求的应用软件。3.4 .高级应用advancedapplication具有较强专业性或信息综合处理能力的应用软件，是基础应用的增强和补充，满足状态预测、健康评估、诊断分析等生产业务的差异化需求。4B§语API:应用程序接口(ApplicationProgrammingInterface)CIM：公共信息模型(CommonInformalionModel)JSON：数据交换格式(JavaScriptObjectNotation)MQ：消息队列(MessageQueue)URL：统资源定位系统(UniformResourceLocator)XML：可扩展标记语言(ExtensibleMarkupLanguage)UTF-8：8位元可变长度统码(万国码)字符编码(UniCOdCTransformationFormat-8bit)5系统构成数字站公共组件由若干数据组件和业务组件组合而成，公共组件基于基础数据实现业务功能的处理和响应；作为服务端，公共组件对外提供一系列业务交互接II,支撑应用获取数据、告警、文件等信息。数字站业务交互框架如图1所示。业务交互支持本地及远方访问数才站公共组件等，业务交互应满足如下主要功能:提供请求订阅实时数据的能力：提供请求存储历史数据的能力：提供请求订阅告警数据的能力：提供清求发送文件数据的能力：提供请求获取视频数据的能力：提供请求获取二维模型的能力：提供请求数据模型的能力:星*白图1数字站业务交互框架示意图提供请求设备台账数据的能力.6总体原则业务交互应遵循以下基本技术原则:a) b)c) d)业务交互应通过微服务架构实现统的信息访问接口*交互接口参数应采用JSON格式定义：交互接口应具备权限校验机制J:安全防护应符合GB/T22239规定，。7技术要求7.1 接口交互7.1.1 总体要求公共组件与应用之间使用统一的数据交互接口，数据交互内容使用17F-8编码的JSON格式字符串，用于应用读取公共组件的实时数据、收发公共组件的告警消息、读写公共组件的历史数据、文件数据、视频数据以及三维数据等，交互数据分为请求接口输入参数和回调接口返回参数，交互时需要进行用户权限校验。7.12 交互内容公共组件与应用之间交互的数据内容如下：Hb Cd ef B实时数据：包括装置上送的模拟量、相量量测、状态量的实时变化数据；历史数据：包括公共组件存储的状态量、模拟量等历史数据：告警数据：包括实时告警数据和历史告警数据；文件数据：包括录波文件、图形文件等:日志数据：包括应用运行日志、操作日志等：视频数据：包括视频流、快照图片等；三维数据：包括三维信息、三维画面等。7.13 3交互方式公共组件与应用之间的数据交互方式包括数据查询、数据订阅（WebSockel方式）、数据订阅（消息队列）和数据存储四种方式，要求如Ma）数据查询：应用通过主动请求方式查询需要的数据，交互方式采用HTTP（HTTPS）协议，使用RESTful设计风格，查询的数据应支持查询条件过港，查询的数据类型包括实时数据.历史数据、告警数据和文件数据等，数据查询交互方式如图2所示：b）数据订阅（WebSoCkel方式）：应用主动向公共组件建立WebSoCkel连接，并向公共组件进行数据订阅，订阅后公共组件周期向应用推送订阅的数据，同时实时推送变化的数据，订阅的数据应支持查询条件过泄，数据订阅CebSoCket方式）如图3所示:c）数据订阅（消息队列方式）：应用通过消息中间件以订阅主题的方式请求数据，公共组件通过消息中间件周期向应用推送订阅的数据，同时实时推送变化的数据，数据订阅（消息队列方式）如图4所示:d）数据存储：应用调用公共组件提供的历史数据交互接口写入需要保存的历史数据，交互方式采用HTTP（HTTPS）协议，使用RESTfUl设计风格，数据存储交互方式如图5所示。图3数据订阅（WebSoCket方式）图4数据订阅(消息队列方式)图5数据存储7.2 接口定义7.2.1 2.1总体要求接口是由公共组件基于微服务框架提供的一组服务.用于读取和修改数据、收发消息、读写文件等口接口风格参照RESTfUIAPI规范.以HTTP(三)URL的形式体现资源和对应的接口方法。完整的接口方法由域名(IP地址)、版本、路径(端点)、HTTP动词(GET和POST)、过i信息(参数)、状态码、返回结果等组成。7.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)/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-Iffi-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权限认证管理7.3.1.1总体要求应符合OAUth2.0要求，应用前后端交互的权限认证宜采用客户端模式，对接口进行访问认证和安全管控。应用部署时，应在管理平台注册备案，获取两个身份识别码.客户端ID（clientid）和客户端密钥（clientsecret）.应用在调用公共组件接口时，权限认证服务通过验证令牌和白名单确保服务调用方的合法性。令牌默认有效期为24小时，超时后需要重新调用接口获取新的令牌。7.31.2权限获取权限获取接口定义如表7所示，客户端请求Content-Type为application/xnww-forrUrlencodecl,请求参数采用表单传值方式，加表8所示，返回成功时数据格式定义如表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类型StringToken烫型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权限校验请求体定义璃性名称类型是否必选描述token令牌String是特校验的令牌表12权限校验成功返回体定义属性名称类型是否必选描述clicnt_id客户端IDString是client的配置项即客户端IDscope授权爸围Strig是由请求时参数决定CXpacc