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

附件2武汉市节能智慧管理系统数据接口规范武汉市发展和改革委员会2013年12月前言为指导我市各级节能智慧管理系统建设，市发改委组织有关专家，以我国现行相关标准为依据，结合我市节能智慧管理系统建设、验收和运行管理要求，研究制定了本数据接口规范。本规范包括主要用能单位上传数据接口标准规范和市区各级系统上传数据接口标准规范两部分，其中两部分包括了接口的标准应用范围、接口的实现、接口的要求、术语和定义和基本原则。本规范由市发改委负责管理和解释。目 录1.主要用能单位上传数据接口规范21.1标准应用范围21.2术语和定义21.3基本原则21.4接口实现21.4.1数据提供方21.4.2数据接收方21.4.3接口的实现方式21.4.4传输方式21.4.5传输协议21.4.6传输过程21.4.7编码原则21.4.8接口的验证方式21.4.9使用策略21.5接口数据的要求及保障22.区分系统上传数据接口规范22.1标准应用范围22.2术语和定义22.3基本原则22.4接口实现22.4.1数据提供方22.4.2数据接收方22.4.3接口的实现方式22.4.4传输方式22.4.5传输协议22.4.6传输过程22.4.7编码原则22.4.8接口的验证方式22.4.9使用策略22.5接口数据的要求及保障2附录1 数据采集器身份认证过程和数据加密2附录2 数据采集器或子系统和市数据中心通信过程2附录3 数据传输的XML数据格式21. 主要用能单位上传数据接口规范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) XXXXXX XXX 以下4种操作类型之一 XXXXXXXX XXXXXXXXpass/fail 2心跳/校时数据包(heart_beat) XXXXXX XXX 以下2种操作类型之一 YYYYMMDDHHMMSS 3能耗远传数据包(data) XXXXXX XXX 以下5种操作类型之一 XXXXXXXX yes/no YYYYMMDDHHMMSS XXX XXX 数据1 数据2 数据1 数据2 4配置信息数据包(config) XXXXXX XXX 以2种操作类型之一 15