《電供暖系統(tǒng)技術(shù)規(guī)范 第10部分：接口》

ICSXX.XXX

CCSXX

中國電力企業(yè)聯(lián)合會標(biāo)準(zhǔn)

T/CECXXXX-2018

電供暖系統(tǒng)技術(shù)規(guī)范

第10部分：接口

Electricalheatingsystemtechnicalspecification

Part10:Interface

(征求意見稿)

201X-XX-XX發(fā)布201X-XX-XX實施

中國電力企業(yè)聯(lián)合會發(fā)布1

I

電供暖系統(tǒng)技術(shù)規(guī)范第10部分：接口

1范圍

本部分規(guī)定了運營服務(wù)平臺與監(jiān)控系統(tǒng)、運營服務(wù)平臺與第三方平臺、監(jiān)控系統(tǒng)與第三

方平臺交互接口的要求、方式、描述、內(nèi)容與安全等。

本部分適用于電供暖系統(tǒng)接口的設(shè)計、開發(fā)、實現(xiàn)、驗收、運行和維護(hù)等。

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

下列文件對于本文件的應(yīng)用是必不可少的。凡是注日期的引用文件，僅注日期的版本適

用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。

GB/T22239—2008信息安全技術(shù)信息系統(tǒng)安全等級保護(hù)基本要求

3術(shù)語和定義

下列術(shù)語和定義適用于本文件。

3.1

WebAPI

WebAPI是網(wǎng)絡(luò)應(yīng)用程序接口。包含了廣泛的功能，網(wǎng)絡(luò)應(yīng)用通過API接口，可以實現(xiàn)

存儲服務(wù)、消息服務(wù)、計算服務(wù)等能力，利用這些能力可以進(jìn)行開發(fā)出強(qiáng)大功能的web應(yīng)

用。

3.2

WebService

是一個應(yīng)用組件，它邏輯性的為其他應(yīng)用程序提供數(shù)據(jù)與服務(wù)。各應(yīng)用程序通過網(wǎng)絡(luò)協(xié)

議和規(guī)定的一些標(biāo)準(zhǔn)數(shù)據(jù)格式來訪問WebService，通過WebService內(nèi)部執(zhí)行得到所需結(jié)

果。WebService可以執(zhí)行從簡單的請求到復(fù)雜商務(wù)處理的任何功能。

4接口概述

接口是運營平臺或監(jiān)控系統(tǒng)與第三方平臺進(jìn)行數(shù)據(jù)交互功能，相關(guān)接口關(guān)系見圖1。接

口包括下列三類：

a)運營服務(wù)平臺進(jìn)行數(shù)據(jù)處理和分析，可以通過接口為第三平臺提供數(shù)據(jù)支撐，完成

不同的業(yè)務(wù)功能；

b)監(jiān)控系統(tǒng)也可以直接為第三方平臺提供接口進(jìn)行交互，三方平臺通過接口獲取電供

暖系統(tǒng)數(shù)據(jù)，可下發(fā)指令至監(jiān)控系統(tǒng)遠(yuǎn)程操控設(shè)備；

c)運營服務(wù)平臺不僅可以通過協(xié)議從監(jiān)控系統(tǒng)采集數(shù)據(jù)，還可以通過接口獲取數(shù)據(jù)及

發(fā)送指令給監(jiān)控系統(tǒng)。

2

圖1接口關(guān)系

5接口要求

一般要求

5.1對于本部分三類接口的設(shè)計和開發(fā)，應(yīng)滿足下列要求：

a)數(shù)據(jù)完整性。發(fā)送數(shù)據(jù)時，收發(fā)雙方必須確保通信數(shù)據(jù)的完整性，傳輸失敗時能夠

進(jìn)行回滾處理，并記錄回滾操作的日志；

b)數(shù)據(jù)正確性。收發(fā)雙方要保證所使用的接口協(xié)議的一致性，確保使用的是同一接口

協(xié)議的相同版本、收發(fā)雙方具備數(shù)據(jù)校驗碼，只有在數(shù)據(jù)校驗碼完全正確下，收方

認(rèn)同數(shù)據(jù)正確；

c)數(shù)據(jù)安全性。接口安全應(yīng)滿足GB/T22239—2008規(guī)定的要求；

d)接口擴(kuò)展性。接口宜隨著平臺業(yè)務(wù)的調(diào)整而增加或改變傳送內(nèi)容，同時應(yīng)對修改的

接口協(xié)議進(jìn)行版本管理，且協(xié)議雙方可以互查對方授權(quán)的接口協(xié)議內(nèi)容；

e)通信實時性。對時間有要求的業(yè)務(wù)，在傳輸數(shù)據(jù)時候，應(yīng)保證傳輸數(shù)據(jù)實時性要求，

確保業(yè)務(wù)的正確開展。

接口方式

5.22.1WebAPI

平臺宜提供WebAPI接口方式，使用JSON格式進(jìn)行數(shù)據(jù)傳遞。基本設(shè)計原則是對

CRUD操作使用HTTP協(xié)議對應(yīng)的方法：

POST-創(chuàng)建資源

GET-檢索資源

PUT–更新資源-

DELETE-刪除資源

返回值JSON格式：

{

"message":"OK",

"state":1,

"code":"",

"data":""

}

其中，

message為消息提示；state為狀態(tài)，1-成功，0-失?。籧ode為響應(yīng)代碼，詳見附錄A；

data為結(jié)果。

3

在本部分后面的描述中，都以此方式進(jìn)行闡述。

5.2.2WebService

平臺可提供WebService接口方式，請求參數(shù)與返回值使用XML的方式進(jìn)行數(shù)據(jù)傳遞。

6接口描述

監(jiān)控系統(tǒng)與運營服務(wù)平臺

6.1運營服務(wù)平臺除通過規(guī)約與監(jiān)控系統(tǒng)進(jìn)行交互外，運營服務(wù)平臺也可以通過接口獲取數(shù)

據(jù)、發(fā)送指令，分為登陸、獲取設(shè)備數(shù)據(jù)列表、獲取設(shè)備實時數(shù)據(jù)、獲取設(shè)備歷史數(shù)據(jù)、遠(yuǎn)

程控制這五大類接口，如圖2。

圖2監(jiān)控系統(tǒng)與運營服務(wù)平臺接口圖

a)登陸。為防止惡意調(diào)用，在運營服務(wù)平臺進(jìn)行交互時，首先應(yīng)進(jìn)行登陸認(rèn)證，只有

認(rèn)證通過的平臺才能調(diào)用接口，詳見第7節(jié)接口安全；

b)獲取設(shè)備數(shù)據(jù)列表。不同類型的設(shè)備能采集的數(shù)據(jù)有所不同，通過此接口，獲取指

定設(shè)備的數(shù)據(jù)列表，返回值列舉了所有能采集的數(shù)據(jù)項的唯一名稱及含義，詳見附

錄B表B.2；

c)獲取設(shè)備實時數(shù)據(jù)。通過調(diào)用此接口，可獲取設(shè)備所有數(shù)據(jù)項的實時狀態(tài)或值，也

可根據(jù)數(shù)據(jù)項名稱獲取某一數(shù)據(jù)的實時狀態(tài)或值，詳見附錄B表B.3；

d)獲取設(shè)備歷史數(shù)據(jù)。根據(jù)數(shù)據(jù)項名稱、時間段，獲取設(shè)備某一數(shù)據(jù)在指定時間段的

數(shù)據(jù)列表，詳見附錄B表B.4；

e)遠(yuǎn)程控制設(shè)備。監(jiān)控系統(tǒng)根據(jù)需求可提供遠(yuǎn)程控制設(shè)備接口，用于運營服務(wù)平臺遠(yuǎn)

程調(diào)控設(shè)備，操作指令應(yīng)能夠進(jìn)行擴(kuò)展，詳見附錄B表B.5。

監(jiān)控系統(tǒng)與第三方平臺

6.2由于監(jiān)控系統(tǒng)為第三方平臺提供的接口功能與為運營服務(wù)平臺提供類似，此部分接口內(nèi)

容參照6.1節(jié)內(nèi)容。

運營服務(wù)平臺與第三方平臺

6.3第三方平臺獲取設(shè)備的數(shù)據(jù)可以通過監(jiān)控系統(tǒng)提供的接口，運營服務(wù)平臺為第三方平臺

提供的接口主要為統(tǒng)計相關(guān)的接口，分為登陸、運行時間統(tǒng)計、報警時間統(tǒng)計、耗能量統(tǒng)計

這四大類接口，如圖3。

4

圖3運營服務(wù)平臺與第三方平臺接口圖

a)登陸。為防止惡意調(diào)用，同樣首先要進(jìn)行登陸認(rèn)證；

b)運行時間統(tǒng)計。通過此接口，獲取設(shè)備指定時間段的運行時間統(tǒng)計結(jié)果，可按日、

月、年進(jìn)行查詢，詳見附錄B表B.6；

c)報警時間統(tǒng)計。通過此接口，獲取設(shè)備指定時間段的報警時間統(tǒng)計結(jié)果，可按日、

月、年進(jìn)行查詢，詳見附錄B表B.7；

d)耗能量統(tǒng)計。通過此接口，獲取設(shè)備指定時間段的耗能量統(tǒng)計結(jié)果，可按日、月、

年進(jìn)行查詢，詳見附錄B表B.8。

7接口安全

密鑰機(jī)制

7.1動態(tài)獲取密鑰，有一個接口需要首先調(diào)用，讓接口提供方返回密鑰，于是就有了登錄的

概念，過程如圖4。

圖4密鑰機(jī)制過程圖

這樣只有接口調(diào)用方和提供方才知道動態(tài)生成的密鑰，而且密鑰具有時效性，規(guī)定為1h，

當(dāng)密鑰超時，會判定無效，應(yīng)重新進(jìn)行登陸認(rèn)證。

登陸機(jī)制

7.2進(jìn)行調(diào)用接口前，調(diào)用方都需要調(diào)用登陸接口進(jìn)行安全認(rèn)證。登陸時傳入?yún)?shù)：用戶名、

密碼。用戶信息應(yīng)向提供方申請獲得。登陸接口詳見附錄B表B.1。

5

附錄A

（資料性附錄）

code含義表

code含義見表A.1。

表A.1code含義表

序號code值含義

10000無異常

20001密鑰超時

30002參數(shù)缺失

40003參數(shù)值格式有誤

58008未知異常

6

附錄B

（資料性附錄）

接口詳解

登陸接口解析見表B.1。

表B.1登陸接口解析表

請求方式POST

服務(wù)路徑/login

Body參數(shù)deviceId:監(jiān)控系統(tǒng)ID

userName:用戶名

password:密碼

返回值類型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data":"KEY值"http://密鑰值

}

獲取設(shè)備數(shù)據(jù)列表接口解析見表B.2。

表B.2獲取設(shè)備數(shù)據(jù)列表接口解析表

請求方式GET

服務(wù)路徑/data/list

Body參數(shù)key:密鑰

deviceId:監(jiān)控系統(tǒng)ID

equipmentAdd:設(shè)備地址

返回值類型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data"://數(shù)據(jù)列表

{

"voltage":"電壓",

"current":"電流",

"power":"功率",

"indoorTemp":"室內(nèi)溫度",

"outsideTemp":"室外溫度",

…

}

}

7

獲取設(shè)備實時數(shù)據(jù)接口解析見表B.3。

表B.3獲取設(shè)備實時數(shù)據(jù)接口解析表

請求方式GET

服務(wù)路徑/data：獲取所有數(shù)據(jù)實時值，/data/name:根據(jù)數(shù)據(jù)項名稱獲取

Body參數(shù)key:密鑰

deviceId:監(jiān)控系統(tǒng)ID

equipmentAdd:設(shè)備地址

dataName:數(shù)據(jù)項名稱，根據(jù)數(shù)據(jù)項名稱獲取時需要

返回值類型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data"://數(shù)據(jù)值

{

"voltage":"220",

"current":"2",

"power":"440",

…

}

}

獲取設(shè)備歷史數(shù)據(jù)接口解析見表B.4。

表B.4獲取設(shè)備歷史數(shù)據(jù)接口解析表

請求方式GET

服務(wù)路徑/data/record/name

Body參數(shù)key:密鑰

deviceId:監(jiān)控系統(tǒng)ID

equipmentAdd:設(shè)備地址

dataName:數(shù)據(jù)項名稱

beginTime:開始時間

endTime:結(jié)束時間

返回值類型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data"://數(shù)據(jù)值

[

{

"id":1,

"value":"220",//值

"time":"1502089272000",//時間戳

8

},

{

"id":2,

"value":"222",//值

"time":"1502089272000",//時間戳

}

...

]

}

遠(yuǎn)程控制接口解析見表B.5。

表B.5遠(yuǎn)程控制接口解析表

請求方式POST

服務(wù)路徑/control

Body參數(shù)key:密鑰

deviceId:監(jiān)控系統(tǒng)ID

equipmentAdd:設(shè)備地址

code:操作代碼，0010-開關(guān)機(jī)，可擴(kuò)展

value:1-開機(jī)，0-關(guān)機(jī)

返回值類型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data":""

}

運行時間統(tǒng)計接口解析見表B.6。

表B.6運行時間統(tǒng)計接口解析表

請求方式GET

服務(wù)路徑/runtime

Body參數(shù)key:密鑰

deviceId:監(jiān)控系統(tǒng)ID

equipmentAdd:設(shè)備地址,可選，不選時統(tǒng)計監(jiān)控系統(tǒng)下所有設(shè)備

beginTime:開始時間

endTime:結(jié)束時間

period:統(tǒng)計周期,0-日，1-月，2-年

返回值類型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

9

"data":

[

{

"id":1,

"value":22000,//運行時間

"unit":"s",//單位

"date":"2017-10",//日期

},

{

"id":2,

"value":22000,//運行時間

"unit":"s",//單位

"date":"2017-11",//日期

}

...

]

}

報警時間統(tǒng)計接口解析見表B.7。

表B.7報警時間統(tǒng)計接口解析表

請求方式GET

服務(wù)路徑/alarmtime

Body參數(shù)key:密鑰

deviceId:監(jiān)控系統(tǒng)ID

equipmentAdd:設(shè)備地址,可選，不選時統(tǒng)計監(jiān)控系統(tǒng)下所有設(shè)備

beginTime:開始時間

endTime:結(jié)束時間

period:統(tǒng)計周期,0-日，1-月，2-年

返回值類型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data":

[

{

"id":1,

"value":22000,//報警時間

"unit":"s",//單位

"date":"2017-10",//日期

},

{

"id":2,

"value":22000,//報警時間

10

"unit":"s",//單位

"date":"2017-11",//日期

}

...

]

}

耗能