智能网管系统与其它系统接口规范.doc

智能网管系统与其他系统间接口规范 文档编写： 张志洋 提交日期： 2010-08-29 版本号 ： 1.06 北邮项目组2010-08-29文档修改记录撰写人修改时间原版本号修改内容介绍张志洋7月28日1.00接口协议部分与现阶段工作进行同步，部分错误修改。张志洋7月29日1.01修改复杂消息内容data元素内的命名，对某些细节进行修改，客服部分增加与BOSS的接口张志洋8月1日1.02根据普天意见对客服部分删除部分数据张志洋8月5日1.03根据普天的修改意见对计费认证及GIS相关进行修改张志洋、谭贺春8月12日1.04加入2.7协议安全机制，修改部分不符合javabean规范的参数张志洋8月28日1.05将原版本中notification/ack模式的响应参数部分与实际使用情况对应；修改了2.1模式中部分表达不明确的地方。1概述52接口协议结构设计62.1模式62.1.1request/response模式62.1.2notification/ack模式72.1.3one-way notification模式72.2参数数据部分72.3数据内容部分82.3.1复杂消息内容82.3.2简单消息内容92.4数据类型102.5命名规则112.6数据流终结符说明122.7协议122.8协议安全机制122.8.1request/response安全机制132.8.2notification/ack安全机制132.8.3one-way安全机制142.9通用消息定义142.9.1消息说明142.9.2登录（login）142.9.3退出（logout）163系统间接口数据内容的定义173.1充电监控173.1.1系统同步173.1.2充电记录183.1.3电池系统实时信息193.1.4电池系统详细充电性能参数203.1.5充电机配置信息213.1.6充电桩配置信息223.1.7充电机实时信息233.1.8充电桩实时信息243.1.9协议网关配置信息253.1.10协议网关实时信息263.1.11充电终端配置信息273.1.12充电终端实时信息283.1.13储位实时状态信息同步293.2快换系统293.2.1系统同步303.2.2快换装置配置信息303.2.3快换装置实时状态信息同步313.2.4工位配置信息同步323.2.5工位实时状态信息同步333.3电池存取输送系统343.3.1系统同步343.3.2电池架配置信息同步353.3.3储位配置信息同步363.3.4换电记录同步373.3.5电池的出入库信息通知383.3.6传输线配置信息同步383.3.7智能存取车配置信息同步393.3.8传输线实时状态信息同步403.3.9智能存取车实时状态信息同步413.3.10储位实时状态信息同步423.4GIS系统433.4.1系统同步433.4.2电池性能信息同步443.4.3换电信息同步453.4.4电池告警信息同步463.4.5站点资源查询463.4.6站点基础信息同步473.4.7车牌号码资源483.5认证计费493.5.1系统同步493.5.2电池系统型与车辆型对应表503.5.3流水交易记录513.5.4电池认证信息523.5.5计费策略533.5.6卡号黑名单543.5.7车卡信息553.5.8电池信息563.6客服系统563.6.1系统同步573.6.2电池信息573.6.3车辆型号583.6.4车辆信息593.6.5客户信息603.6.6客服工单623.7一卡通系统631 概述普天海油项目，主要包括BOSS系统、网管系统、GIS系统、一卡通系统、计费认证系统、客服系统、充电监控系统、快换系统以及电池存取输送系统。本文档主要描述了BOSS系统和网管系统与其它各系统之间的接口规范及接口内容定义。2 接口协议结构设计2.1 模式通信有三种模式：1、 request/response模式在这种模式下，请求方先发送一个请求（request），应答方返回一个应答（response）2、 notification/ack模式在这种模式下，通知方主动向响应方推送一个通知（notificaition），响应方收到通知之后，给出一个响应（ack）3、 oneway模式在这种模式下，数据发送方主动向数据接收方推送一个消息，接收方不需要有任何回应。2.1.1 request/response模式request方式 参数数据部分reponse部分 数据内容部分说明：1、 request有三个参数，id表示每个消息的序列号码，每个都不相同，name表示消息的名字。不同的消息名字表示消息的类型，token用户安全论证机制。2、 每个request可以包含一些请求的参数。具体的参数内容存放在parameters元素之内。3、 在客户端向服务器端发出请求之前，需要进行登录。登录时需要输入用户名和密码。登录成功之后，服务器端返回给客户端一个token值。该token值用于后续的请求申请。如果该token值在30s内没有使用，该token失效。客户端必须重新登录以获得新的token值才能够进行新的请求申请。4、 reponse有两个个参数。replyId的属性值表示该消息对对哪个请求的回答。type表示该应答是成功应答、失败应答还是零应答。5、 本消息模式不包括登录请求token的request/response格式的定义，登录请求的request/response的格式，参见2.7协议安全机制。2.1.2 notification/ack模式notification消息 数据内容部分（复杂数据内容）说明： token为可选属性，目的是为了强化安全机制，详见2.7协议安全机制。ack消息数据内容部分（简单消息内容） 2.1.3 one-way notification模式one-way消息 数据内容部分说明： token为可选属性，目的是为了强化安全机制，详见2.7协议安全机制。2.2 参数数据部分参数数据部分表示request消息的参数。具体形式为： zzz1 . zzzn说明：1、 count表示参数的数量2、 yyy1表示参数的名称，zzz1表示参数的值。以此类推。3、 request是login与logout时，格式固定，参看2.7.2和 数据内容部分2.3.1 复杂消息内容复杂消息内容用于组织response数据反馈、notification消息、oneway消息的内容。具体形式如下： k true DDD1 type1 . DDDn typen EEE1 EEE2. EEEn . EEE1 EEE2. EEEn 说明：1、 节点有两种子节点： 子节点、子节点。2、 节点包含、子节点。节点包含节点。3、 节点的属性字段number表示属性的个数（下级节点的数目）。节点的数据表示节点的个数。4、 节点的数据表示一个消息是否完整。其值为true表示消息内容完整，无后续消息，此时。如果值为false，表示后续还有消息，作为该消息内容的补充。5、 的数据表示传输数据的全部属性字段和类型。节点包括：节点，节点的值表示字段属性名称；节点，节点值表示字段的类型。DDD1、.、DDDn即为属性名称。6、 下级节点包括： 、.、。7、 、等节点的值为DDD1、DDDn属性的值8、 一个数据在元素中包含。9、 的serialno表示一个编号，的最后一个编号与节点值对应2.3.2 简单消息内容 request/resposne成功消息： request/response失败消息： xxx1 xxx request/response的零回答消息在服务器中没有客户所要求的数据，可以采用零回答消息 notification/ack成功消息：第3部分系统间接口数据内容的定义中的notification/ack消息，ack部分result为1时采用此种简单消息。 notification/ack失败消息： xxx1 xxx2第3部分系统间接口数据内容的定义中的notification/ack消息，ack部分result为0时采用此种简单消息。2.4 数据类型目前支持的数据类型有：类型名称解释示例string字符串数据类型，字符串空是在有限的字符序列Hello，linmingboolean布尔，二进制值逻辑的数学概念FalsedecimalDecimal 变量存储为 96 位（12 个字节）无符号的整型形式，并除以一个 10 的幂数。10000float浮点数，是IEEE规定的单精度32位浮点型1.25doubleIEEE规定的双精度64位浮点型1267.43233E12duration一个时间期限1696-09-01T00:00:00Z1697-02-01T00:00:00ZdateTime日期时间，是由年、月、日、小时、分钟、秒等属性组成2002-10-10T12:00:00Ztime时间13:20:00date日期格式2002-10-09base64Binary代表Base64编码的任意的二进制数据。B64S := B64 #x20?anyURI是一个统一资源标识符（URI）。/ 可以包含hibernate所支持的其他数据类型。2.5 命名规则参数部分命名规则采用驼峰命名规则，例如：batteryId，startTime。请求或通知名称的命名包括三部分内容，内容之间采用下划线“_”分割，形如A_B_C， 参数解释A消息发起方名称，具体消息发起方名称定义参见发起端命名表B消息类型定义：可以为N、R或者O，分别表示notification、request或者onewayC接口名称例如：BS_R_chargeRecords，CK_N_bsRealtimeInfo。发起端命名表：序号系统生产厂家缩写代码1.BMS清华BM2.车载终端银通CZ3.车载GPS上海普天CG4.整车控制器清源ZC5.快换控制器科易动力KH6.地面快换设备科易动力DM7.充电桩北交大CD8.充电机北交大CJ9.协议转换板北交大XY10.充电监控北交大CK11.刷卡终端银通SK12.计费认证银通JF13.电池输送普天物流DC14.GIS上海普天GI15.客服上海普天邮通KF16.BOSS北邮BS17.网管北邮WG18.一卡通银通YK19.电表银通DB2.6 数据流终结符说明不同系统之间传输的协议内容，均是先转换为比特流的形式，再进行传输、接收及处理。为了方便消息的传输以及增加接口的实用性。在此约定在所有的传输消息结束均加一位ASCII码“0”作为终结符，标识流结束。2.7 协议下层传输协议，可以采用下列方式：1、 tcp/ip2、 http+post2.8 协议安全机制 为了保证通信过程中数据的安全，约定以token为核心的安全机制。2.8.1 request/response安全机制若通信一方需向另一方请求数据，则该方需要先请求登录，另一方返回reponse后，在response的数据内容部分包含token的信息作为数据请求方的安全标识。request 的token安全机制的约定：1、用户登录后可重新登录2、同一个IP地址可以多个用户同时登录3、用户退出登录时必须在退出的request请求中带token4、非登录request消息，必须带有合法token，否则接收方不予以处理5、token的有效期规定：若用户在有效期内未发出新的request，则用户在超过有效期后，再发送request，则返回其token超时的提醒；token具有延续时间功能，若用户在有效期内发出request，则token延长一个有效期以下是请求登录的request，用于request的安全机制： xxx1 yyy1 2.8.2 notification/ack安全机制 notification的安全级别分两级：一种为，无验证机制；另一种为，需notification token安全机制验证；token为notification可选字段，需要根据消息内容对notification的安全级别做界定。notification带token安全机制的约定：1、 notification消息需要为含token安全机制的消息2、 此时token为必填字段3、 用户需要提前发出登录的request信息获得token，才可以发送notification4、 若通信一方向另一方发送了一条无token验证信息的notification，则返回ack给出提示。5、 token的有效期规定参照2.7.1。以下是请求登录的request，用于notification/ack的安全机制：xxx1yyy12.8.3 one-way安全机制one-way的安全级别分两级，具体约定见notification/ack安全机制, one-way的安全级别需通信双方提前约定,token是one-way的可选字段。one-way的token安全机制的约定：1、若通信一方向另一方发送了一条无token验证信息的one-way，若该one-way的安全级别为带token安全级别，则另一方丢弃该消息，不做任何处理2、若one-way的安全级别为带token安全级别，则用户需要先发出登录的request信息。具体约定同request 的token安全机制的约定。以下为请求登录的request，用于one-way的安全机制： xxx1 yyy1 2.9 通用消息定义2.9.1 消息说明该request/response模式的消息为通用的消息模式定义，旨在完成用户信息的验证，验证通过后将给用户下发有一定时限的令牌，表示验证通过。2.9.2 登录（login）登录请求 xxx1 yyy1 登录响应1：正确响应 1true token string xxx1 登录响应2：错误响应 xxx1 xxx2字段说明项目参数解释详细解释其他namelogin登录消息parametersusername用户名password密码attributestoken返回的令牌,表示登录成功。类型为string一个令牌可以在系统中存活20秒。如果一个连接在20秒内不发出新的请求，就必须重新登录错误响应login_001登录用户名和密码不匹配login_002消息令牌不正确，需要重新登录login_003该用户的权限不够，服务器拒绝请求login_004该请求的服务时间不正确,token已过期,需要重新登录表3-1登录字段说明及错误信息2.9.3 退出（logout）退出请求退出响应1：正确响应退登出响应2：错误响应 xxx1 xxx23 系统间接口数据内容的定义3.1 充电监控3.1.1 系统同步 接口描述接口名称系统同步接口描述系统间状态同步接口类型notification/ack通知名称WG_N_isExist通知方网管系统响应方充电监控系统 应用场景网管系统重启或定时通过该接口与充电监控系统进行同步，以确认系统间是否连接正常。备注 通知参数字段含义类型长度必填参考existedTime通知时系统时间string14myyyyMMddhhmmss 响应参数成功响应请参见，notification/ack成功消息；失败响应请参见，notification/ack失败消息。3.1.2 充电记录 接口描述接口名称充电记录接口描述充电机或充电桩上的电池充电记录接口类型request/response请求名称BS_R_chargeRecords请求方BOSS系统应答方充电监控系统 应用场景BOSS系统从充电监控系统中批量取回充电记录备注 请求参数字段含义类型长度必填参考startTime请求充电结束时间范围的起点string14myyyyMMddhhmmssendTime请求充电结束时间范围的终点 string14myyyyMMddhhmmss 响应参数字段含义类型长度必填参考batteryId电池id编号string8mstartTime开始充电时间string14myyyyMMddhhmmssendTime结束充电时间string14myyyyMMddhhmmsschargeType充电类型string1 m1、充电桩充电2、充电机充电eiId充电设备idstring待定m待定degree充电度数float 8m345.55kwhbcSoc充电前socfloat8m soc为剩余电量百分比 接口数据传输时不传输百分号acSoc充电后soc float8m66.5%3.1.3 电池系统实时信息 接口描述接口名称电池系统实时信息接口描述当电池系统在电池架上的实时信息接口类型notification/ack通知名称CK_N_bsRealtimeInfo通知方充电监控系统 响应方网管系统应用场景网管系统需要周期性获取电池系统的实时状态备注 通知参数字段含义类型长度必填参考bsId电池idstring8mbsState电池状态string1m1、已充满；2、正在充；3、待充 4、故障bsError电池故障原因string8c故障原因代码待定stationId所在站点编号string8mstorageId电池架储位编号string8m电池架储位编号第一个字节表示的是电池架编号bsVoltage 当前电压float8mbsCurrent 当前电流float8mbsSoc当前socfloat8m34.5%time时间string14myyyyMMddhhmmsshighTemperature最高温度float8mlowTemperature最低温度float8m 响应参数成功响应请参见，notification/ack成功消息；失败响应请参见，notification/ack失败消息。3.1.4 电池系统详细充电性能参数 接口描述接口名称电池系统详细充电性能参数接口描述电池在充电时由充电监控系统记录详细的性能参数接口类型request/response 请求名称WG_R_bsChargeParam请求方网管系统应答方充电监控系统 应用场景网管系统定时发出请求备注 请求参数字段含义类型长度必填参考startTime请求获取范围时间内充电性能信息的时间起点string14myyyyMMddhhmmssendTime请求获取范围时间内充电性能信息的时间终点 string14myyyyMMddhhmmss 应答参数字段含义类型长度必填参考bsId电池idstring8mbsVoltage 当前电压float8m3211伏特bsCurrent 当前电流float8m123.456安培bsSoc当前socfloat8m34.5%bsSoe剩余能量string16obsSoh健康度string16otime时间string14myyyyMMddhhmmssunitVoltage单体电压string2048*2m3212毫伏，系统限制最多记录2048个单体电池电压值（按顺序）pointTemperature采集点温度string1024m单位为0.1度，10即为1度。3.1.5 充电机配置信息 接口描述接口名称充电机信息接口描述充电机配置信息接口类型request/response 请求名称WG_R_cmInfo请求方网管系统应答方充电监控系统 应用场景网管系统定时发出请求更新配置信息备注 请求参数字段含义类型长度必填参考startTime请求获取范围时间内更改的配置信息的时间起点string14myyyyMMddhhmmssendTime请求获取范围时间内更改的配置信息的时间终点string14myyyyMMddhhmmss 应答参数字段含义类型长度必填参考cmId充电机编号string8mstationId所在站点编号string8mcmType充电机型号string8mcmRatingPower额定输出功率float8m123.4kwcmMaxPower最大输出功率float8m123.4kwcmMaxCurrent最大输出电流float8m123.456acmMaxVoltage最大输出电压float8m123.6vtime配置时间string14myyyyMMddhhmmssavailable该记录是否被删除string1m0 已删除 1 有效positionId电池架储位编号string8m3.1.6 充电桩配置信息 接口描述接口名称充电桩信息接口描述充电桩配置信息接口类型request/response 请求名称WG_R_cpInfo请求方网管系统应答方充电监控系统 应用场景网管系统定时发出请求更新配置信息备注 请求参数字段含义类型长度必填参考startTime请求获取范围时间内更改的配置信息的时间起点string14myyyyMMddhhmmssendTime请求获取范围时间内更改的配置信息的时间终点string14myyyyMMddhhmmss 响应参数字段含义类型长度必填参考cpId充电桩编号string8mstationId所在充电桩集群或站点编号string8mcpPower最大输出功率float8mposNumpos机终端号string6mcpRatingPower额定输出功率float8mcpMaxCurrent最大输出电流float8mcpMaxVoltage最大输出电压float8mtime配置时间string14myyyyMMddhhmmssavailable该记录是否已删除string1m0 已删除 1 有效3.1.7 充电机实时信息 接口描述接口名称充电机实时信息接口描述网管系统需要监管充电机运行的实时信息接口类型notification/ack通知名称CK_N_cmRealtimeInfo通知方充电监控系统 响应方网管系统应用场景网管系统需要获取充电机的实时信息,以进行管理备注 通知参数字段含义类型长度必填参考cmId充电机编号string8mstorageId充电机所在站点idstring8mcmState充电机状态string1m1、充电2、空闲3、故障cmError充电机故障原因string4c故障原因代码待定errorTime故障时间string14cyyyyMMddhhmmsserrorPosition故障位置string4c故障位置代码待定voltage充电机充电时的电压float8c10.5vcurrent充电机充电时的电流float 8c 3.5ainputVoltage输入电压float8o123.4vinputCurrent输入电流float8o123.456ainputEquantity本次已充入电量float8o1234.5c 响应参数成功响应请参见，notification/ack成功消息；失败响应请参见，notification/ack失败消息。3.1.8 充电桩实时信息 接口描述接口名称充电桩实时信息接口描述充电桩运行的实时信息接口类型notification/ack通知名称CK_N_cpRealtimeInfo通知方充电监控系统 响应方网管系统应用场景充电监控系统在充电桩状态改变时主动通知网管系统充电桩的实时状态,以进行管理备注 通知参数字段含义类型长度必填参考cpId充电桩编号string8mstorageId充电桩所在站点idstring8mcpState充电桩状态string1m1、充电2、空闲3、故障cpError充电桩故障原因string4c故障原因代码待定errorTime故障时间string14cyyyyMMddhhmmsserrorPosition故障位置string4c故障位置代码待定voltage充电桩充电时的电压float8c10.5current充电桩充电时的电流float 8c 3.5inputColtage输入电压float8minputCurrent输入电流float8minputEquantity本次已充入电量float8o1234.5c 响应参数成功响应请参见，notification/ack成功消息；失败响应请参见，notification/ack失败消息。3.1.9 协议网关配置信息 接口描述接口名称充电协议网关信息接口描述协议网关配置信息接口类型request/response 请求名称WG_R_pgInfo请求方网管系统响应方充电监控系统 应用场景网管系统定时发出请求更新配置信息备注 请求参数字段含义类型长度必填参考startTime请求获取范围时间内更改的配置信息的时间起点string14myyyyMMddhhmmssendTime请求获取范围时间内更改的配置信息的时间终点string14myyyyMMddhhmmss 响应参数字段含义类型长度必填参考pgId协议网关编号string8mtype类型string8m与若干协议版本对应time配置时间string14myyyyMMddhhmmssavailable该记录是否已删除string1m0 已删除 1 有效3.1.10 协议网关实时信息 接口描述接口名称协议网关实时信息接口描述网管系统需要监管协议网关运行时的告警信息接口类型notification/ack通知名称CK_N_pgRealtimeInfo通知方充电监控系统 响应方网管系统应用场景充电监控系统在协议网关状态改变时主动通知网管系统协议网关的实时状态,以进行管理备注 通知参数字段含义类型长度必填参考pgId协议网关编号string8mpgState协议网关状态string1m1、正常2、故障pgError协议网关故障原因string4c故障原因代码待定errorTime故障时间string14cyyyyMMddhhmmsserrorPosition故障位置string4c故障位置代码待定 响应参数成功响应请参见，notification/ack成功消息；失败响应请参见，notification/ack失败消息。3.1.11 充电终端配置信息 接口描述接口名称充电终端信息接口描述充电终端配置信息接口类型request/response 请求名称WG_R_ctInfo请求方网管系统应答方充电监控系统 应用场景网管系统定时发出请求更新配置信息备注 请求参数字段含义类型长度必填参考startTime请求获取范围时间内更改的配置信息的时间起点string14myyyyMMddhhmmssendTime请求获取范围时间内更改的配置信息的时间终点string14myyyyMMddhhmmss 应答参数字段含义类型长度必填参考ctId充电终端编号string8mstationId所在充电桩集群或站点编号string8mctType充电终端型号string8 cpgVersion协议网关类型string4otime配置时间string14myyyyMMddhhmmssavailable该记录是否已删除string1m0 已删除 1 有效3.1.12 充电终端实时信息3.1.12