附件2
武汉市节能智慧管理系统
数据接口规范
武汉市发展和改革委员会
2013年12月
1
前言
为指导我市各级节能智慧管理系统建设，市组织有关专家，以我国现行相关标准为依据，结合我市节能智慧管理系统建设、验收和运行管理要求，研究制定了本数据接口规范。
本规范包括主要用能单位上传数据接口标准规范和市区各级系统上传数据接口标准规范两部分，其中两部分包括了接口的标准应用范围、接口的实现、接口的要求、术语和定义和基本原则。
本规范由市负责管理和解释。
2
目录
1. 主要用能单位上传数据接口规范
...................................................... 5
1.1标准应用范围................................................................................ 51.2术语和定义.................................................................................... 51.3基本原则........................................................................................ 51.4接口实现........................................................................................ 6
1.4.1数据提供方.......................................................................... 61.4.2数据接收方.......................................................................... 61.4.3接口的实现方式.................................................................. 71.4.4传输方式.............................................................................. 71.4.5传输协议.............................................................................. 71.4.6传输过程.............................................................................. 71.4.7编码原则.............................................................................. 81.4.8接口的验证方式.................................................................. 81.4.9使用策略.............................................................................. 91.5接口数据的要求及保障 ............................................................... 92. 区分系统上传数据接口规范 ............................................................ 10
2.1标准应用范围.............................................................................. 10 2.2术语和定义.................................................................................. 10 2.3基本原则...................................................................................... 10 2.4接口实现...................................................................................... 11
3
2.4.1数据提供方........................................................................ 11 2.4.2数据接收方........................................................................ 12 2.4.3接口的实现方式................................................................ 12 2.4.4传输方式............................................................................ 12 2.4.5传输协议............................................................................ 12 2.4.6传输过程............................................................................ 12 2.4.7编码原则............................................................................ 13 2.4.8接口的验证方式................................................................ 13 2.4.9使用策略............................................................................ 14 2.5接口数据的要求及保障 ............................................................. 14 附录1 数据采集器身份认证过程和数据加密
..................................... 15
......................... 16
附录2 数据采集器或子系统和市数据中心通信过程
附录3 数据传输的XML数据格式...................................................... 17
4
1.主要用能单位上传数据接口规范
1.1标准应用范围
本标准主要为解决主要用能单位与市
/区系统数据交互问题，指
导主要用能单位向武汉市或各区节能智慧管理系统上传能耗数据。1.2术语和定义
名词接口规范数据提供方数据接收方日志
指本文档
主要用能单位节能智慧管理子系统武汉市/各区节能智慧管理系统
指接口系统在操作过程中数据处理结果的数据库记录或文件。
1.3基本原则
为了保证数据提供方和数据接收方之间高效、准确地交换数据，因此接口规范的编制应符合如下原则：
数据提供方和数据接收方之间接口应具备完整性、
放性和灵活性；
接口定义遵循易理解、易使用、易交流、方便扩展的原则；保证数据提供方和数据接收方的数据一致性；
在满足业务需求的前提下，使接口数据量最少，最大限度地减
轻数据接收方的压力；
具有可靠完善的接口数据传输与错误纠正机制，
确性和完整性。
5
说明
规范性、开
保证数据的正
1.4接口实现1.4.1数据提供方
数据提供方应满足以下要求与功能1)2)3)
:
保证按时提供接口规范规定的数据内容；
对接口数据提供相关的验证功能，保证数据的准确性、一致性；若相关系统有变更，则要求在变更前提供变更内容说明，
并及
时更新本接口规范及相关附件的相应内容；4)5)6)7)8)
遵循本接口规范中规定的验证规则；应及时解决接口数据提供过程中出现的问题。对于未尽事宜，应同数据接收方协商解决。
数据提供方应具有在上传数据之前对数据的加密的功能。数据提供方的数据接口应能根据数据接收方的接口更新和升
级，灵活的调整，达到灵活的与数据接收方的数据对接。9)
能够满足数据接收方所要求的数据接收频率，
根据上传频率自
动将所需数据传送至系统。10)
用能单位在传输数据时候，如突遇网络异常或其他异常情况，
应具有断点续传和补全历史数据的功能。11)
具有用能单位自身内部的用能单位子系统，
能够读取到设备的
能耗数据，将数据接收方所需的数据根据上传频率传送至市系统。1.4.2数据接收方1)2)
按时接收接口规范规定的相关数据内容。对接收的数据提供验证功能。
6
3)4)5)6)
遵循本接口规范中规定的验证规则和变更说明。对于未尽事宜，应同数据提供方协商解决。数据接收方具有设置数据提供方的上传权限的功能。数据接收方能够根据配置量控制数据提供方的数据量。
1.4.3接口的实现方式1.
采用服务（SOA理念）的方式提供数据共享；接口交互技术采
用WebServices方式。2.
交换内容组织格式统一采用
XML方式，字符编码格式采用
UTF-8。3.
XML解析技术采用SAX解析技术（解析器可自编程）。
1.4.4传输方式
数据主要通过数据接口的方式进行传输。具体要求包括：
支持网络模式传输，可以实现跨越局域网络、广域网络等系统
的数据传送获取。
支持对接口机的IP地址、帐户、口令、存取目录的验证。1.4.5传输协议
接口应支持TCP/IP（HTTP、FTP）网络协议。1.4.6传输过程数据传输应支持：
实时、高效和安全可靠地传送数据；传输过程中的差错控制。
7
数据接口处理过程：
数据接收方在接收数据之前对数据提供方进行安全验证。数据接收方接收数据或文件，并校验是否成功获取；若成功，则对数据包或文件名进行标识并存放在相应数据库或
目录；
若失败，则对数据包或文件名进行读取失败标识，
存放在相应
数据库或目录，并通知相关系统及时处理故障，协商重传时间。1.4.7编码原则1.2.
对所有交互对象及对象属性统一命名
方法、参数名称采用首字母小写，后面每个单词首字母大写的
形式，缩写为1-3个字母的参考第一个规则（如getUserID、getUserName）1.4.8接口的验证方式
为了保证能源数据的准确性，必须对数据提供方与数据接收方之间的数据接口进行验证，接口数据的验证由接口双方共同负责。
实时验证：每次数据提供方调用数据接收方接口进行数据交互时，对交互的数据进行验证。验证方法
数据提供方在上报数据前根据报表数据要求和接口数据要求对上报数据进行初步校验。
数据接收方在接收到上报数据后对数据格式、的完整性进行校验。
8
数据长度、数据
1.4.9使用策略
调用时间根据数据接收方所需要的上传频率来进行数据上传。调用频率根据数据接收方所需要的上传频率要求可以多次调
用。
触发机制由数据提供方向数据源提供方推送数据。
1.5接口数据的要求及保障
数据接收方在发现数据错误时，必须及时记录日志，并将校验通过的数据和校验失败的数据转存到相应字段中。校验：
主键检查
主键唯一性校验，检查接口数据中是否违反规范定义的唯一性约束；
数据类型及格式检查
字段类型检查，检查各字段类型是否与规范定义一致；数据值域检查对数据的取值有效检查。
需要对数据进行逻辑
9
2.区分系统上传数据接口规范
2.1标准应用范围
本标准主要为解决武汉市各区分系统与市系统数据交互问题，导各区分系统向市系统上传能耗数据。2.2术语和定义
名词接口规范数据提供方数据接收方日志
指本文档
武汉市各区节能智慧管理分系统武汉市节能智慧管理系统
指接口系统在操作过程中数据处理结果的数据库记录或文件。
2.3基本原则
为了保证数据提供方和数据接收方之间高效、准确地交换数据，因此接口规范的编制应符合如下原则：
数据提供方和数据接收方之间接口应具备完整性、放性和灵活性；
接口定义遵循易理解、易使用、易交流、方便扩展的原则；保证数据提供方和数据接收方的数据一致性；
在满足业务需求的前提下，使接口数据量最少，最大限度地减轻数据接收方的压力；
具有可靠完善的接口数据传输与错误处理机制。
规范性、开
说明
指
10
2.4接口实现2.4.1数据提供方
数据提供方应满足以下要求与功能1)2)3)
:
保证按时提供接口规范规定的数据内容；
对接口数据提供相关的验证功能，保证数据的准确性、一致性；若相关系统有变更，则要求在变更前提供变更内容说明，
并及
时更新本接口规范及相关附件的相应内容；4)5)6)7)8)
遵循本接口规范中规定的验证规则；应及时解决接口数据提供过程中出现的问题。对于未尽事宜，应同数据接收方协商解决。
上传数据前应有对数据的打包压缩和加密的处理过程。数据提供方在进行接口开发时
,应具有灵活和迅速与数据接收
方进行对接，包括在后期的接口迁移和升级，能快速的与数据接口进行对接传输数据。9)
能够满足数据接收方根据实际需求所需要的数据接收频率，
根
据上传频率自动将所需数据传送10)
数据提供方在传输数据时候，突遇网络异常或其他异常情况，
应具有断点续传和补全历史数据的功能。11)
具有接收到用能单位级能管中心的能耗数据的功能，
以及用能
单位上报的数据。12)
能够保证用能单位到地市系统，地市系统到省系统的数据数据
一致性和完整性。
11
2.4.2数据接收方1)2)3)4)5)6)
按时接收接口规范规定的相关数据内容；对接收的数据提供验证功能；
遵循本接口规范中规定的验证规则和变更说明。对于未尽事宜，应同数据提供方协商解决。
数据接收方对数据提供方的上传数据权限分配和设置。数据接收方对数据提供方的数据量控制。
2.4.3接口的实现方式1.
采用服务（SOA理念）的方式提供数据共享; 接口交互技术采
用WebServices方式。2.
交换内容组织格式统一采用
XML方式，字符编码格式采用
UTF-8。3.
XML接析技术采用SAX解析技术（解析器可自编程）。
2.4.4传输方式
数据主要通过数据接口的方式进行传输。具体要求包括：
支持网络模式传输，可以实现跨越局域网络、广域网络等系统的数据传送获取。
支持对接口机的IP地址、帐户、口令、存取目录的验证。
2.4.5传输协议
接口应支持TCP/IP（HTTP、FTP）网络协议。2.4.6传输过程数据传输应支持：
12
实时、高效和安全可靠地传送数据；传输过程中的差错控制。
传输过程中如有网络出现异常或其他异常情况导出数据不能正常上传至系统，数据提供方能够自动进行续传或补齐丢失数据的功能。数据接口处理过程：
数据接收方在接收数据之前对数据提供方进行安全验证。数据接收方接收数据或文件，并校验是否成功获取；若成功，则对数据包或文件名进行标识并存放在相应数据库或目录；
若失败，则对数据包或文件名进行读取失败标识，
存放在相应
数据库或目录，并通知相关系统及时处理故障，协商重传时间。
2.4.7编码原则
1.对所有交互对象及对象属性统一命名2.
方法、参数名称采用首字母小写，后面每个单词首字母大写的
形式，缩写为1-3个字母的参考第一个规则（如getUserID、getUserName）2.4.8接口的验证方式
为了保证能源数据的准确性，必须对数据提供方与数据接收方之间的数据接口进行验证，接口数据的验证由接口双方共同负责。
实时验证：每次数据提供方调用数据接收方接口进行数据交互时，对交互的数据进行验证。
13
验证方法
数据提供方在上报数据前根据报表数据要求和接口数据要求对上报数据进行初步校验。
数据接收方在接收到上报数据后对数据格式、的完整性进行校验。
2.4.9使用策略
调用时间定于规定上报期内的任何时段，能耗实时数据根据数据接收方的频率进行上传
调用频率根据实际上报要求可以多次调用，数据接收方的频率进行多次调用
触发机制由数据提供方向数据源提供方推送数据
2.5接口数据的要求及保障
数据接收方在发现数据错误时，必须及时记录日志，并将校验通过的数据和校验失败的数据转存到相应字段中。校验.
主键检查
主键唯一性校验，检查接口数据中是否违反规范定义的唯一性约束；
数据类型及格式检查
字段类型检查，检查各字段类型是否与规范定义一致；
数据值域检查对数据的取值有效检查。
14
数据长度、数据
能耗实时数据根据
需要对数据进行逻辑
附录1 数据采集器身份认证过程和数据加密
1．身份认证过程
数据中心使用MD5算法进行数据采集器身份认证，密钥长度为128bit，具体过程如下：
（1）TCP连接建立成功后，数据采集器向数据中心发送身份认证请求；
（2）数据中心向数据采集器发送一个随机序列；
（3）数据采集器将接收到的随机序列和本地存储的认证密钥组合成一连接串，计算连接串的
（4）数据中心将接收到的
MD5值并发送给数据中心; MD5值和本地计算结果相比较，如
果一致则认证成功，否则认证失败。
认证密钥存储在数据中心和数据采集器的本地文件系统中，数据中心可以通过网络对数据采集器的认证密钥进行更新。2．数据加密
使用AES加密算法对
XML数据包进行加密，密钥长度为
128bit。加密密钥存储在数据中心和数据采集器的本地文件系统中，数据中心可以通过网络对数据采集器的加密密钥进行更新。
15
附录2 数据采集器或子系统和市数据中心通信过程
开始
是
否
数据采集器向数据中心发起TCP连接
连接无效？
连接成功？
发送心跳*连接监测
是
否
数据中心对数据采集器进行身份验证
否
验证失败验证成功？
是
配置设置
数据采集**(数据处理)***数据远/重传
否
数据存储远传成功？
是
结束
附图数据采集器或子系统和市数据中心通信过程
* 连接成功后数据采集器定时向数据中心发送心跳包以保持连接的有效性
** 数据采集根据系统配置在主动定时和被动查询模式间选择*** 数据采集器对能耗数据的处理功能根据系统配置选择
16
附录3 数据传输的XML数据格式
1．身份验证数据包(id_validate) XXXXXXXXX以下4种操作类型之一
XXXXXXXX XXXXXXXXpass/fail
2．心跳/校时数据包(heart_beat) XXXXXXXXX以下2种操作类型之一
3．能耗远传数据包(data)
XXXXXXXXX以下5种操作类型之一
XXXXXXXXyes/no
数据220
数据1
数据2
4．配置信息数据包(config)
XXXXXXXXX以2种操作类型之一
21
15
22
