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

智能网管系统与其他系统间接口规范
文档编写：张志洋
提交日期： 2010-08-29
版本号： 1.06
北邮项目组
2010-08-29
文档修改记录
1 概述 (5)
2 接口协议结构设计 (5)
2.1 模式 (5)
2.1.1 request/response模式 (5)
2.1.2 notification/ack模式 (6)
2.1.3 one-way notification模式 (6)
2.2 参数数据部分 (7)
2.3 数据内容部分 (7)
2.3.1 复杂消息内容 (7)
2.3.2 简单消息内容 (8)
2.4 数据类型 (10)
2.5 命名规则 (10)
2.6 数据流终结符说明 (11)
2.7 协议 (11)
2.8 协议安全机制 (12)
2.8.1 request/response安全机制 (12)
2.8.2 notification/ack安全机制 (12)
2.8.3 one-way安全机制 (13)
2.9 通用消息定义 (13)
2.9.1 消息说明 (13)
2.9.2 登录（login） (13)
2.9.3 退出（logout） (15)
3 系统间接口数据内容的定义 (16)
3.1 充电监控 (16)
3.1.1 系统同步 (16)
3.1.2 充电记录 (17)
3.1.3 电池系统实时信息 (18)
3.1.4 电池系统详细充电性能参数 (19)
3.1.5 充电机配置信息 (20)
3.1.6 充电桩配置信息 (21)
3.1.7 充电机实时信息 (22)
3.1.8 充电桩实时信息 (23)
3.1.9 协议网关配置信息 (24)
3.1.10 协议网关实时信息 (25)
3.1.11 充电终端配置信息 (26)
3.1.12 充电终端实时信息 (27)
3.1.13 储位实时状态信息同步 (28)
3.2 快换系统 (28)
3.2.1 系统同步 (29)
3.2.2 快换装置配置信息 (29)
3.2.3 快换装置实时状态信息同步 (30)
3.2.4 工位配置信息同步 (31)
3.2.5 工位实时状态信息同步 (32)
3.3 电池存取输送系统 (33)
3.3.1 系统同步 (33)
3.3.2 电池架配置信息同步 (34)
3.3.3 储位配置信息同步 (35)
3.3.4 换电记录同步 (36)
3.3.5 电池的出入库信息通知 (37)
3.3.6 传输线配置信息同步 (37)
3.3.7 智能存取车配置信息同步 (38)
3.3.8 传输线实时状态信息同步 (39)
3.3.9 智能存取车实时状态信息同步 (40)
3.3.10 储位实时状态信息同步 (41)
3.4 GIS系统 (42)
3.4.1 系统同步 (42)
3.4.2 电池性能信息同步 (43)
3.4.3 换电信息同步 (44)
3.4.4 电池告警信息同步 (45)
3.4.5 站点资源查询 (45)
3.4.6 站点基础信息同步 (46)
3.4.7 车牌号码资源 (47)
3.5 认证计费 (48)
3.5.1 系统同步 (48)
3.5.2 电池系统型与车辆型对应表 (49)
3.5.3 流水交易记录 (50)
3.5.4 电池认证信息 (51)
3.5.5 计费策略 (52)
3.5.6 卡号黑名单 (53)
3.5.7 车卡信息 (54)
3.5.8 电池信息 (55)
3.6 客服系统 (55)
3.6.1 系统同步 (56)
3.6.2 电池信息 (56)
3.6.3 车辆型号 (57)
3.6.4 车辆信息 (58)
3.6.5 客户信息 (59)
3.6.6 客服工单 (61)
3.7 一卡通系统 (62)
1概述
普天海油项目，主要包括BOSS系统、网管系统、GIS系统、一卡通系统、计费认证系统、客服系统、充电监控系统、快换系统以及电池存取输送系统。

本文档主要描述了BOSS系统和网管系统与其它各系统之间的接口规范及接口内容定义。

2接口协议结构设计
2.1模式
通信有三种模式：
1、request/response模式
在这种模式下，请求方先发送一个请求（request），应答方返回一个应答（response）2、notification/ack模式
在这种模式下，通知方主动向响应方推送一个通知（notificaition），响应方收到通知之后，给出一个响应（ack）
3、oneway模式
在这种模式下，数据发送方主动向数据接收方推送一个消息，接收方不需要有任何回应。

2.1.1request/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.2notification/ack模式
notification消息
token为可选属性，目的是为了强化安全机制，详见2.7协议安全机制。

ack消息
2.1.3one-way notification模式
one-way消息
说明：
token为可选属性，目的是为了强化安全机制，详见2.7协议安全机制。

2.2参数数据部分
参数数据部分表示request消息的参数。

具体形式为：
说明：
1、count表示参数的数量
2、yyy1表示参数的名称，zzz1表示参数的值。

以此类推。

3、request是login与logout时，格式固定，参看2.7.2和2.7.3
2.3数据内容部分
2.3.1复杂消息内容
复杂消息内容用于组织response数据反馈、notification消息、oneway消息的内容。

具体形式如下：
1、节点<content>有两种子节点：<summary>子节点、<data>子节点。

2、<summary>节点包含<count>、<finished>、<attributes>子节点。

<attributes>节点包含
<attribute>节点。

3、<attributes>节点的属性字段number表示属性的个数（<data>下级节点的数目）。

<count>
节点的数据表示<data>节点的个数。

4、<finished>节点的数据表示一个消息是否完整。

其值为true表示消息内容完整，无后续
消息，此时<finished节点可缺省>。

如果值为false，表示后续还有消息，作为该消息内容的补充。

5、<attributes>的数据表示传输数据的全部属性字段和类型。

<attribute>节点包括：<name>
节点，节点的值表示字段属性名称；<type>节点，节点值表示字段的类型。

DDD1、...、DDDn即为属性名称。

6、<data>下级节点包括：< DDD1>、...、<DDDn>。

7、< DDD1>、…、<DDDn>等节点的值为DDD1、…、DDDn属性的值
8、一个数据在<data>元素中包含。

9、<data>的serialno表示一个编号，<data>的最后一个编号与节点<count>值对应
2.3.2简单消息内容
2.3.2.1r equest/resposne成功消息：
2.3.2.2r equest/response失败消息：
2.3.2.3r equest/response的零回答消息
在服务器中没有客户所要求的数据，可以采用零回答消息
2.3.2.4n otification/ack成功消息：
第3部分系统间接口数据内容的定义中的notification/ack消息，ack部分result为1时采用此种简单消息。

2.3.2.5n otification/ack失败消息：
采用此种简单消息。

2.4数据类型
目前支持的数据类型有：
可以包含hibernate所支持的其他数据类型。

2.5命名规则
参数部分命名规则采用驼峰命名规则，例如：batteryId，startTime。

请求或通知名称的命名包括三部分内容，内容之间采用下划线“_”分割，形如A_B_C，
例如：BS_R_chargeRecords，CK_N_bsRealtimeInfo。

发起端命名表：
2.6数据流终结符说明
不同系统之间传输的协议内容，均是先转换为比特流的形式，再进行传输、接收及处理。

为了方便消息的传输以及增加接口的实用性。

在此约定在所有的传输消息结束均加一位ASCII码“0”作为终结符，标识流结束。

2.7协议
下层传输协议，可以采用下列方式：
1、tcp/ip
2、http+post
2.8协议安全机制
为了保证通信过程中数据的安全，约定以token为核心的安全机制。

2.8.1request/response安全机制
若通信一方需向另一方请求数据，则该方需要先请求登录，另一方返回reponse后，在response的数据内容部分包含token的信息作为数据请求方的安全标识。

request 的token安全机制的约定：
1、用户登录后可重新登录
2、同一个IP地址可以多个用户同时登录
3、用户退出登录时必须在退出的request请求中带token
4、非登录request消息，必须带有合法token，否则接收方不予以处理
5、token的有效期规定：若用户在有效期内未发出新的request，则用户在超过有效期后，再发送request，则返回其token超时的提醒；token具有延续时间功能，若用户在有效期内发出request，则token延长一个有效期
以下是请求登录的request，用于request的安全机制：
2.8.2notification/ack安全机制
notification的安全级别分两级：一种为，无验证机制；另一种为，需notification token 安全机制验证；token为notification可选字段，需要根据消息内容对notification的安全级别做界定。

notification带token安全机制的约定：
1、notification消息需要为含token安全机制的消息
2、此时token为必填字段
3、用户需要提前发出登录的request信息获得token，才可以发送notification
4、若通信一方向另一方发送了一条无token验证信息的notification，则返回ack给出提示。

5、token的有效期规定参照2.7.1。

以下是请求登录的request，用于notification/ack的安全机制：
2.8.3one-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的安全机制：
2.9通用消息定义
2.9.1消息说明
该request/response模式的消息为通用的消息模式定义，旨在完成用户信息的验证，验证通过后将给用户下发有一定时限的令牌，表示验证通过。

2.9.2登录（login）
登录请求
登录响应1：正确响应
登录响应2：错误响应
表3-1登录字段说明及错误信息2.9.3退出（logout）
退出请求
退出响应1：正确响应
退登出响应2：错误响应
3系统间接口数据内容的定义
3.1充电监控
3.1.1系统同步
3.1.1.1接口描述
3.1.1.2通知参数
3.1.1.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.1.2充电记录3.1.2.1接口描述
3.1.2.2请求参数
3.1.2.3响应参数
3.1.3电池系统实时信息3.1.3.1接口描述
3.1.3.2通知参数
3.1.3.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.1.4电池系统详细充电性能参数
3.1.
4.1接口描述
3.1.
4.2请求参数
应答参数
3.1.
4.3
3.1.5
充电机配置信息
3.1.5.1 接口描述
3.1.5.2 请求参数
3.1.5.3应答参数
3.1.6充电桩配置信息3.1.6.1接口描述
3.1.6.2请求参数
3.1.6.3响应参数
3.1.7充电机实时信息3.1.7.1接口描述
3.1.7.2通知参数
3.1.7.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.1.8充电桩实时信息
3.1.8.1接口描述
3.1.8.2通知参数
3.1.8.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.1.9协议网关配置信息
3.1.9.1接口描述
3.1.9.2请求参数
3.1.9.3响应参数
3.1.10协议网关实时信息3.1.10.1接口描述
3.1.10.2通知参数
3.1.10.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.1.11充电终端配置信息
3.1.11.1接口描述
3.1.11.2请求参数
3.1.11.3应答参数
3.1.12充电终端实时信息
3.1.12.1接口描述
3.1.12.2通知参数
3.1.12.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，
notification/ack失败消息。

3.1.13储位实时状态信息同步
3.1.13.1接口描述
3.1.13.2通知参数
3.1.13.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.2快换系统
3.2.1系统同步
3.2.1.1接口描述
3.2.1.2通知参数
3.2.1.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.2.2快换装置配置信息
3.2.2.1接口描述
3.2.2.2请求参数
3.2.2.3响应参数
3.2.3快换装置实时状态信息同步3.2.3.1接口描述
3.2.3.2通知参数
3.2.3.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.2.4工位配置信息同步
3.2.
4.1接口描述
3.2.
4.2请求参数
3.2.
4.3应答参数
3.2.5工位实时状态信息同步3.2.5.1接口描述
3.2.5.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.3电池存取输送系统
3.3.1系统同步
3.3.1.1接口描述
3.3.1.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.3.2电池架配置信息同步
3.3.2.1接口描述
3.3.2.2请求参数
3.3.3储位配置信息同步3.3.3.1接口描述
3.3.3.2请求参数
3.3.3.3应答参数
3.3.4换电记录同步3.3.
4.1接口描述
3.3.
4.2请求参数
3.3.
4.3应答参数
3.3.5电池的出入库信息通知
3.3.5.1接口描述
3.3.5.2通知参数
3.3.5.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.3.6传输线配置信息同步
3.3.6.1接口描述
3.3.6.2请求参数
3.3.6.3应答参数
3.3.7智能存取车配置信息同步3.3.7.1接口描述
3.3.7.2请求参数
3.3.7.3应答参数
3.3.8传输线实时状态信息同步3.3.8.1接口描述
3.3.8.2通知参数
3.3.8.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.3.9智能存取车实时状态信息同步
3.3.9.1接口描述
3.3.9.2通知参数
3.3.9.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.3.10储位实时状态信息同步
3.3.10.1接口描述
3.3.10.2通知参数
3.3.10.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.4GIS系统
3.4.1系统同步
3.4.1.1接口描述
3.4.1.2通知参数
3.4.1.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.4.2电池性能信息同步3.4.2.1接口描述
3.4.2.2请求参数
3.4.2.3应答参数
3.4.3换电信息同步
3.4.3.1接口描述
3.4.3.2通知参数
3.4.3.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.4.4电池告警信息同步
3.4.4.1接口描述
3.4.4.2通知参数
3.4.4.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.4.5站点资源查询
3.4.5.1接口描述
3.4.5.2请求参数
3.4.5.3响应参数
3.4.6站点基础信息同步3.4.6.1接口描述
3.4.6.2请求参数
3.4.6.3应答参数
3.4.7车牌号码资源3.4.7.1接口描述
3.4.7.2请求参数
3.4.7.3应答参数
3.5认证计费
3.5.1系统同步3.5.1.1接口描述
3.5.1.2通知参数
3.5.1.3响应参数
成功响应请参见 2.3.2.4，notification/ack成功消息；失败响应请参见 2.3.2.5，notification/ack失败消息。

3.5.2电池系统型与车辆型对应表
3.5.2.1接口描述
3.5.2.2请求参数
3.5.2.3应答参数
3.5.3流水交易记录3.5.3.1接口描述
3.5.3.2请求参数。