《电供暖系统技术规范 第10部分：接口》

ICSXX.XXX

CCSXX

中国电力企业联合会标准

T/CECXXXX-2018

电供暖系统技术规范

第10部分：接口

Electricalheatingsystemtechnicalspecification

Part10:Interface

(征求意见稿)

201X-XX-XX发布201X-XX-XX实施

中国电力企业联合会发布1

I

电供暖系统技术规范第10部分：接口

1范围

本部分规定了运营服务平台与监控系统、运营服务平台与第三方平台、监控系统与第三

方平台交互接口的要求、方式、描述、内容与安全等。

本部分适用于电供暖系统接口的设计、开发、实现、验收、运行和维护等。

2规范性引用文件

下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适

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

GB/T22239—2008信息安全技术信息系统安全等级保护基本要求

3术语和定义

下列术语和定义适用于本文件。

3.1

WebAPI

WebAPI是网络应用程序接口。包含了广泛的功能，网络应用通过API接口，可以实现

存储服务、消息服务、计算服务等能力，利用这些能力可以进行开发出强大功能的web应

用。

3.2

WebService

是一个应用组件，它逻辑性的为其他应用程序提供数据与服务。各应用程序通过网络协

议和规定的一些标准数据格式来访问WebService，通过WebService内部执行得到所需结

果。WebService可以执行从简单的请求到复杂商务处理的任何功能。

4接口概述

接口是运营平台或监控系统与第三方平台进行数据交互功能，相关接口关系见图1。接

口包括下列三类：

a)运营服务平台进行数据处理和分析，可以通过接口为第三平台提供数据支撑，完成

不同的业务功能；

b)监控系统也可以直接为第三方平台提供接口进行交互，三方平台通过接口获取电供

暖系统数据，可下发指令至监控系统远程操控设备；

c)运营服务平台不仅可以通过协议从监控系统采集数据，还可以通过接口获取数据及

发送指令给监控系统。

2

图1接口关系

5接口要求

一般要求

5.1对于本部分三类接口的设计和开发，应满足下列要求：

a)数据完整性。发送数据时，收发双方必须确保通信数据的完整性，传输失败时能够

进行回滚处理，并记录回滚操作的日志；

b)数据正确性。收发双方要保证所使用的接口协议的一致性，确保使用的是同一接口

协议的相同版本、收发双方具备数据校验码，只有在数据校验码完全正确下，收方

认同数据正确；

c)数据安全性。接口安全应满足GB/T22239—2008规定的要求；

d)接口扩展性。接口宜随着平台业务的调整而增加或改变传送内容，同时应对修改的

接口协议进行版本管理，且协议双方可以互查对方授权的接口协议内容；

e)通信实时性。对时间有要求的业务，在传输数据时候，应保证传输数据实时性要求，

确保业务的正确开展。

接口方式

5.22.1WebAPI

平台宜提供WebAPI接口方式，使用JSON格式进行数据传递。基本设计原则是对

CRUD操作使用HTTP协议对应的方法：

POST-创建资源

GET-检索资源

PUT–更新资源-

DELETE-删除资源

返回值JSON格式：

{

"message":"OK",

"state":1,

"code":"",

"data":""

}

其中，

message为消息提示；state为状态，1-成功，0-失败；code为响应代码，详见附录A；

data为结果。

3

在本部分后面的描述中，都以此方式进行阐述。

5.2.2WebService

平台可提供WebService接口方式，请求参数与返回值使用XML的方式进行数据传递。

6接口描述

监控系统与运营服务平台

6.1运营服务平台除通过规约与监控系统进行交互外，运营服务平台也可以通过接口获取数

据、发送指令，分为登陆、获取设备数据列表、获取设备实时数据、获取设备历史数据、远

程控制这五大类接口，如图2。

图2监控系统与运营服务平台接口图

a)登陆。为防止恶意调用，在运营服务平台进行交互时，首先应进行登陆认证，只有

认证通过的平台才能调用接口，详见第7节接口安全；

b)获取设备数据列表。不同类型的设备能采集的数据有所不同，通过此接口，获取指

定设备的数据列表，返回值列举了所有能采集的数据项的唯一名称及含义，详见附

录B表B.2；

c)获取设备实时数据。通过调用此接口，可获取设备所有数据项的实时状态或值，也

可根据数据项名称获取某一数据的实时状态或值，详见附录B表B.3；

d)获取设备历史数据。根据数据项名称、时间段，获取设备某一数据在指定时间段的

数据列表，详见附录B表B.4；

e)远程控制设备。监控系统根据需求可提供远程控制设备接口，用于运营服务平台远

程调控设备，操作指令应能够进行扩展，详见附录B表B.5。

监控系统与第三方平台

6.2由于监控系统为第三方平台提供的接口功能与为运营服务平台提供类似，此部分接口内

容参照6.1节内容。

运营服务平台与第三方平台

6.3第三方平台获取设备的数据可以通过监控系统提供的接口，运营服务平台为第三方平台

提供的接口主要为统计相关的接口，分为登陆、运行时间统计、报警时间统计、耗能量统计

这四大类接口，如图3。

4

图3运营服务平台与第三方平台接口图

a)登陆。为防止恶意调用，同样首先要进行登陆认证；

b)运行时间统计。通过此接口，获取设备指定时间段的运行时间统计结果，可按日、

月、年进行查询，详见附录B表B.6；

c)报警时间统计。通过此接口，获取设备指定时间段的报警时间统计结果，可按日、

月、年进行查询，详见附录B表B.7；

d)耗能量统计。通过此接口，获取设备指定时间段的耗能量统计结果，可按日、月、

年进行查询，详见附录B表B.8。

7接口安全

密钥机制

7.1动态获取密钥，有一个接口需要首先调用，让接口提供方返回密钥，于是就有了登录的

概念，过程如图4。

图4密钥机制过程图

这样只有接口调用方和提供方才知道动态生成的密钥，而且密钥具有时效性，规定为1h，

当密钥超时，会判定无效，应重新进行登陆认证。

登陆机制

7.2进行调用接口前，调用方都需要调用登陆接口进行安全认证。登陆时传入参数：用户名、

密码。用户信息应向提供方申请获得。登陆接口详见附录B表B.1。

5

附录A

（资料性附录）

code含义表

code含义见表A.1。

表A.1code含义表

序号code值含义

10000无异常

20001密钥超时

30002参数缺失

40003参数值格式有误

58008未知异常

6

附录B

（资料性附录）

接口详解

登陆接口解析见表B.1。

表B.1登陆接口解析表

请求方式POST

服务路径/login

Body参数deviceId:监控系统ID

userName:用户名

password:密码

返回值类型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data":"KEY值"//密钥值

}

获取设备数据列表接口解析见表B.2。

表B.2获取设备数据列表接口解析表

请求方式GET

服务路径/data/list

Body参数key:密钥

deviceId:监控系统ID

equipmentAdd:设备地址

返回值类型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data"://数据列表

{

"voltage":"电压",

"current":"电流",

"power":"功率",

"indoorTemp":"室内温度",

"outsideTemp":"室外温度",

…

}

}

7

获取设备实时数据接口解析见表B.3。

表B.3获取设备实时数据接口解析表

请求方式GET

服务路径/data：获取所有数据实时值，/data/name:根据数据项名称获取

Body参数key:密钥

deviceId:监控系统ID

equipmentAdd:设备地址

dataName:数据项名称，根据数据项名称获取时需要

返回值类型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data"://数据值

{

"voltage":"220",

"current":"2",

"power":"440",

…

}

}

获取设备历史数据接口解析见表B.4。

表B.4获取设备历史数据接口解析表

请求方式GET

服务路径/data/record/name

Body参数key:密钥

deviceId:监控系统ID

equipmentAdd:设备地址

dataName:数据项名称

beginTime:开始时间

endTime:结束时间

返回值类型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data"://数据值

[

{

"id":1,

"value":"220",//值

"time":"1502089272000",//时间戳

8

},

{

"id":2,

"value":"222",//值

"time":"1502089272000",//时间戳

}

...

]

}

远程控制接口解析见表B.5。

表B.5远程控制接口解析表

请求方式POST

服务路径/control

Body参数key:密钥

deviceId:监控系统ID

equipmentAdd:设备地址

code:操作代码，0010-开关机，可扩展

value:1-开机，0-关机

返回值类型application/json

返回值描述{

"message":"OK",

"state":1,

"code":"0000",

"data":""

}

运行时间统计接口解析见表B.6。

表B.6运行时间统计接口解析表

请求方式GET

服务路径/runtime

Body参数key:密钥

deviceId:监控系统ID

equipmentAdd:设备地址,可选，不选时统计监控系统下所有设备

beginTime:开始时间

endTime:结束时间

period:统计周期,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",//日期

}

...

]

}

报警时间统计接口解析见表B.7。

表B.7报警时间统计接口解析表

请求方式GET

服务路径/alarmtime

Body参数key:密钥

deviceId:监控系统ID

equipmentAdd:设备地址,可选，不选时统计监控系统下所有设备

beginTime:开始时间

endTime:结束时间

period:统计周期,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",//日期

}

...

]

}

耗能