《數(shù)字換流站業(yè)務(wù)交互技術(shù)規(guī)范》

ICS29.240.01

F21

DL

中華人民共和國電力行業(yè)標(biāo)準(zhǔn)

數(shù)字換流站業(yè)務(wù)交互技術(shù)規(guī)范

Technicalspecificationforserviceinteractionofdigitalconverterstation

征求意見稿

XXXX-XX-XX發(fā)布XXXX-XX-XX實(shí)施

國家能源局發(fā)布

I

數(shù)字換流站業(yè)務(wù)交互技術(shù)規(guī)范

1范圍

本文件規(guī)定了數(shù)字換流站業(yè)務(wù)交互部分的系統(tǒng)構(gòu)成、總體原則和技術(shù)要求，包括數(shù)據(jù)、告警、文

件、日志、視頻、三維、控制、卡片等業(yè)務(wù)交互接口。

本文件適用于換流站的數(shù)字化建設(shè)，指導(dǎo)數(shù)字換流站的設(shè)計(jì)、研發(fā)、驗(yàn)收和應(yīng)用。

2規(guī)范性引用文件

下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文

件，僅該日期對應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適

用于本文件。

GB/T22239信息安全技術(shù)網(wǎng)絡(luò)安全等級保護(hù)基本要求

GB/T30149電網(wǎng)通用模型描述規(guī)范

3術(shù)語和定義

3.1

數(shù)字換流站digitalconverterstation

運(yùn)用先進(jìn)數(shù)字技術(shù)、信息技術(shù)發(fā)展創(chuàng)新成果，統(tǒng)籌布局?jǐn)?shù)字化基礎(chǔ)設(shè)施，具有強(qiáng)化設(shè)備廣泛互

聯(lián)、狀態(tài)深度感知、數(shù)據(jù)融合貫通、管理精益高效能力的換流站。

3.2

公共組件publiccomponent

具備數(shù)據(jù)接入、處理、存儲和分析能力，對外提供服務(wù)接口供應(yīng)用調(diào)用，支撐業(yè)務(wù)應(yīng)用功能實(shí)現(xiàn)

的軟件。

3.3

基礎(chǔ)應(yīng)用basicapplication

具備一定的生產(chǎn)業(yè)務(wù)處理能力，滿足運(yùn)行監(jiān)視、運(yùn)維分析、業(yè)務(wù)管控等共性數(shù)字化需求的應(yīng)用軟

件。

3.4

高級應(yīng)用advancedapplication

具有較強(qiáng)專業(yè)性或信息綜合處理能力的應(yīng)用軟件，是基礎(chǔ)應(yīng)用的增強(qiáng)和補(bǔ)充，滿足狀態(tài)預(yù)測、健

康評估、診斷分析等生產(chǎn)業(yè)務(wù)的差異化需求。

4縮略語

API：應(yīng)用程序接口（ApplicationProgrammingInterface）

CIM：公共信息模型（CommonInformationModel）

JSON：數(shù)據(jù)交換格式（JavaScriptObjectNotation）

MQ：消息隊(duì)列（MessageQueue）

URL：統(tǒng)一資源定位系統(tǒng)（UniformResourceLocator）

XML：可擴(kuò)展標(biāo)記語言（ExtensibleMarkupLanguage）

UTF-8：8位元可變長度統(tǒng)一碼（萬國碼）字符編碼（UnicodeTransformationFormat-8bit）

4

5系統(tǒng)構(gòu)成

數(shù)字站公共組件由若干數(shù)據(jù)組件和業(yè)務(wù)組件組合而成，公共組件基于基礎(chǔ)數(shù)據(jù)實(shí)現(xiàn)業(yè)務(wù)功能的處

理和響應(yīng)；作為服務(wù)端，公共組件對外提供一系列業(yè)務(wù)交互接口，支撐應(yīng)用獲取數(shù)據(jù)、告警、文件等

信息。數(shù)字站業(yè)務(wù)交互框架如圖1所示。

業(yè)務(wù)交互支持本地及遠(yuǎn)方訪問數(shù)字站公共組件等，業(yè)務(wù)交互應(yīng)滿足如下主要功能：

a)提供請求訂閱實(shí)時數(shù)據(jù)的能力；

b)提供請求存儲歷史數(shù)據(jù)的能力；

c)提供請求訂閱告警數(shù)據(jù)的能力；

d)提供請求發(fā)送文件數(shù)據(jù)的能力；

e)提供請求獲取視頻數(shù)據(jù)的能力；

f)提供請求獲取三維模型的能力；

g)提供請求數(shù)據(jù)模型的能力；

h)提供請求設(shè)備臺賬數(shù)據(jù)的能力。

圖1數(shù)字站業(yè)務(wù)交互框架示意圖

6總體原則

業(yè)務(wù)交互應(yīng)遵循以下基本技術(shù)原則：

a)業(yè)務(wù)交互應(yīng)通過微服務(wù)架構(gòu)實(shí)現(xiàn)統(tǒng)一的信息訪問接口；

b)交互接口參數(shù)應(yīng)采用JSON格式定義；

c)交互接口應(yīng)具備權(quán)限校驗(yàn)機(jī)制；

d)安全防護(hù)應(yīng)符合GB/T22239規(guī)定，。

7技術(shù)要求

7.1接口交互

7.1.1總體要求

公共組件與應(yīng)用之間使用統(tǒng)一的數(shù)據(jù)交互接口，數(shù)據(jù)交互內(nèi)容使用UTF-8編碼的JSON格式字符

串，用于應(yīng)用讀取公共組件的實(shí)時數(shù)據(jù)、收發(fā)公共組件的告警消息、讀寫公共組件的歷史數(shù)據(jù)、文件

數(shù)據(jù)、視頻數(shù)據(jù)以及三維數(shù)據(jù)等，交互數(shù)據(jù)分為請求接口輸入?yún)?shù)和回調(diào)接口返回參數(shù)，交互時需要

進(jìn)行用戶權(quán)限校驗(yàn)。

7.1.2交互內(nèi)容

公共組件與應(yīng)用之間交互的數(shù)據(jù)內(nèi)容如下：

a)實(shí)時數(shù)據(jù)：包括裝置上送的模擬量、相量量測、狀態(tài)量的實(shí)時變化數(shù)據(jù)；

5

b)歷史數(shù)據(jù)：包括公共組件存儲的狀態(tài)量、模擬量等歷史數(shù)據(jù)；

c)告警數(shù)據(jù)：包括實(shí)時告警數(shù)據(jù)和歷史告警數(shù)據(jù)；

d)文件數(shù)據(jù)：包括錄波文件、圖形文件等；

e)日志數(shù)據(jù)：包括應(yīng)用運(yùn)行日志、操作日志等；

f)視頻數(shù)據(jù)：包括視頻流、快照圖片等；

g)三維數(shù)據(jù)：包括三維信息、三維畫面等。

7.1.3交互方式

公共組件與應(yīng)用之間的數(shù)據(jù)交互方式包括數(shù)據(jù)查詢、數(shù)據(jù)訂閱（WebSocket方式）、數(shù)據(jù)訂閱（消

息隊(duì)列）和數(shù)據(jù)存儲四種方式，要求如下：

a)數(shù)據(jù)查詢：應(yīng)用通過主動請求方式查詢需要的數(shù)據(jù)，交互方式采用HTTP（HTTPS）協(xié)議，使

用RESTful設(shè)計(jì)風(fēng)格，查詢的數(shù)據(jù)應(yīng)支持查詢條件過濾，查詢的數(shù)據(jù)類型包括實(shí)時數(shù)據(jù)、歷

史數(shù)據(jù)、告警數(shù)據(jù)和文件數(shù)據(jù)等，數(shù)據(jù)查詢交互方式如圖2所示；

b)數(shù)據(jù)訂閱（WebSocket方式）：應(yīng)用主動向公共組件建立WebSocket連接，并向公共組件進(jìn)行

數(shù)據(jù)訂閱，訂閱后公共組件周期向應(yīng)用推送訂閱的數(shù)據(jù)，同時實(shí)時推送變化的數(shù)據(jù)，訂閱的

數(shù)據(jù)應(yīng)支持查詢條件過濾，數(shù)據(jù)訂閱（WebSocket方式）如圖3所示；

c)數(shù)據(jù)訂閱（消息隊(duì)列方式）：應(yīng)用通過消息中間件以訂閱主題的方式請求數(shù)據(jù)，公共組件通

過消息中間件周期向應(yīng)用推送訂閱的數(shù)據(jù)，同時實(shí)時推送變化的數(shù)據(jù)，數(shù)據(jù)訂閱（消息隊(duì)列

方式）如圖4所示；

d)數(shù)據(jù)存儲：應(yīng)用調(diào)用公共組件提供的歷史數(shù)據(jù)交互接口寫入需要保存的歷史數(shù)據(jù)，交互方式

采用HTTP（HTTPS）協(xié)議，使用RESTful設(shè)計(jì)風(fēng)格，數(shù)據(jù)存儲交互方式如圖5所示。

圖2數(shù)據(jù)查詢

圖3數(shù)據(jù)訂閱（WebSocket方式）

圖4數(shù)據(jù)訂閱（消息隊(duì)列方式）

6

圖5數(shù)據(jù)存儲

7.2接口定義

7.2.1總體要求

接口是由公共組件基于微服務(wù)框架提供的一組服務(wù)，用于讀取和修改數(shù)據(jù)、收發(fā)消息、讀寫文件

等。

接口風(fēng)格參照RESTfulAPI規(guī)范，以HTTP(s)URL的形式體現(xiàn)資源和對應(yīng)的接口方法。完整的接

口方法由域名（IP地址）、版本、路徑（端點(diǎn)）、HTTP動詞（GET和POST）、過濾信息（參數(shù)）、狀態(tài)

碼、返回結(jié)果等組成。

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協(xié)議訪問接口所需的主機(jī)地址和端口

2cs固定詞，表示數(shù)字站

3v{n}表示版本號，如當(dāng)前版本號為v1

4{endpoint}表示路徑（端點(diǎn)），用于標(biāo)識具體的接口

采用本文件的接口URL中，{endpoint}之前的部分（即“http(s)://{host}:{port}/v{n}/cs/”

或者“http(s)://{}/v{n}/cs/”）需根據(jù)數(shù)字站的情況進(jìn)行組裝。具體的接口內(nèi)容在

{endpoint}部分定義。

7.2.3請求方法

查詢和數(shù)據(jù)獲取類型的接口，采用HTTPGET方法。其他類型的接口采用HTTPPOST方法。如表3

所示。

表3請求方法

方法描述

GET讀取動作

POST請求動作

7

7.2.4消息頭部

消息頭部如表4所示。

表4消息頭部

屬性名稱類型是否必選

交互類型：權(quán)限認(rèn)證交互（application/x-www-form-

Content-TypeString是

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

Authorizationtoken令牌String是

X-HW-IDAPI網(wǎng)關(guān)身份認(rèn)證IDString否

X-HW-APPKEYAPI網(wǎng)關(guān)身份認(rèn)證KEYString否

7.2.5請求體

請求體為JSON格式的對象，應(yīng)具有以下字段，如表5所示。

表5請求體

屬性名稱類型是否必選

id請求IDInt是

clientId客戶端Id（應(yīng)用注冊時由權(quán)限認(rèn)證服務(wù)提供）String是

body請求內(nèi)容（具體內(nèi)容見各接口詳細(xì)說明）Object是

7.2.6返回體

返回體為JSON格式的對象，應(yīng)有以下字段，如表6所示。

表6返回體

屬性名稱類型是否必選

id請求IDInt是

code返回碼（應(yīng)符合表A.1）String是

message返回碼描述String是

body返回內(nèi)容（具體內(nèi)容見各接口詳細(xì)說明）Object是

7.3接口功能

7.3.1權(quán)限認(rèn)證管理

總體要求

應(yīng)符合OAuth2.0要求，應(yīng)用前后端交互的權(quán)限認(rèn)證宜采用客戶端模式，對接口進(jìn)行訪問認(rèn)證和安

全管控。應(yīng)用部署時，應(yīng)在管理平臺注冊備案，獲取兩個身份識別碼，客戶端ID（clientid）和客

戶端密鑰（clientsecret）。應(yīng)用在調(diào)用公共組件接口時，權(quán)限認(rèn)證服務(wù)通過驗(yàn)證令牌和白名單確保

服務(wù)調(diào)用方的合法性。令牌默認(rèn)有效期為24小時，超時后需要重新調(diào)用接口獲取新的令牌。

權(quán)限獲取

權(quán)限獲取接口定義如表7所示，客戶端請求Content-Type為application/x-www-form-

urlencoded，請求參數(shù)采用表單傳值方式，如表8所示，返回成功時數(shù)據(jù)格式定義如表9所示。

8

表7權(quán)限獲取接口定義

請求方法POST

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

協(xié)議應(yīng)用http(s)

表8權(quán)限獲取請求體定義

屬性名稱類型是否必選描述

grant_typeToken類型String是固定填寫client_credentials

scope信號索引鍵String是固定填寫all

client_id客戶端賬號String是客戶端賬號，由平臺分配

client_secret客戶端密碼String是客戶端密碼，由平臺分配

表9權(quán)限獲取返回體定義

屬性名稱類型描述

access_token認(rèn)證TokenString獲取到的令牌

token_typeToken類型StringToken類型

expires_in過期時間Long過期時間

scope權(quán)限范圍String表示申請的權(quán)限范圍，默認(rèn)為all

code返回碼String應(yīng)符合表A.1

message返回碼描述String返回碼對應(yīng)的描述信息

jti聲明String唯一標(biāo)識符

權(quán)限校驗(yàn)

權(quán)限校驗(yàn)接口定義如表10所示，請求參數(shù)采用表單傳值方式，其定義如表11所示，校驗(yàn)成功時

返回?cái)?shù)據(jù)格式定義如表12所示，校驗(yàn)失敗時返回?cái)?shù)據(jù)格式定義如表13所示。

表10權(quán)限校驗(yàn)接口定義

請求方法POST

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

協(xié)議應(yīng)用http(s)

表11權(quán)限校驗(yàn)請求體定義

屬性名稱類型是否必選描述

token令牌String是待校驗(yàn)的令牌

表12權(quán)限校驗(yàn)成功返回體定義

9

屬性名稱類型是否必選描述

client_id客戶端IDString是client的配置項(xiàng)即客戶端ID

scope授權(quán)范圍String[]是由請求時參數(shù)決定

expaccess_token有效期Long是默認(rèn)有效期為86400秒

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

sub被授權(quán)方String是一般就是當(dāng)前用戶ID

iss授權(quán)方String是站名@授權(quán)方，示例如poyanghu@nrec

user_name當(dāng)前用戶名String否當(dāng)前用戶名（僅針對web用戶）

last_login上次登陸時間戳Long是如果未登陸過，則為0

pri用戶角色String[]是用戶具備的角色集合

account統(tǒng)一賬戶名String否ISC的唯一賬戶名（僅針對web用戶）

obj_id統(tǒng)一賬戶用戶IDString否ISC的唯一賬戶用戶ID（僅針對web用戶）

表13權(quán)限校驗(yàn)失敗返回?cái)?shù)據(jù)

屬性名稱類型描述

succ是否成功Boolean是否校驗(yàn)成功

code錯誤碼String校驗(yàn)錯誤碼

message錯誤信息String校驗(yàn)錯誤信息

path請求路徑String請求路徑

timestamp校驗(yàn)時間Long校驗(yàn)時間

用戶同步

用戶同步接口定義如表14所示，應(yīng)遵循7.2中消息頭部、請求體、返回體的相關(guān)定義。請求體中

body數(shù)據(jù)的定義如表15所示，Condition的定義如表16所示。請求成功時，返回體中body定義如表

17所示，其中SysUser的結(jié)構(gòu)如表18所示。請求失敗時，返回體中body定義為空。

表14用戶同步接口定義

請求方法POST

請求地址sys-service/sys/user

協(xié)議應(yīng)用http(s)

表15用戶同步請求體body定義

屬性名稱類型是否必選描述

需查詢的人員列表,

id人員主鍵ID列表List<String>否

為空時查所有人員信息

attributes屬性列表List<String>否需返回的屬性列表，不填返回所有

conditions檢索條件List<Condition>否檢索條件列表，不填無條件

10

表16用戶同步請求參數(shù)Condition定義

屬性名稱類型是否必選描述

dept_id部門IdString否所屬部門Id

org_id單位IdString否所屬單位Id

if_effective檢索值Boolean否人員是否有效，默認(rèn)所有

表17用戶同步成功時返回體body定義

屬性名稱類型描述

values人員列表List<SysUser>查詢到的人員列表

表18用戶同步返回參數(shù)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創(chuàng)建時間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人員專業(yè)String最大長度50

staff_sex人員性別String人員性別(0:女,1:男)

telphone內(nèi)線電話String最大長度50

cardid身份證String最大長度52

source數(shù)據(jù)來源Stringisc:數(shù)據(jù)同步,owner:自身新增

組織同步

組織同步接口定義如表19所示，應(yīng)遵循7.2中消息頭部、請求體、返回體的相關(guān)定義。請求體中

body數(shù)據(jù)的定義如表20所示，Condition的定義如表21所示。請求成功時，返回體中body定義如表

22所示，其中SysOrg的結(jié)構(gòu)如表23所示。請求失敗時，返回體中body定義為空。

表19組織同步接口定義

請求方法POST

11

請求地址sys-service/sys/org

協(xié)議應(yīng)用http(s)

表20組織同步請求體body定義

屬性名稱類型是否必選描述

需查詢的部門根節(jié)點(diǎn)及其子節(jié)點(diǎn),

id部門主鍵IDString否

為空時查所有部門組織信息

attributes屬性列表List<String>否需返回的屬性列表，不填返回所有

conditions檢索條件List<Condition>否檢索條件列表，不填無條件

表21組織同步請求參數(shù)Condition定義

屬性名稱類型是否必選描述

manage_level管理級別String否管理級別

表22組織同步成功時返回體body定義

屬性名稱類型描述

values部門列表List<SysOrg>查詢到的部門列表

表23組織同步返回?cái)?shù)據(jù)SysOrg定義

屬性名稱類型描述

obj_id部門主鍵String最大長度42

dept_name部門名稱String最大長度200

dept_style部門性質(zhì)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創(chuàng)建時間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數(shù)據(jù)有效性Int

province_id所屬網(wǎng)省String最大長度42

province_name所屬網(wǎng)省名稱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數(shù)據(jù)來源Stringisc:數(shù)據(jù)同步,owner:自身新增

unicode統(tǒng)一編碼String最大長度50

pms_idPMS映射主鍵String最大長度50

station_type站的類別String最大長度1

7.3.2查詢模型數(shù)據(jù)管理

通用模型查詢接口

公共組件支持應(yīng)用獲取指定設(shè)備模型相關(guān)數(shù)據(jù)信息，設(shè)備模型應(yīng)符合GB/T30149和Q/GDW

10703。接口定義如表24所示，應(yīng)遵循7.2中消息頭部、請求體、返回體的相關(guān)定義。請求體中body

數(shù)據(jù)的定義如表25所示。請求成功時，返回體中body定義如表26所示，其中Data結(jié)構(gòu)字段以請求

參數(shù)中field字段查詢的數(shù)據(jù)結(jié)構(gòu)為準(zhǔn)，如表27所示。請求失敗時，返回體中body定義為空。

表24通用模型查詢接口定義

請求方法POST

請求地址mdldata-service/model

協(xié)議應(yīng)用http(s)

表25通用模型查詢請求體body定義

屬性名稱類型是否必選描述

field查詢的數(shù)據(jù)結(jié)構(gòu)String是mrid,name,description,…。

特定選擇字段，多個字段時用英文逗號分

隔，不允許使用*,每個datetype類型支

持的field列表見模型文檔。

13

datatype數(shù)據(jù)類型String是1.Station，廠站

2.Area，區(qū)域

3.Voltagelevel，電壓等級

4.Bay，間隔

5.Equipment，一次設(shè)備

6.Analog，模擬量

7.State，狀態(tài)量

8.Accumulator，遙脈量

9.Assettype，設(shè)備類型

10.Component，設(shè)備部件

11.可根據(jù)具體場景約定擴(kuò)展

condition查詢條件String是SQL語句的where條件，查詢條件應(yīng)防止

SQL注入。

必須指定查詢條件，如不指定，則公共組件

直接返回查詢失敗，其中

analog/state/accumulator需支持按mrid

（模擬量/離散量/累加量標(biāo)識）、astid（所

屬設(shè)備資產(chǎn)ID）、psrid（所屬設(shè)備資源

ID）、astuid（所屬設(shè)備通用識別碼ID）、

flagcode(應(yīng)用標(biāo)記碼)進(jìn)行過濾查詢。

表26通用模型查詢成功時返回體body定義

屬性名稱類型描述

data返回?cái)?shù)據(jù)信息Data數(shù)據(jù)

表27通用模型查詢返回?cái)?shù)據(jù)Data定義

屬性名稱類型描述

mridId值Long例“4222124802768902”

name名稱String例“A相電壓”

desc描述String例“A相電壓”

parentid父節(jié)點(diǎn)String例“029020000000000002092756”

dimension單位String例“kV”

type類型Int例“6”

calvalue值Long例“220.156”

根據(jù)mrid查詢數(shù)據(jù)

公共組件支持應(yīng)用按需根據(jù)mrid查詢當(dāng)前數(shù)據(jù)。接口定義如表28所示，應(yīng)遵循7.2中消息頭

部、請求體、返回體的相關(guān)定義。請求體中body數(shù)據(jù)的定義如表29所示。請求成功時，返回體中

body