T∕CEC 165.10-2018 电供暖系统技术规范 第10部分：接口

ICS 29.020 P 46 备案号：53939-2016 准T / CEC 165.102018 电供暖系统技术规范 第 10 部分：接口 Electrical heating system technical specification Part 10: Interface 2018-01-24 发 布 2018-04-01 实施 中国电力企业联合会 发布 T / CEC 165.102018 中国电力企业联合会标准 电供暖系统技术规范 第 10 部分：接口 T / CEC 165.102018 *中国电力出版社出版、发行 （北京市东城区北京站西街 19 号 100005 ） 北京传奇佳彩印刷有限公司印刷 *2019 年 7 月第一版 2019 年 7 月北京第一次印刷 880 毫米1230 毫米 16 开本 0.75 印张 20 千字 *统一书号 155198.1145 定价 15.00 元 版权专有 侵权必究 本书如有印装质量问题，我社营销中心负责退换 T / CEC 165.102018 目次前言 II 1 范围 1 2 规范性引用文件  1 3 术语和定义  1 4 接口概述  1 5 接口要求  2 6 接口描述  2 7 接口安全  3 附录 A（资料性附录） code 含义表  4 附录 B（资料性附录） 接口详解  5 IT / CEC 165.102018 前言T/CEC 165电供暖系统技术规范分为 12 个部分： 第 1 部分：总则； 第 2 部分：设备； 第 3 部分：系统设计； 第 4 部分：施工和安装； 第 5 部分：验收； 第 6 部分：监控系统； 第 7 部分：运营服务平台； 第 8 部分：通信规约； 第 9 部分：运行维护； 第 10 部分：接口； 第 11 部分：计量； 第 12 部分：检测。 本部分为 T/CEC 165 的第 10 部分。 本部分按照 GB/T 1.12009标准化工作导则 第 1 部分：标准的结构和编写给出的规则起草。 本部分由中国电力企业联合会提出并归口。 本部分主要起草单位：中国电力科学研究院有限公司、济南博佳特物联科技有限公司、湖南索拓 科技有限公司、许继集团有限公司、国网湖南省电力有限公司、国网北京市电力公司、秦皇岛华电测 控设备有限公司、国网冀北电力有限公司、青岛高校信息产业股份有限公司、国网江西省电力有限公 司、国网甘肃综合能源服务有限公司、国网信通产业集团有限公司。 本部分主要起草人：郭炳庆、孙志安、陈铁军、钟鸣、徐亮、崔明思、王瀚秋、蒋利民、何友诚、 罗志坤、陈宋宋、孙贝贝、周琪、刘潇潇、李香龙、张建华、白中华、夏稀源、秦玉臣、李琼。 本标准是首次发布。 本部分在执行过程中的意见或建议反馈至中国电力企业联合会标准化管理中心（北京市白广路二 条一号，100761） 。II T / CEC 165.102018 电供暖系统技术规范 第 10 部分：接口 1范围 T/CEC 165 的本部分规定了接口的要求、描述、安全等。 本部分适用于电供暖系统接口的设计、开发、施工和安装、验收、运行和维护等。 2规范性引用文件 下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文 件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 GB/T 22239 信息安全技术 信息系统安全等级保护基本要求 3术语和定义 下列术语和定义适用于本文件。 3.1 Web API 互联网应用程序接口，网络应用程序可通过应用程序接口（API） ，实现存储服务、消息服务、计 算服务等能力，利用这些能力可以开发面向各种客户端服务的互联网应用。 3.2 Web Service 一种跨平台、跨语言的互联网信息互联规范和技术，用于不同操作系统、不同编程语言开发的应 用之间的交互和远程调用，能使得运行在不同机器上的不同应用无须借助附加的、专门的第三方软件 或硬件，就可相互交换数据或集成。 4接口概述 运营平台、监控系统与第三方平台进行数据交互是通过接口来实现，相关接口关系见图 1。接口包 括下列三类： a） 运营服务平台可通过接口为第三平台提供数据支撑，完成业务功能，还可通过接口从第三方获 取数据； 图1 接口关系 b） 监控系统可通过接口与第三方平台进行交互，可通过第三方平台通过接口下发指令至监控系统 1T / CEC 165.102018 远程操控设备。 55.1 5.2 接口要求 一般要求 本部分接口的设计和开发应满足下列要求： a） 数据完整性。发送数据时，收发双方必须确保通信数据的完整性，传输失败时，记入日志并做 相应失败处理操作。 b） 数据正确性。收发双方要保证所使用的接口协议的一致性，确保使用的是同一接口的相同版 本、收发双方具备数据校验码，只有在数据校验码完全正确时，收方才认同数据正确。 c） 数据保密性。应严密控制各个可能泄密的环节，使数据在产生、传输、处理和存储的各个环节 中不泄漏给非授权的个人和实体，具体应满足 GB/T 22239 规定的要求。 d） 接口扩展性。接口宜随着平台业务的调整而增加或改变传送内容，同时应对修改的接口协议进 行版本管理，且协议双方可以互查对方授权的接口协议内容。 接口方式 5.2.1 Web API 平台宜提供 Web API 接口方式，采用 JSON 格式进行数据传递。基本设计原则是对 CRUD 操作， 使用 HTTP 协议对应的方法有：POST-创建资源；GET-检索资源；PUT-更新资源；DELETE-删除资 源。其中，返回值 JSON 格式： "message":"OK"， "state":1， "code":"0000"， "data":"" 返回值 JSON 格式中，message 为消息提示；state 为状态，1 表示操作成功，0 表示操作失败； code 为响应代码，code 含义详细参见附录 A；data 为结果。 5.2.2 Web Service 平台可提供 Web Service 接口方式，请求参数与返回值宜采用 XML 的方式进行数据传递。 6接口描述 6.1 监控系统与运营服务平台 监控系统与运营服务平台的接口应包括登录、获取设备数据列表、获取设备实时数据、获取设备 历史数据、远程控制五种接口。应符合如下要求： a） 登录接口要求详见第 7 章接口安全； b） 调用获取设备数据列表接口，应能够获取指定设备的数据列表，返回值应列举所有能采集的数 据项的唯一名称及含义，详细参见附录 B 中表 B.1； c） 调用获取设备实时数据接口，应能够获取设备所有数据项的实时状态或值，也能够根据数据项 名称获取某一数据的实时状态或值，详细参见附录 B 中表 B.2； 2T / CEC 165.102018 d） 调用获取设备历史数据接口，应能够根据数据项名称、时间段，获取设备某一数据在指定时间 段的数据列表，详细参见附录 B 中表 B.3； e） 监控系统根据需求可提供远程控制设备接口，用于运营服务平台远程调控设备，操作指令应能 够进行扩展，详细参见附录 B 中表 B.4。 6.2 监控系统与第三方平台 监控系统为第三方平台提供的接口功能与为运营服务平台提供类似，此部分接口内容应与 6.1 保持 一致。 6.3 运营服务平台与第三方平台 运营服务平台与第三方平台的接口包括登录、运行时间统计、报警时间统计、耗能量统计四种接 口，应符合如下要求： a） 调用运行时间统计接口，应能够获取设备指定时间段的运行时间统计结果，应可以按日、月、 年进行查询，详细参见附录 B 中表 B.5； b） 调用报警时间统计接口，应能够获取设备指定时间段的报警时间统计结果，应可以按日、月、 年进行查询，详细参见附录 B 中表 B.6； c） 调用耗能量统计接口，应能够获取设备指定时间段的耗能量统计结果，应可以按日、月、年进 行查询，详细参见附录 B 中表 B.7。 7接口安全 7.1 密钥机制 密钥应动态获取，在系统进行交互时，应先调用登录接口进行登录认证，认证成功后返回密钥， 过程如图 2。 图2 密钥机制过程 应保证只有接口调用方和提供方知道动态生成的密钥，而且密钥应具有时效性，规定为 1h。当密 钥超时，会判定无效，应重新进行登录认证。 7.2 登录机制 登录接口应传入用户信息参数：用户名、密码。用户信息由接口调用方向接口提供方申请获得。 登录接口详细参见附录 B 中表 B.8。 3T / CEC 165.102018 附录A （资料性附录） code 含 义 表 code 含义见表 A.1。 表 A.1 code 含 义表序号 code 值 含义10000 无异常 20001 密钥超时 30002 参数缺失 40003 参数值格式有误 58008 未知异常 4T / CEC 165.102018 附录B （资料性附录） 接口详解 获取设备数据列表接口解析见表 B.1。 表 B.1 获取设备数据列表接口解析表 请求方式 GET 服务路径 /data/list Body 参数 返回值类型 返回值描述 key：密钥 deviceId：监控系统 ID equipmentAdd：设备地址 application/json "message":"OK"， "state":1， "code":"0000"， "data": /数据列表 "voltage":"电压"， "current":"电流"， "power":"功率"， "indoorTemp":"室内温度"， "outsideTemp":"室外温度"， 获取设备实时数据接口解析见表 B.2。 表 B.2 获取设备实时数据接口解析表 请求方式 GET 服务路径 Body 参数 返回值类型 返回值描述 /data：获取所有数据实时值，/data/name：根据数据项名称获取 key：密钥 deviceId：监控系统 ID equipmentAdd：设备地址 dataName：数据项名称，根据数据项名称获取时需要 application/json "message":"OK"， "state":1， "code":"0000"， "data": /数据值 "voltage":"220"， "current":"2"， "power":"440"， 5T / CEC 165.102018 获取设备历史数据接口解析见表 B.3。 表 B.3 获取设备历史数据接口解析表 请求方式 GET 服务路径 Body 参数 返回值类型 返回值描述 远程控制接口解析见表 B.4。 /data/record/name key：密钥 deviceId：监控系统 ID equipmentAdd：设备地址 dataName：数据项名称 beginTime：开始时间 endTime：结束时间 application/json "message":"OK"， "state":1， "code":"0000"， "data": /数据值 "id":1， "value":"220"，/值 "time":"1502089272000"，/时间戳 ， "id":2， "value":"222"，/值 "time":"1502089272000"，/时间戳 . 表 B.4 远程控制接口解析表 请求方式 POST 服务路径 Body 参数 返回值类型 返回值描述 /control key：密钥 deviceId：监控系统 ID equipmentAdd：设备地址 code：操作代码，0010-开关机，可扩展 value：1-开机，0-关机 application/json "message":"OK"， "state":1， "code":"0000"， "data":"" 6T / CEC 165.102018 运行时间统计接口解析见表 B.5。 表 B.5 运行时间统计接口解析表 请求方式 服务路径 Body 参数 返回值类型 返回值描述 GET /runtime 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，/运行时间 "unit":"s "，/单位 "date":"2017-11"，/日期 . 报警时间统计接口解析见表 B.6。 表 B.6 报警时间统计接口解析表 请求方式 服务路径 Body 参数 返回值类型 返回值描述 GET /alarmtime key：密钥 deviceId：监控系统 ID equipmentAdd：设备地址，可选，不选时统计监控系统下所有设备 beginTime：开始时间 endTime：结束时间 period：统计周期，0-日，1-月，2-年 application/json "message":"OK"， "state":1， "code":"0000"， "data": 7T / CEC 165.102018 表 B.6（续） "id":1， "value":22000，/报警时间 "unit":"s "，/单位 "date":"2017-10"，/日期 ， 返回值描述 "id":2， "value":22000，/报警时间 "unit":"s "，/单位 "date":"2017-11"，/日期 . 耗能量统计接口解析见表 B.7。 表 B.7 耗能量统计接口解析表 请求方式 服务路径 Body 参数 返回值类型 返回值描述 GET /energy key：密钥 deviceI