1、集团公司接口规范.doc

中国石油天然气集团公司矿区水电气远程集抄系统数据交换接口规范（1.0版）集团公司矿区服务工作部矿区服务业务管理信息系统项目组2008年06月1目 录第1章总则21.1远程集抄数据交换接口21.2版本号2第2章接口技术方案32.1WEB SERVICE接口说明 42.2请求消息 42.3响应消息 52.4数据架构 6第3章接口内容和协议（格式）63.1报送登录63.1.1.请求消息体63.1.2.响应消息体63.2注册计量表类型73.2.1.请求消息体字段说明73.2.2.响应消息体字段说明73.3注册和变更计量表用户信息83.3.1.请求消息体字段说明 83.3.2.响应消息体字段说明 83.4获取注册反馈 93.4.1.请求消息体 93.4.2.响应消息体 93.5报送计量信息103.5.1.请求消息体字段说明103.5.2.响应消息体字段说明10第4章附件111 总则1.1 远程集抄数据交换接口 本规范是中国石油天然气集团公司矿区服务业务管理信息系统各类数据交换接口规范的一部分，它规定了在各单位矿区水电气远程抄表集中监控系统向矿区服务业务管理信息系统报送管理数据的数据交换，具体内容包括：网络拓扑接口技术方案接口内容和协议（格式）本规范适用于中国石油天然气集团公司各单位矿区服务事业部各类远程集抄系统的供应商和开发单位。1.2 版本号集团公司矿区服务业务管理信息系统各类数据交换接口规范版本号由主版本号和小版本号两部分构成，均为两位数字。版本号内部表示为4位数字，主版本号和子版本号串接而成，首位0不可省略。在书写表示时主版本号和小版本号中间用英文点号分隔，即形如00.00的格式，两部分的首位0均可省略。当前版本是本规范的初始版本，版本号为01.00，可书写为1.0版(Ver1.0)。网络拓扑集团总部、各矿区及其下属单位的远程集抄系统根据管理需要就近部署，用于数据交换的数据收集服务器部署在集团公司指定机房，各远程集抄系统（数据报送操作的发起方）通过中国石油企业网连接中国石油矿区服务业务管理信息系统数据收集服务器（数据报送操作的接收方），按指定的接口技术方案及对应的协议（格式）报送数据。因网络覆盖原因，如有部署暂时不能直接连通中国石油企业网的地区系统，可以向相关信息管理部门申请VPN方式连接中国石油企业网报送数据。“抄表终端设备（含户表、集中器等）远程集抄系统”间的通讯网络和“数据收集服务器矿区管理系统”间的通讯网络不属于接口范畴，本规范不规定它们的网络拓扑。考虑到安全等方面的要求，远程集抄系统不得利用与数据收集服务器间的网络连接从事未经许可的、与数据报送无关的网络行为。2 接口技术方案根据接口涉及的相关技术环境和应用系统的特点，中国石油矿区服务业务管理信息系统采用基于TCP/IP网络的HTTP、SOAP、FTP、SMTP等标准协议，基于HTML、XML、Web Services或文件传输等技术路线，实现应用系统之间的数据交换。矿区服务业务管理信息系统与远程集抄系统的数据报送接口采用Web Service技术实现，基于SOAP over HTTP协议。本规范未指定Web Service的服务端点。根据最终部署情况，Web Service的服务端点由矿区服务工作部在实施期间，各远程集抄系统向矿区服务工作部或指定机构申请帐号时一并指定，不得随意更改。因部署或者网络调整发生变化时，矿区服务工作部或指定机构将通知各系统及时调整。2.1 Web Service接口说明Web Services 使用 Web Services 描述语言 (WSDL) 提供服务所支持的所有消息的详细规格。WSDL 将消息组合成操作。操作是与服务进行交互的逻辑单位，它被定义为请求消息以及与之相关的任何响应消息。本章定义了数据报送Web Service接口统一的请求消息和响应消息框架结构，在附件中提供消息内封装的相关数据架构。具体的数据报送操作和这些操作相关数据项的详细说明详见“接口内容和协议（格式）”一章。除了指定与服务相关联的操作，WSDL服务规格还记录服务的特定于通信信道的地址。附件RemoteMeterInterface.wsdl文件中的相关通信信道的地址信息并非真正的服务端点，参见本章开头的说明。本规范规定远程集抄数据交换Web Service接口各数据报送操作同步调用处理，数据报送的接收方在接收到请求操作后及时进行处理，并反馈规定的响应消息给调用方。在Web Service接口中采用加密校验信息保证数据完整，登录采用预共享密码加密校验信息，成功登录后接收方生成会话共享密码，按指定的加密算法校验数据。2.2 请求消息远程集抄数据交换Web Service接口中，所有报送操作的发起方通过向指定服务端点发送请求消息，向数据报送接收方提交数据报送操作。请求消息包括请求消息头和请求消息体两部分，如下图所示。其中，请求消息头包括请求消息序号、规范版本号、连接用户名、请求时间、请求消息体包括的数据条数、用协议指定方式生成的校验码等，参见下表。序字段名类型说明1RequestId整型请求序号。在同一会话中每次请求序号不同，随时间增长2Version4位串规范版本号。要求服务支持的规范版本号，固定为01003LoginName10位串连接用户名。报送数据的远程集抄系统的识别号，由矿区服务工作部指定4RequestTime14位串请求时间。请求发起的当前时间格式：YYYYMMDDhhmmss5DataRecordCount整型数据条数。在消息体内包含的数据条数，默认为1，1-9996VerifyCode字符串校验码。按指定校验算法提供请求消息（含消息头和消息体，不包括校验码本身）的校验码请求消息体由具体操作涉及的内容决定，详见“接口内容和协议（格式）”一章。2.3 响应消息报送操作的接收方在完整收到请求操作后及时进行处理，并反馈规定的响应消息给调用方。响应消息包括响应消息头和响应消息体两部分，如下图所示。其中，响应消息头包括响应消息序号、协议版本号、请求消息序号、响应时间、成功失败码、请求消息体包含的数据条数、响应消息体包括的数据条数、用协议指定方式生成的校验码等，参见下表。序字段名类型说明1RespRecId整型响应序号。在同一会话中每次响应序号不同，随时间增长2Version4位串规范版本号。服务支持的规范版本号，固定为01003ReqRecId整型请求序号。复制请求序号，用于标识对应请求4ResponseTime14位串响应时间。响应发起的当前时间格式：YYYYMMDDhhmmss5Flag整型成功失败码。0=成功 正数=警告 负数=失败，详参附件6RequestRecordCount整型请求数据条数。对应请求消息体内包含的数据条数，0-9997ResponseRecordCount整型响应数据条数。当前响应消息体内包含的数据条数，0-9998VerifyCode字符串校验码。按指定校验算法提供请求消息（含消息头和消息体，不包括校验码本身）的校验码响应消息体由具体操作涉及的内容决定，详见“接口内容和协议（格式）”一章。2.4 数据架构在远程集抄数据交换Web Service接口方案中，本规范参照标准定义了接口相关的数据架构，请参考规范附件RemoteMeterInterface.xsd文件。3 接口内容和协议（格式）3.1 报送登录在Web Service接口中，报送方发起建立一次数据报送会话的操作，即报送登录操作。请求消息体本规范规定Web Service接口下，在正式报送数据前，报送方建立一次数据报送的会话（即登录），从服务器取得会话共享密码，用于本次会话后续的各类数据报送操作。报送登录的请求消息体如下表所示（单条记录）。序字段名类型说明1EncyptedInfo字符串认证信息。对消息头的用户名和请求时间串接成的共24位字符串用预定共享密码按指定方式加密2ChgPwd1位数字改密码标志。1=登录成功后修改预定共享密码，0（默认）=不修改3NewShareKey字符串新共享密码。默认为空；如请求改密码，则用原来的预定共享密码按指定方式加密新的预定共享密码响应消息体数据接收服务器在接收到请求报送登录的消息后，根据登录成功与否响应消息。如登录不成功，响应消息体为空。如登录成功，响应消息体格式如下。序字段名类型说明1EncSessionCode字符串会话密码。用预定共享密码按指定方式加密，解密才能得到会话密码2NewKeyEncSessionCode字符改密码确认。默认空；改密码成功时用新的共享密码按指定方式加密会话密码，用于验证密码修改成功3.2 注册计量表类型在报送远程集抄数据计量信息以前，远程集抄系统需事先注册集抄系统用到的计量表类型。Web Service接口方法名：RegisterMeterType请求消息体字段说明出于网络传输等方面的考虑，每个注册计量表类型的请求记录条数不得超过999，每条数据记录的接口参数（记录字段）说明如下表。序字段名类型说明1ReqRecId3位整数记录顺序号。1-999当前请求体内所有请求记录的唯一标识2UsageId1位整数用途标志。1=冷水水表 2=燃气表 3=电能表3MeterTypeId2位字串表类型编码。一个集抄系统内同一用途计量表类型唯一标识4Operation1位整数注册操作。1=新增 2=修改 3=停用 4=恢复5Modulus9位整数模数。表的最大示数加上一个单位的最小可示数，即计量表走满一圈到相同数字时的用量6MultipleAble1位整数变比装置。0=无变比装置 1=可装变比装置7CheckCycle3位整数检定周期。单位：月8Life3位整数寿命。单位：月9Desc200位字串型号说明。表名称、型号、生产厂家等，由字母、数字和中文、下线、减号、斜线等字符组成响应消息体字段说明数据报送接口服务器在收到请求后，Web Service同步处理并反馈错误响应消息。如处理成功，响应消息体为空，只在响应消息头中声明成功处理。当处理全部失败时，在响应消息头中声明请求处理失败；部分失败时，在响应消息头中声明请求处理部分失败的警告。无论是失败或警告，均会在响应消息体返回处理失败的记录。在处理失败时，响应消息体的字段说明如下表，其中序号为1-4的字段值直接拷贝于请求消息体对应名称的字段值。序字段名类型说明1Id3位整数记录顺序号。1-999对应请求体内记录的唯一标识2UsageId1位整数用途标志。1=冷水水表 2=燃气表 3=电能表3MeterTypeId2位字串表类型编码。一个集抄系统内所有表类型的唯一标识4Operation1位整数注册操作。1=新增 2=修改 3=停用 4=恢复5Flag5位整数错误代码。对应错误内容详见附件，0代表处理成功3.3 注册和变更计量表用户信息在报送远程集抄数据计量信息以前，远程集抄系统需事先注册集抄系统中各用户、使用计量表号、用途等。Web Service接口方法名：RegisterMeterUsage请求消息体字段说明出于网络传输等方面的考虑，每个注册计量表类型的请求记录条数不得超过999，每条数据记录的接口参数（记录字段）说明如下表。序字段名类型说明1ReqRecId3位整数记录顺序号。1-999当前请求体内所有请求记录的唯一标识2UsageId1位整数用途标志。1=冷水水表 2=燃气表 3=电能表3MeterTypeId2位字串表类型编码。一个集抄系统内同一用途计量表类型唯一标识4Operation1位整数注册操作。1=新增 2=修改用户信息(不能改表号和用户号) 3=停用 4=恢复 5=变比系数变更5UserId30位字符用户标识号。一个集抄系统内对用户的唯一编号，同时抄收多种用途表的同一用户的标识号应一致6MeterId30位字符计量表号。出厂编号或者其他可标识唯一的编码7Multiple5位数字变比。整数或者小数，加装互感或者其他装置后计量表的变比，即实际用量是示数变化的指定倍数8CurrentValue15位数字当前示数。发生变更业务时点的计量表示数（小数）。用于记录起始读数和，对修改、停用等核对（仍需报送具体的计量信息）9RegTime14位时间注册时间。YYYYMMDDhhmmss10ProductDate8位日期出厂日期。YYYYMMDD11LastCheckDate8位日期上次检定。YYYYMMDD12MeterDesc60位字串计量表说明。计量表的特征，用于人工识读，可含出厂编号等标识信息13UserDesc200位字串用户情况。用户信息，主要是姓名（单位名称）、地址等标识性信息，用于人工识读核对用户响应消息体字段说明数据报送接口服务器在收到请求后，Web Service同步处理并反馈不能通过数据校验的错误响应消息。如处理成功，响应消息体为空，只在响应消息头中声明成功处理。当处理全部失败时，在响应消息头中声明请求处理失败；部分失败时，在响应消息头中声明请求处理部分失败的警告。无论是失败或警告，均会在响应消息体返回处理失败的记录。在处理失败时，响应消息体的字段说明如下表，其中序号为1-6的字段值直接拷贝于请求消息体对应名称的字段值。序字段名类型说明1ReqRecId3位整数记录顺序号。1-999对应请求体内记录的唯一标识2UsageId1位整数用途标志。1=冷水水表 2=燃气表 3=电能表3MeterTypeId2位字串表类型编码。一个集抄系统内同一用途计量表类型唯一标识4Operation1位整数注册操作。1=新增 2=修改信息(不能改表号和用户号) 3=停用 4=恢复5UserId30位字符用户标识号。一个集抄系统内对用户的唯一编号，同时抄收多种用途表的同一用户的标识号应一致6MeterId30位字符计量表号。出厂编号或同类型表可标识唯一的其它编码7RegTime14位时间注册时间。YYYYMMDDhhmmss8Flag5位整数错误代码。对应错误内容详见附件3.4 获取注册反馈对Web Service接口的计量表类型的注册，如果远程集抄系统需要确认矿区服务业务管理信息系统正确接收并正确处理，对于Web Service接口，调用此服务操作获取指定时间段内已经处理成功的记录。对Web Service接口的计量表用户信息注册操作，调用此服务操作获取处理时间段内的在处理期间失败和成功的记录。Web Service接口方法：GetRegisterResult注：预留接口，暂未提供。请求消息体Web Service接口的请求消息体是一个单条记录，用于传递接口调用参数，字段说明见下表。注意：所请求的反馈数据在一个响应消息体提供，为避免过长的网络传输带来的不可靠，请求的时间段不要太大。序字段名类型说明1RegType1位数字待取类型。0=所有 1=计量表类型注册 2=计量表用户信息2UsageId1位数字用途标志。0=所有 1=冷水水表 2=燃气表 3=电能表3Flag1位数字成功失败。0=所有 1=只取失败记录 2=只取成功记录4StartDate8位日期开始日期。YYYYMMDD5EndDate8位日期结束日期。YYYYMMDD响应消息体服务器在接收到获取注册反馈的请求后，提取待获取的数据响应内容，消息体包括反馈的注册计量表反馈和计量表用户信息两个部分，即如下图所示。注册计量表和计量表用户信息反馈与响应消息体类似，由反馈的注册记录构成，详细字段说明参见前面对应章节的说明。注意其中反馈的顺序号不再是请求的顺序号，而是服务器生成的反馈顺序记录号。3.5 报送计量信息数据报送接口中调用最频繁的操作，远程集抄系统根据矿区服务工作部规定的频度定期报送采集到的计量表读数和计量信息。Web Service接口方法名：RemoteMeterData请求消息体字段说明出于网络传输等方面的考虑，每个计量信息报送的请求记录条数不得超过999，每条数据记录的接口参数（记录字段）说明如下表。序字段名类型说明1ReqRecId3位整数记录顺序号。1-999当前请求体内所有请求记录的唯一标识2UsageId1位整数用途标志。1=冷水水表 2=燃气表 3=电能表3MeterTypeId2位字串表类型编码。一个集抄系统内同一用途计量表类型唯一标识4UserId30位字符用户标识号。一个集抄系统内用户的唯一编号，同时抄收多种用途表的同一用户的标识号应一致5MeterId30位字符计量表号。出厂编号或同类型表可标识唯一的其它编码6ReadTime14位时间读表时间。YYYYMMDDhhmmss7CurrentValue15位数字当前示数。发生变更业务时点的