设备维护平台接口技术设计规范方案说明书0513.docx
《设备维护平台接口技术设计规范方案说明书0513.docx》由会员分享，可在线阅读，更多相关《设备维护平台接口技术设计规范方案说明书0513.docx（29页珍藏版）》请在冰点文库上搜索。
设备维护平台接口技术设计规范方案说明书0513
设备维护平台
接口技术规范说明书
（版本号V1.0）
杭州天梦科技有限公司
二◦一◦年五月
更改履历
版本号
修改编号
更改时间
更改的图表和章节
更改简要描述
更改人
批准人
V1.0
2013-05-13
创建，形成初稿
叶庆国
V1.1
2014-06-09
维修业务操作接口调整，仅开放维保单位相关操作接口
叶庆国
注：
更改人除形成初稿，以后每次修改在未批准确认前均需采用修订的方式
进行修改
1概述2
1.1编写目的2
1.2预期读者2
1.3参考文献2
2接口平台设计2
2.1技术架构2
2.1.1接口架构图2
2.1.2业务流图3
2.2部署方式4
2.3接口标准4
2.3.1技术标准4
2.3.2数据规约5
2.3.3示例6
3WEBSERVICE服务8
3.1设备维护平台提供的服务8
3.1.1接口服务清单8
3.1.2接口服务设计8
1概述
1.1编写目的
为设备维护平台的信息同步和共享，制定了统一的接口规范，用来指导各系统的接口设计、开发、联调及迁移工作。
范围：
本文档主要是对设备维护平台与外围业务系统的数据交互需求进行说明。
1.2调试要求
强烈要求第三方调用者，先做测试库的接口调试，确保接口及参数调用正确,否则将对正式库可能出现的系统故障承担主要责任。
1.3预期读者
项目组人员、各交互系统涉及到的开发厂家。
1.4参考文献
《智能交通设备维护管理系统设备接入标准》杭州天梦科技有限公司
2接口平台设计
2.1技术架构
2.1.1接口架构图
（暂缺）
2.1.2业务流图
说明：
用户通过接口。
2.2部署方式
接口服务层包括Webservice服务、展现集成服务。
1、Webservice服务
各系统提供的接口服务统一部署在设备维护平台接口服务层上，各系统客户
端和接口服务层用SOAP协议通过HTTP来交互，客户端根据WSDL描述文档生成SOAP请求消息发送到服务端，服务端解析收到的SOAP请求，调用Webservice，然后再生成相应的SOAP应答送回到客户端。
2、展现集成服务
展现集成服务主要是应用界面集成服务，由服务提供方提供详细的URL及相
关参数说明，调用方传入参数，调用服务方提供的页面进行展现。
3、平台Service组件服务
平台Service组件服务统一部署在设备维护平台接口服务层上，通过平台接口服务层进行查询操作。
2.3接口标准
2.3.1技术标准
2.3.1.1简述
客户端和服务器用SOAP协议通过HTTP来交互，客户端根据WSDL描述文档生成SOAP请求消息发送到服务端，服务端解析收到的SOAP请求，调用Webservice，然后再生成相应的SOAP应答送回到客户端。
2.3.1.2认证机制
设备维护平台提供的所有WebService服务均需要认证授权才能被调用，Webservice服务接收到请求后从传入参数中获取用户名和密码，进行认证，认证
通过后再调用具体服务。
2.3.2数据规约
2.3.2.1简述
客户端和服务端采用XML格式的字符串来交互业务数据，客户端将业务数据组织成XML格式的字符串作为最后一个入参调用服务端接口，服务端解析XML格式的字符串得到业务数据处理业务并把结果组织成XML格式的字符串返
回给客户端。
接口调用的结果，自动序列化后，以XML格式的字符串返回，其中包含了接口调用中出现的错误描述。
2.3.2.2格式约定
若是业务接口调用，将以Dataltem_Rsp类实例序列化，表示单一数据项，内容包括操作结果、错误描述，无数据集。
若是查询接口调用，将以EntSetSerialize_Rsp类实例序列化，表示查询结果，其中包括错误描述，有数据集。
XML字符串中，若是节点取值为null，则是VBANK—CODExsi:
nil="true"x/BANK_CODE＞，在节点中存在属性XSi：
nil="true"；若是节点取值为空字符串，贝U是＜BANK_NAME/＞。
XML编码格式为“UTF-8';
字段为日期的遵循以下约定：
1.年月曰格式统一为“丫丫丫丫-MM-DD”，女口“2006-06-22”。
2.年月格式为“YYYYMM”，女口“200606”。
3.包含时间的日期格式统一为“YYYY-MM-DDTHH:
MI:
SS”，如
“2006-06-22T14:
00:
00”。
4.如果未约定日期格式，则DATE类型的默认为“YYYY-MM-DD”，如
“2006-06-22”。
2.323格式DTD
暂缺
2.3.3示例
2.3.3.1示例：
查询接口，包含数据集
xmlversion="1.0"encoding="utf-8"?
>
xmlns:
xsi="http:
//www.w3.org/2001/XMLSchema-instanee"
xmlns:
xsd="http:
//www.w3.org/2001/XMLSchema"xmlns="http:
//tempuri.org/">
0
0
操作成功
3
3
10
0
1
true
e4fb99cf-108b-4688-b124-43ae8a2b5787可控的故障维修
900308010
ead3b6fb-Oc5e-482c-892d-d629f57b75ef
nil="true"/>
9OO5O1O1O
9OO3O8O1O
1O
1
可控的故障维修
2011-09-26T17:
20:
17
nil="true"/>
true
195a341c-35dc-43ab-a2fc-bO5Obe12eaOc不可控的故障维修
9OO3O8O2O
ead3b6fb-Oc5e-482c-892d-d629f57b75ef
nil="true"/>
900501010
900308020
20
1
不可控的故障维修
2011-09-26T17:
20:
32.187
nil="true"/>
true
c648d4d3-9a7e-4f3f-8a2f-96f94cb9d978频繁上下线
9OO3O8O3Oead3b6fb-Oc5e-482c-892d-d629f57b75ef
nil="true"/>
9OO5O1O1O
9OO3O8O3O
22
1
频繁上下线
2011-11-24T23:
28:
17.953
nil="true"/>
2.3.3.2示例：
业务接口，只有返回标识
xmlversion="1.0"encoding="utf-8"?
>
xsi="http:
//www.w3.org/2001/XMLSchema-instanee"
xmlns:
xsd="http:
//www.w3.org/2001/XMLSchema"xmlns="http:
//tempuri.org/">
0
0
授权帐号验证失败
System.Boolean
False
3Webservice服务
3.1设备维护平台提供的服务
由于各用户单独安装部署，故对于WebService服务地址，另外单独提供。
3.1.1接口服务清单
序号
服务名称
接口名称
说明
调用方
频率
1
ClientUserCheck
客户端信息验证
第三方
实时
2
BaseData_DevList
基础数据.设备清单查询
第三方
实时
3
BaseData_OrgList
基础数据.组织机构及设备分组清单查询
第三方
实时
4
BaseData_DictionaryList
基础数据.数据字典代码项查询
第三方
实时
5
DevRep_FaultSearch
业务流程.故障上报查询
第三方
半小时
6
DevRep_FaultReport
故障上报
第三方
半小时
7
DevRep_RepairSearch
业务流程•报修查询
第三方
半小时
8
DevRep_RepFeeApp
维修报价申请
第三方
半小时
9
DevRep_FaultRsp
维修响应
第三方
半小时
10
DevRep_FaultFeedback
维修反馈
第三方
半小时
11
DevRep_RepairAudit
维修审核
第三方
半小时
12
3.1.2接口服务设计
3.121客户端信息验证
服务名称
ClientUserCheck
接口声明
publicDataItem_RspClientUserCheck（stringclientUser,stringclientPwd,
stringclientIp）
描述
客户端信息验证
中文名
字段名
长度类型
非空
说明及数据要求
入参
登录帐号
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientlp
string
Y
出参
IsError
0:
有错误；
1:
无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台
3.122基础数据，设备清单查询
服务名称
BaseData_DevList
接口声明
publicEntSetSerialize_Rsp
BaseData_DevList（stringdevType,stringdevIp,stringdevGuid,string
devCodeSdk,stringdevChannel
stringunitRepGuid,Int32pageIndex,stringclientUser,stringclientPwd,
stringclientlp）
描述
基础数据.设备清单查询
中文名
字段名
长度类型
非空
说明及数据要求
入参
设备类型
devType
string
N
设备IP
devIp
string
N
设备GUID
devGuid
string
N
设备接口编号
devCodeSdk
string
N
来自第三方设备平台
设备通道号
devChannel
string
N
维保单位
GUID
unitRepGuid
string
N
作为维保方，其登录帐号所属单位GUID，可作为
维保单位GUID
页索引
pageIndex
Int32
Y
登录帐号
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientlp
string
Y
出参
IsError
0:
有错误；
1:
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数:
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表，采用泛型集合List，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.123基础数据，组织机构及设备分组查询
服务名称
BaseDataOrgList
接口声明
publicEntSetSerialize_RspBaseData_OrgList（lnt32
pageIndex,stringclientUser,stringclientPwd,stringclientlp）
描述
基础数据•组织机构及设备分组清单查询
中文名
字段名
长度类型
非空
说明及数据要求
页索引
pageIndex
Int32
Y
登录帐号
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientlp
string
Y
出参
IsError
0:
有错误；
1:
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表，采用泛型集合List，自动序列化产生，根据查询接口不
同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.124基础数据，数据项查询
服务名称
BaseData_DictionaryList
接口声明
publicEntSetSerialize_Rsp
BaseData_DictionaryList（Int32pageIndex,stringnodeCategory,string
nodeType
stringclientUser,stringclientPwd,stringclientlp）
描述
基础数据•数据字典代码项查询
中文名
字段名
长度类型
非空
说明及数据要求
页索引
pageIndex
Int32
Y
节点大类
nodeCategory
string
Y
故障原因大类
-900501010
故障原因细类
-900501020
节点细类
nodeType
string
N
登录帐号
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientlp
string
Y
出参
IsError
0:
有错误；
1:
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数丁
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表，采用泛型集合List，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.125业务流程，故障上报查询
服务名称
DevRep_FaultSearch
接口声明
publicEntSetSerialize_Rsp
DevRep_FaultSearch（stringreportUnitGuid,stringfaultAuditStatus,string
devType,stringfaultType
stringfaultTimeStart,stringfaultTimeEnd,stringrepStatus,stringjobNo,stringdeviceGuid,intpageIndex
stringclientUser,stringclientPwd,stringclientlp）
描述
业务流程•故障上报查询
中文名
字段名
长度类型
非空
说明及数据要求
入参
上报单位
GUID
reportUnitGuid
string
N
作为维保方，其登录帐号所属单位GUID，可作为
上报单位GUID
故障审核状态
faultAuditStatus
string
N
设备类型
devType
string
N
故障类型
faultType
string
N
开始时间
faultTimeStart
string
N
故障时间
结束时间
faultTimeEnd
string
N
故障时间
维修状态
repStatus
string
N
工单号
jobNo
string
N
设备GUID
deviceGuid
string
N
页索引
pageIndex
Int32
Y
登录帐号
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientlp
string
Y
出参
IsError
0:
有错误；
1:
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表，采用泛型集合List，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.126业务流程，故障上报
服务名称
DevRep_FaultReport
接口声明
publicDataItem_RspDevRep_FaultReport（stringdeviceGuid,string
fault_Time,stringfault_Type
stringfault_Remark,stringclientUser,stringclientPwd,stringclientlp）
描述
故障上报
中文名
字段名
长度类型
非空
说明及数据要求
设备GUID
deviceGuid
string
Y
故障时间
fault_Time
string
Y
故障类型
fault_Type
string
Y
故障类型编号，可在数据项中查询，参考参数如下
节点大类，900501005
节点细类，900504050
故障描述
fault_R
升级会员 