主要用能单位上传数据接口规范.doc

附件2

武汉市节能智慧管理系统
数据接口规范

武汉市发展和改革委员会
2013年12月
前言
为指导我市各级节能智慧管理系统建设，市发改委组织有关专家，以我国现行相关标准为依据，结合我市节能智慧管理系统建设、验收和运行管理要求，研究制定了本数据接口规范。
本规范包括主要用能单位上传数据接口标准规范和市区各级系统上传数据接口标准规范两部分，其中两部分包括了接口的标准应用范围、接口的实现、接口的要求、术语和定义和基本原则。
本规范由市发改委负责管理和解释。
目 录
1. 主要用能单位上传数据接口规范 2
1.1标准应用范围 2
1.2术语和定义 2
1.3基本原则 2
1.4接口实现 2
1.4.1数据提供方 2
1.4.2数据接收方 2
1.4.3接口的实现方式 2
1.4.4传输方式 2
1.4.5传输协议 2
1.4.6传输过程 2
1.4.7编码原则 2
1.4.8接口的验证方式 2
1.4.9使用策略 2
1.5接口数据的要求及保障 2
2. 区分系统上传数据接口规范 2
2.1标准应用范围 2
2.2术语和定义 2
2.3基本原则 2
2.4接口实现 2
2.4.1数据提供方 2
2.4.2数据接收方 2
2.4.3接口的实现方式 2
2.4.4传输方式 2
2.4.5传输协议 2
2.4.6传输过程 2
2.4.7编码原则 2
2.4.8接口的验证方式 2
2.4.9使用策略 2
2.5接口数据的要求及保障 2
附录1 数据采集器身份认证过程和数据加密 2
附录2 数据采集器或子系统和市数据中心通信过程 2
附录3 数据传输的XML数据格式 2

1. 主要用能单位上传数据接口规范
1.1标准应用范围
本标准主要为解决主要用能单位与市/区系统数据交互问题，指导主要用能单位向武汉市或各区节能智慧管理系统上传能耗数据。
1.2术语和定义
名词
说明
接口规范
指本文档
数据提供方
主要用能单位节能智慧管理子系统
数据接收方
武汉市/各区节能智慧管理系统
日志
指接口系统在操作过程中数据处理结果的数据库记录或文件。
1.3基本原则
为了保证数据提供方和数据接收方之间高效、准确地交换数据，因此接口规范的编制应符合如下原则：
² 数据提供方和数据接收方之间接口应具备完整性、规范性、开放性和灵活性；
² 接口定义遵循易理解、易使用、易交流、方便扩展的原则；
² 保证数据提供方和数据接收方的数据一致性；
² 在满足业务需求的前提下，使接口数据量最少，最大限度地减轻数据接收方的压力；
² 具有可靠完善的接口数据传输与错误纠正机制，保证数据的正确性和完整性。
1.4接口实现
1.4.1数据提供方
数据提供方应满足以下要求与功能:
1) 保证按时提供接口规范规定的数据内容；
2) 对接口数据提供相关的验证功能，保证数据的准确性、一致性；
3) 若相关系统有变更，则要求在变更前提供变更内容说明，并及时更新本接口规范及相关附件的相应内容；
4) 遵循本接口规范中规定的验证规则；
5) 应及时解决接口数据提供过程中出现的问题。
6) 对于未尽事宜，应同数据接收方协商解决。
7) 数据提供方应具有在上传数据之前对数据的加密的功能。
8) 数据提供方的数据接口应能根据数据接收方的接口更新和升级，灵活的调整，达到灵活的与数据接收方的数据对接。
9) 能够满足数据接收方所要求的数据接收频率，根据上传频率自动将所需数据传送至系统。
10) 用能单位在传输数据时候，如突遇网络异常或其他异常情况，应具有断点续传和补全历史数据的功能。
11) 具有用能单位自身内部的用能单位子系统，能够读取到设备的能耗数据，将数据接收方所需的数据根据上传频率传送至市系统。
1.4.2数据接收方
1) 按时接收接口规范规定的相关数据内容。
2) 对接收的数据提供验证功能。
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传输过程
数据传输应支持：
² 实时、高效和安全可靠地传送数据；
² 传输过程中的差错控制。
数据接口处理过程：
² 数据接收方在接收数据之前对数据提供方进行安全验证。
² 数据接收方接收数据或文件，并校验是否成功获取；
² 若成功，则对数据包或文件名进行标识并存放在相应数据库或目录；
² 若失败，则对数据包或文件名进行读取失败标识，存放在相应数据库或目录，并通知相关系统及时处理故障，协商重传时间。
1.4.7编码原则
1. 对所有交互对象及对象属性统一命名
2. 方法、参数名称采用首字母小写，后面每个单词首字母大写的形式，缩写为1-3个字母的参考第一个规则（如getUserID、getUserName）
1.4.8接口的验证方式
为了保证能源数据的准确性，必须对数据提供方与数据接收方之间的数据接口进行验证，接口数据的验证由接口双方共同负责。
u 实时验证：每次数据提供方调用数据接收方接口进行数据交互时，对交互的数据进行验证。
² 验证方法
u 数据提供方在上报数据前根据报表数据要求和接口数据要求对上报数据进行初步校验。
u 数据接收方在接收到上报数据后对数据格式、数据长度、数据的完整性进行校验。
1.4.9使用策略
² 调用时间根据数据接收方所需要的上传频率来进行数据上传。
² 调用频率根据数据接收方所需要的上传频率要求可以多次调用。
² 触发机制由数据提供方向数据源提供方推送数据。
1.5接口数据的要求及保障
数据接收方在发现数据错误时，必须及时记录日志，并将校验通过的数据和校验失败的数据转存到相应字段中。需要对数据进行逻辑校验：
² 主键检查
主键唯一性校验，检查接口数据中是否违反规范定义的唯一性约束；
² 数据类型及格式检查
字段类型检查，检查各字段类型是否与规范定义一致；
² 数据值域检查
对数据的取值有效检查。

2. 区分系统上传数据接口规范
2.1标准应用范围
本标准主要为解决武汉市各区分系统与市系统数据交互问题，指导各区分系统向市系统上传能耗数据。
2.2术语和定义
名词
说明
接口规范
指本文档
数据提供方
武汉市各区节能智慧管理分系统
数据接收方
武汉市节能智慧管理系统
日志
指接口系统在操作过程中数据处理结果的数据库记录或文件。
2.3基本原则
为了保证数据提供方和数据接收方之间高效、准确地交换数据，因此接口规范的编制应符合如下原则：
² 数据提供方和数据接收方之间接口应具备完整性、规范性、开放性和灵活性；
² 接口定义遵循易理解、易使用、易交流、方便扩展的原则；
² 保证数据提供方和数据接收方的数据一致性；
² 在满足业务需求的前提下，使接口数据量最少，最大限度地减轻数据接收方的压力；
² 具有可靠完善的接口数据传输与错误处理机制。
2.4接口实现
2.4.1数据提供方
数据提供方应满足以下要求与功能:
1) 保证按时提供接口规范规定的数据内容；
2) 对接口数据提供相关的验证功能，保证数据的准确性、一致性；
3) 若相关系统有变更，则要求在变更前提供变更内容说明，并及时更新本接口规范及相关附件的相应内容；
4) 遵循本接口规范中规定的验证规则；
5) 应及时解决接口数据提供过程中出现的问题。
6) 对于未尽事宜，应同数据接收方协商解决。
7) 上传数据前应有对数据的打包压缩和加密的处理过程。
8) 数据提供方在进行接口开发时,应具有灵活和迅速与数据接收方进行对接，包括在后期的接口迁移和升级，能快速的与数据接口进行对接传输数据。
9) 能够满足数据接收方根据实际需求所需要的数据接收频率，根据上传频率自动将所需数据传送
10) 数据提供方在传输数据时候，突遇网络异常或其他异常情况，应具有断点续传和补全历史数据的功能。
11) 具有接收到用能单位级能管中心的能耗数据的功能，以及用能单位上报的数据。
12) 能够保证用能单位到地市系统，地市系统到省系统的数据数据一致性和完整性。
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传输过程
数据传输应支持：
² 实时、高效和安全可靠地传送数据；
² 传输过程中的差错控制。
² 传输过程中如有网络出现异常或其他异常情况导出数据不能正常上传至系统，数据提供方能够自动进行续传或补齐丢失数据的功能。
数据接口处理过程：
² 数据接收方在接收数据之前对数据提供方进行安全验证。
² 数据接收方接收数据或文件，并校验是否成功获取；
² 若成功，则对数据包或文件名进行标识并存放在相应数据库或目录；
² 若失败，则对数据包或文件名进行读取失败标识，存放在相应数据库或目录，并通知相关系统及时处理故障，协商重传时间。
2.4.7编码原则
1. 对所有交互对象及对象属性统一命名
2. 方法、参数名称采用首字母小写，后面每个单词首字母大写的形式，缩写为1-3个字母的参考第一个规则（如getUserID、getUserName）
2.4.8接口的验证方式
为了保证能源数据的准确性，必须对数据提供方与数据接收方之间的数据接口进行验证，接口数据的验证由接口双方共同负责。
u 实时验证：每次数据提供方调用数据接收方接口进行数据交互时，对交互的数据进行验证。
² 验证方法
u 数据提供方在上报数据前根据报表数据要求和接口数据要求对上报数据进行初步校验。
u 数据接收方在接收到上报数据后对数据格式、数据长度、数据的完整性进行校验。
2.4.9使用策略
² 调用时间定于规定上报期内的任何时段，能耗实时数据根据数据接收方的频率进行上传
² 调用频率根据实际上报要求可以多次调用，能耗实时数据根据数据接收方的频率进行多次调用
² 触发机制由数据提供方向数据源提供方推送数据
2.5接口数据的要求及保障
数据接收方在发现数据错误时，必须及时记录日志，并将校验通过的数据和校验失败的数据转存到相应字段中。需要对数据进行逻辑校验.
² 主键检查
主键唯一性校验，检查接口数据中是否违反规范定义的唯一性约束；
² 数据类型及格式检查
字段类型检查，检查各字段类型是否与规范定义一致；
² 数据值域检查
对数据的取值有效检查。
附录1 数据采集器身份认证过程和数据加密
1．身份认证过程
数据中心使用MD5算法进行数据采集器身份认证，密钥长度为128bit，具体过程如下：
（1）TCP连接建立成功后，数据采集器向数据中心发送身份认证请求；
（2）数据中心向数据采集器发送一个随机序列；
（3）数据采集器将接收到的随机序列和本地存储的认证密钥组合成一连接串，计算连接串的MD5值并发送给数据中心;
（4）数据中心将接收到的MD5值和本地计算结果相比较，如果一致则认证成功，否则认证失败。
认证密钥存储在数据中心和数据采集器的本地文件系统中，数据中心可以通过网络对数据采集器的认证密钥进行更新。
2．数据加密
使用AES加密算法对XML数据包进行加密，密钥长度为128bit。加密密钥存储在数据中心和数据采集器的本地文件系统中，数据中心可以通过网络对数据采集器的加密密钥进行更新。
附录2 数据采集器或子系统和市数据中心通信过程

附图 数据采集器或子系统和市数据中心通信过程

* 连接成功后数据采集器定时向数据中心发送心跳包以保持连接的有效性
** 数据采集根据系统配置在主动定时和被动查询模式间选择
*** 数据采集器对能耗数据的处理功能根据系统配置选择
附录3 数据传输的XML数据格式
1．身份验证数据包(id_validate)
<?xml version="1.0" encoding="utf-8" ?>
<root>
<!-- 通用部分 -->
<!--
building_id:用能单位编号
gateway_id:采集器编号
type:身份验证数据包的类型
  -->
<common>
  <building_id>XXXXXX</building_id >
  <gateway_id>XXX</gateway_id >
  <type>以下4种操作类型之一</type>
</common>
<!-- 身份验证 -->
<!-- 操作有4种类型
request:采集器请求身份验证（该数据包为采集器发送给服务器）
sequence:服务器发送一串随机序列，sequence子元素有效（该数据包为服务器发送给采集器）
md5:采集器发送计算的MD5，md5子元素有效（该数据包为采集器发送给服务器）
result:服务器发送验证结果，result子元素有效（该数据包为服务器发送给采集器）
  -->
<id_validate operation="request/sequence/md5/result">
<sequence >XXXXXXXX </sequence >
<md5>XXXXXXXX</md5>
<result >pass/fail</result >
</id_validate>
</root>

2．心跳/校时数据包(heart_beat)
<?xml version="1.0" encoding="utf-8" ?>
<root>
<!-- 通用部分 -->
<!--
building_id:用能单位编号
gateway_id:采集器编号
type:心跳/校时数据包的类型
  -->
<common>
  <building_id>XXXXXX</building_id >
  <gateway_id>XXX</gateway_id >
  <type>以下2种操作类型之一</type>
</common>
<!-- 心跳/校时 ->
<!-- 操作有2种类型
notify:采集器定期给服务器发送存活通知
time:服务器在收到存活通知后发送授时信息，此时子元素time有效
-->
<heart_beat operation="notify/time">
  <time>YYYYMMDDHHMMSS</time>
  </heart_beat>
</root>

3．能耗远传数据包(data)
<?xml version="1.0" encoding="utf-8" ?>
<root>
<!-- 通用部分 -->
<!--
building_id:用能单位编号
gateway_id:采集器编号
type:能耗远传数据包的类型
  -->
<common>
 <building_id>XXXXXX</building_id >
  <gateway_id>XXX</gateway_id >
  <type>以下5种操作类型之一</type>
</common>
<!-- 能耗远传 -->
<!-- 操作有4种类型
query:服务器查询数据采集器，不需要子元素
reply:采集器对服务器查询的应答
report:采集器定时上报的能耗数据
continuous:采集器断点续传的能耗数据
continuous_ack:全部续传数据包接收完成后，服务器对断点续传的应答，不需要子元素
元素有5种类型
sequence元素:采集器向服务器发送数据的序号
parser元素:向服务器发送的数据是否经采集器解析过
time元素:数据采集时间
total元素:断点续传时有效，表示需要断点续传数据包的总数
current元素:断点续传时有效，表示当前断点续传数据包的编号
port元素:计量装置的设备号，具有id属性
function元素:每个计量装置的具体采集功能，具有下列3种属性，
id属性:计量装置的数据采集功能编号（供多功能电能表使用）
coding属性:能耗数据分类/分项编码
error属性:该功能出现错误的状态码，0表示没有错误
-->
<data operation="query/reply/report/continuous/continuous_ack">
  <sequence>XXXXXXXX</sequence>
  <parser>yes/no</parser>
  <time> YYYYMMDDHHMMSS </time>
<total>XXX</total>
<current>XXX</current>
<meter id="1">
  <function id="1" coding="XXX" error="XXX">数据1</function>
  <function id="2" coding="XXX" error="XXX">数据2</function>
  </meter>
<meter id="2">
  <function id="1" coding="XXX" error="XXX">数据1</function>
  <function id="2" coding="XXX" error="XXX">数据2</function>
  </meter>
</data>
</root>

4．配置信息数据包(config)
<?xml version="1.0" encoding="utf-8" ?>
<root>
<!-- 通用部分 -->
<!--
building_id:用能单位编号
gateway_id:采集器编号
type:配置信息数据包的类型
  -->
<common>
 <building_id>XXXXXX</building_id >
  <gateway_id>XXX</gateway_id >
  <type>以2种操作类型之一</type>
</common>
<!-- 配置信息 -->
<!--操作有2种类型
period:表示服务器对采集器采集周期的配置,period子元素有效
period_ack:表示采集器对服务器采集周期配置信息的应答
  -->
<config operation="period/period_ack">
  <period>15</period>
  </config>
  </root>