设备维护平台接口技术规范说明书.docx
《设备维护平台接口技术规范说明书.docx》由会员分享，可在线阅读，更多相关《设备维护平台接口技术规范说明书.docx（28页珍藏版）》请在冰豆网上搜索。
设备维护平台接口技术规范说明书
设备维护平台
接口技术规说明书
（版本号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服务7
3.1设备维护平台提供的服务7
3.1.1接口服务清单7
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格式约定
若是业务接口调用，将以DataItem_Rsp类实例序列化，表示单一数据项，容包括操作结果、错误描述，无数据集。
若是查询接口调用，将以EntSetSerialize_Rsp类实例序列化，表示查询结果，其中包括错误描述，有数据集。
XML字符串中，若是节点取值为null，则是nil="true">，在节点中存在属性xsi:
nil="true"；若是节点取值为空字符串，则是。
XML编码格式为“UTF-8”；
字段为日期的遵循以下约定：
1.年月日格式统一为“YYYY-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.3.2.3格式DTD
暂缺
2.3.3示例
2.3.3.1示例：
查询接口，包含数据集
xmlversion="1.0"encoding="utf-8"?
>
xsi=".w3.org/2001/XMLSchema-instance"xmlns:
xsd=".w3.org/2001/XMLSchema"xmlns="tempuri.org/">
0
0
操作成功
3
3
10
0
1
true
e4fb99cf-108b-4688-b124-43ae8a2b5787
可控的故障维修
900308010
ead3b6fb-0c5e-482c-892d-d629f57b75ef
nil="true"/>
900501010
900308010
10
1
可控的故障维修
2011-09-26T17:
20:
17
nil="true"/>
true
195a341c-35dc-43ab-a2fc-b050be12ea0c
不可控的故障维修
900308020
ead3b6fb-0c5e-482c-892d-d629f57b75ef
nil="true"/>
900501010
900308020
20
1
不可控的故障维修
2011-09-26T17:
20:
32.187
nil="true"/>
true
c648d4d3-9a7e-4f3f-8a2f-96f94cb9d978
频繁上下线
900308030
ead3b6fb-0c5e-482c-892d-d629f57b75ef
nil="true"/>
900501010
900308030
22
1
频繁上下线
2011-11-24T23:
28:
17.953
nil="true"/>
2.3.3.2示例：
业务接口，只有返回标识
xmlversion="1.0"encoding="utf-8"?
>
xsi=".w3.org/2001/XMLSchema-instance"xmlns:
xsd=".w3.org/2001/XMLSchema"xmlns="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.1.2.1客户端信息验证
服务名称
ClientUserCheck
接口声明
publicDataItem_RspClientUserCheck（stringclientUser,stringclientPwd,stringclientIp）
描述
客户端信息验证
中文名
字段名
长度类型
非空
说明及数据要求
入参
登录
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientIp
string
Y
出参
IsError
0：
有错误；
1：
无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台
3.1.2.2基础数据，设备清单查询
服务名称
BaseData_DevList
接口声明
publicEntSetSerialize_RspBaseData_DevList（stringdevType,stringdevIp,stringdevGuid,stringdevCodeSdk,stringdevChannel
stringunitRepGuid,Int32pageIndex,stringclientUser,stringclientPwd,stringclientIp）
描述
基础数据.设备清单查询
中文名
字段名
长度类型
非空
说明及数据要求
入参
设备类型
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
clientIp
string
Y
出参
IsError
0：
有错误；
1：
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.1.2.3基础数据，组织机构及设备分组查询
服务名称
BaseData_OrgList
接口声明
publicEntSetSerialize_RspBaseData_OrgList（Int32pageIndex,stringclientUser,stringclientPwd,stringclientIp）
描述
基础数据.组织机构及设备分组清单查询
中文名
字段名
长度类型
非空
说明及数据要求
页索引
pageIndex
Int32
Y
登录
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientIp
string
Y
出参
IsError
0：
有错误；
1：
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.1.2.4基础数据，数据项查询
服务名称
BaseData_DictionaryList
接口声明
publicEntSetSerialize_RspBaseData_DictionaryList（Int32pageIndex,stringnodeCategory,stringnodeType
stringclientUser,stringclientPwd,stringclientIp）
描述
基础数据.数据字典代码项查询
中文名
字段名
长度类型
非空
说明及数据要求
页索引
pageIndex
Int32
Y
节点大类
nodeCategory
string
Y
故障原因大类-900501010
故障原因细类-900501020
节点细类
nodeType
string
N
登录
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientIp
string
Y
出参
IsError
0：
有错误；
1：
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.1.2.5业务流程，故障上报查询
服务名称
DevRep_FaultSearch
接口声明
publicEntSetSerialize_RspDevRep_FaultSearch（stringreportUnitGuid,stringfaultAuditStatus,stringdevType,stringfaultType
stringfaultTimeStart,stringfaultTimeEnd,stringrepStatus,stringjobNo,stringdeviceGuid,intpageIndex
stringclientUser,stringclientPwd,stringclientIp）
描述
业务流程.故障上报查询
中文名
字段名
长度类型
非空
说明及数据要求
入参
上报单位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
clientIp
string
Y
出参
IsError
0：
有错误；
1：
无错误
ErrorDesc
错误描述
TotalCount
数据查询结果的总记录数
RspCount
实际返回的记录数
RspPageSize
分页查询的页大小
RspPageIndex
分页查询的页索引
RspPageTotal
分页查询的页总数
EntList
数据查询结果列表,采用泛型集合List，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准
部署情况
设备维护平台
3.1.2.6业务流程，故障上报
服务名称
DevRep_FaultReport
接口声明
publicDataItem_RspDevRep_FaultReport（stringdeviceGuid,stringfault_Time,stringfault_Type
stringfault_Remark,stringclientUser,stringclientPwd,stringclientIp）
描述
故障上报
中文名
字段名
长度类型
非空
说明及数据要求
设备GUID
deviceGuid
string
Y
故障时间
fault_Time
string
Y
故障类型
fault_Type
string
Y
故障类型编号，可在数据项中查询，参考参数如下
节点大类，900501005
节点细类，900504050
故障描述
fault_Remark
string
Y
登录
clientUser
string
Y
登录密码
clientPwd
string
Y
用户IP
clientIp
string
Y
出参
IsError
0：
有错误；
1：
无错误
ItemType
数据项类型
ItemValue
数据项取值
ErrorDesc
错误描述
部署情况
设备维护平台
3.1.2.7业务流程，报修查询
服务名称
DevRep_RepairSearch
接口声明
publicEntSetSerialize_RspDevRep_
升级会员 