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

ICS29.240.01

F21

DL

中华人民共和国电力行业标准

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

Technicalspecificationforserviceinteractionofdigitalconverterstation

征求意见稿

XXXX-XX-XX发布XXXX-XX-XX实施

国家能源局发布

I

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

1范围

本文件规定了数字换流站业务交互部分的系统构成、总体原则和技术要求，包括数据、告警、文

件、日志、视频、三维、控制、卡片等业务交互接口。

本文件适用于换流站的数字化建设，指导数字换流站的设计、研发、验收和应用。

2规范性引用文件

下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文

件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适

用于本文件。

GB/T22239信息安全技术网络安全等级保护基本要求

GB/T30149电网通用模型描述规范

3术语和定义

3.1

数字换流站digitalconverterstation

运用先进数字技术、信息技术发展创新成果，统筹布局数字化基础设施，具有强化设备广泛互

联、状态深度感知、数据融合贯通、管理精益高效能力的换流站。

3.2

公共组件publiccomponent

具备数据接入、处理、存储和分析能力，对外提供服务接口供应用调用，支撑业务应用功能实现

的软件。

3.3

基础应用basicapplication

具备一定的生产业务处理能力，满足运行监视、运维分析、业务管控等共性数字化需求的应用软

件。

3.4

高级应用advancedapplication

具有较强专业性或信息综合处理能力的应用软件，是基础应用的增强和补充，满足状态预测、健

康评估、诊断分析等生产业务的差异化需求。

4缩略语

API：应用程序接口（ApplicationProgrammingInterface）

CIM：公共信息模型（CommonInformationModel）

JSON：数据交换格式（JavaScriptObjectNotation）

MQ：消息队列（MessageQueue）

URL：统一资源定位系统（UniformResourceLocator）

XML：可扩展标记语言（ExtensibleMarkupLanguage）

UTF-8：8位元可变长度统一码（万国码）字符编码（UnicodeTransformationFormat-8bit）

4

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)实时数据：包括装置上送的模拟量、相量量测、状态量的实时变化数据；

5

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数据订阅（消息队列方式）

6

图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}表示版本号，如当前版本号为v1

4{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

7.2.4消息头部

消息头部如表4所示。

表4消息头部

属性名称类型是否必选

交互类型：权限认证交互（application/x-www-form-

Content-TypeString是

urlencoded）、其它交互（application/json）

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所示。

8

表7权限获取接口定义

请求方法POST

请求地址/auth-service/oauth/token

协议应用http(s)

表8权限获取请求体定义

属性名称类型是否必选描述

grant_typeToken类型String是固定填写client_credentials

scope信号索引键String是固定填写all

client_id客户端账号String是客户端账号，由平台分配

client_secret客户端密码String是客户端密码，由平台分配

表9权限获取返回体定义

属性名称类型描述

access_token认证TokenString获取到的令牌

token_typeToken类型StringToken类型

expires_in过期时间Long过期时间

scope权限范围String表示申请的权限范围，默认为all

code返回码String应符合表A.1

message返回码描述String返回码对应的描述信息

jti声明String唯一标识符

权限校验

权限校验接口定义如表10所示，请求参数采用表单传值方式，其定义如表11所示，校验成功时

返回数据格式定义如表12所示，校验失败时返回数据格式定义如表13所示。

表10权限校验接口定义

请求方法POST

请求地址/auth-service/oauth/check_token

协议应用http(s)

表11权限校验请求体定义

属性名称类型是否必选描述

token令牌String是待校验的令牌

表12权限校验成功返回体定义

9

属性名称类型是否必选描述

client_id客户端IDString是client的配置项即客户端ID

scope授权范围String[]是由请求时参数决定

expaccess_token有效期Long是默认有效期为86400秒

active是否有效Boolean是token是否有效

sub被授权方String是一般就是当前用户ID

iss授权方String是站名@授权方，示例如poyanghu@nrec

user_name当前用户名String否当前用户名（仅针对web用户）

last_login上次登陆时间戳Long是如果未登陆过，则为0

pri用户角色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>否检索条件列表，不填无条件

10

表16用户同步请求参数Condition定义

属性名称类型是否必选描述

dept_id部门IdString否所属部门Id

org_id单位IdString否所属单位Id

if_effective检索值Boolean否人员是否有效，默认所有

表17用户同步成功时返回体body定义

属性名称类型描述

values人员列表List<SysUser>查询到的人员列表

表18用户同步返回参数SysUser定义

属性名称类型描述

obj_id人员主键String最大长度42

staff_name人员姓名String最大长度60

order_no显示顺序Int

dept_id所属部门IdString最大长度42

org_id所属单位IdString最大长度42

account登录账户String最大长度50

create_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最大长度50

staff_subject人员专业String最大长度50

staff_sex人员性别String人员性别(0:女,1:男)

telphone内线电话String最大长度50

cardid身份证String最大长度52

source数据来源Stringisc:数据同步,owner:自身新增

组织同步

组织同步接口定义如表19所示，应遵循7.2中消息头部、请求体、返回体的相关定义。请求体中

body数据的定义如表20所示，Condition的定义如表21所示。请求成功时，返回体中body定义如表

22所示，其中SysOrg的结构如表23所示。请求失败时，返回体中body定义为空。

表19组织同步接口定义

请求方法POST

11

请求地址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最大长度42

dept_name部门名称String最大长度200

dept_style部门性质String最大长度50

dept_code部门编码String最大长度50

p_id上级IdString最大长度42

p_name上级部门名称String最大长度200

order_no显示顺序Int

manage_level管理级别String最大长度20

dept_simp部门简称String最大长度100

create_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数据有效性Int

province_id所属网省String最大长度42

province_name所属网省名称String最大长度200

12

属性名称类型描述

municipa_id所属地市String最大长度42

municipa_name所属地市名称String最大长度200

county_id所属供电公司（县局）String最大长度42

county_name所属供电公司名称String最大长度200

dept_level单位级别String最大长度30，判断省市公司

path_name组织全路径String最大长度500

path_id组织全路径IdString最大长度500

if_cancel是否撤销String最大长度5

source数据来源Stringisc:数据同步,owner:自身新增

unicode统一编码String最大长度50

pms_idPMS映射主键String最大长度50

station_type站的类别String最大长度1

7.3.2查询模型数据管理

通用模型查询接口

公共组件支持应用获取指定设备模型相关数据信息，设备模型应符合GB/T30149和Q/GDW

10703。接口定义如表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列表见模型文档。

13

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