设备维护平台接口技术规范说明书

1、1 / 19设备维护平台设备维护平台接口技术规说明书接口技术规说明书（版本号 V1.0）天梦科技天梦科技二二一一年五月年五月1 / 19更改履历版本版本号号修改修改编号编号更改时间更改时间更改的更改的图表和章节图表和章节更改简要描述更改简要描述更改人更改人批准人批准人V1.02013-05-13创建，形成初稿叶庆国V1.12014-06-09维修业务操作接口调整，仅开放维保单位相关操作接口叶庆国注：更改人除形成初稿，以后每次修改在未批准确认前均需采用修订的方式进行修改。I / 19目 录1 1 概述概述 2 21.1 编写目的 21.2 预期读者 21.3 参考文献 22 2 接口平台设计接口

2、平台设计 2 22.1 技术架构 22.1.1 接口架构图 22.1.2 业务流图 32.2 部署方式 42.3 接口标准 42.3.1 技术标准 42.3.2 数据规约 52.3.3 示例 63WEBSERVICE3WEBSERVICE 服务服务 7 73.1 设备维护平台提供的服务 73.1.1 接口服务清单 73.1.2 接口服务设计 82 / 191概述1.1编写目的为设备维护平台的信息同步和共享，制定了统一的接口规，用来指导各系统的接口设计、开发、联调与迁移工作。围：本文档主要是对设备维护平台与外围业务系统的数据交互需求进行说明。1.2调试要求强烈要求第三方调用者，先做测试库的接口调

3、试，确保接口与参数调用正确，否则将对正式库可能出现的系统故障承担主要责任。1.3预期读者项目组人员、各交互系统涉与到的开发厂家。1.4参考文献智能交通设备维护管理系统设备接入标准 天梦科技2接口平台设计2.1技术架构2.1.1 接口架构图（暂缺）3 / 192.1.2 业务流图说明：用户通过接口。4 / 192.2部署方式接口服务层包括 Webservice 服务、展现集成服务。1、Webservice 服务各系统提供的接口服务统一部署在设备维护平台接口服务层上，各系统客户端和接口服务层用 SOAP 协议通过 来交互，客户端根据 WSDL 描述文档生成SOAP 请求消息发送到服务端，服务端解析

4、收到的 SOAP 请求，调用 Web service，然后再生成相应的 SOAP 应答送回到客户端。2、展现集成服务展现集成服务主要是应用界面集成服务，由服务提供方提供详细的 URL 与相关参数说明，调用方传入参数，调用服务方提供的页面进行展现。3、平台 Service 组件服务平台 Service 组件服务统一部署在设备维护平台接口服务层上，通过平台接口服务层进行查询操作。2.3接口标准2.3.1 技术标准2.3.1.1简述客户端和服务器用 SOAP 协议通过 来交互，客户端根据 WSDL 描述文档生成 SOAP 请求消息发送到服务端，服务端解析收到的 SOAP 请求，调用 Web serv

5、ice，然后再生成相应的 SOAP 应答送回到客户端。2.3.1.2认证机制设备维护平台提供的所有 WebService 服务均需要认证授权才能被调用，Webservice 服务接收到请求后从传入参数中获取用户名和密码，进行认证，认证通过后再调用具体服务。5 / 192.3.2 数据规约2.3.2.1简述客户端和服务端采用 XML 格式的字符串来交互业务数据，客户端将业务数据组织成 XML 格式的字符串作为最后一个入参调用服务端接口，服务端解析XML 格式的字符串得到业务数据处理业务并把结果组织成 XML 格式的字符串返回给客户端。接口调用的结果，自动序列化后，以 XML 格式的字符串返回，其

6、中包含了接口调用中出现的错误描述。 2.3.2.2格式约定若是业务接口调用，将以 DataItem_Rsp 类实例序列化，表示单一数据项，容包括操作结果、错误描述，无数据集。若是查询接口调用，将以 EntSetSerialize_Rsp 类实例序列化，表示查询结果，其中包括错误描述，有数据集。XML 字符串中，若是节点取值为null，则是，在节点中存在属性 xsi:nil=true；若是节点取值为空字符串，则是。XML 编码格式为“UTF-8” ；字段为日期的遵循以下约定：1. 年月日格式统一为“YYYY-MM-DD” ，如“2006-06-22” 。2. 年月格式为“YYYYMM” ，如“2

7、00606” 。3. 包含时间的日期格式统一为“YYYY-MM-DDTHH:MI:SS” ，如“2006-06-22T14:00:00” 。4. 如果未约定日期格式，则 DATE 类型的默认为“YYYY-MM-DD” ，如“2006-06-22” 。2.3.2.3格式 DTD暂缺6 / 192.3.3 示例2.3.3.1示例：查询接口，包含数据集 0 0 操作成功 3 3 10 0 1 true e4fb99cf-108b-4688-b124-43ae8a2b5787 可控的故障维修 900308010 ead3b6fb-0c5e-482c-892d-d629f57b75ef 90050101

8、0 900308010 10 1 可控的故障维修 2011-09-26T17:20:17 true 195a341c-35dc-43ab-a2fc-b050be12ea0c 不可控的故障维修 900308020 ead3b6fb-0c5e-482c-892d-d629f57b75ef 900501010 900308020 20 1 不可控的故障维修 2011-09-26T17:20:32.187 7 / 19 true c648d4d3-9a7e-4f3f-8a2f-96f94cb9d978 频繁上下线 900308030 ead3b6fb-0c5e-482c-892d-d629f57b75

9、ef 900501010 900308030 22 1 频繁上下线 2011-11-24T23:28:17.953 2.3.3.2示例：业务接口，只有返回标识 0 0 0 0 授权验证失败授权验证失败 System.BooleanSystem.Boolean FalseFalse 3Webservice 服务3.1 设备维护平台提供的服务由于各用户单独安装部署，故对于 WebService 服务地址，另外单独提供。3.1.1 接口服务清单序号服务名称接口名称说明调用方频率1ClientUserCheck客户端信息验证第三方实时2BaseData_DevList基础数据.设备清单查询第三方实时3

10、BaseData_OrgList基础数据.组织机构与设备分组清单查询第三方实时4BaseData_DictionaryList基础数据.数据字典代码项查询第三方实时8 / 195DevRep_FaultSearch业务流程.故障上报查询第三方半小时6DevRep_FaultReport故障上报第三方半小时7DevRep_RepairSearch业务流程.报修查询第三方半小时8DevRep_RepFeeApp维修报价申请第三方半小时9DevRep_FaultRsp维修响应第三方半小时10DevRep_FaultFeedback维修反馈第三方半小时11DevRep_RepairAudit维修审核第

11、三方半小时123.1.2 接口服务设计3.1.2.1客户端信息验证服务名称ClientUserCheck接口声明public DataItem_Rsp ClientUserCheck(string clientUser, string clientPwd, string clientIp)描述客户端信息验证中文名字段名长度类型非空说明与数据要求登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringY入参IsError0：有错误；1：无错误ItemType 数据项类型ItemValue数据项取值出参ErrorDesc错误描述部署情况设

12、备维护平台3.1.2.2基础数据，设备清单查询服务名称BaseData_DevList接口声明public EntSetSerialize_Rsp BaseData_DevList(string 9 / 19devType, string devIp, string devGuid, string devCodeSdk, string devChannel, string unitRepGuid, Int32 pageIndex, string clientUser, string clientPwd, string clientIp)描述基础数据.设备清单查询中文名字段名长度类型非空说明与数

13、据要求设备类型devTypestringN设备 IPdevIpstringN设备 GUIDdevGuidstringN设备接口编号 devCodeSdkstringN来自第三方设备平台设备通道号devChannelstringN维保单位 GUIDunitRepGuidstringN作为维保方，其登录所属单位 GUID，可作为维保单位 GUID页索引pageIndexInt32Y登录clientUserstringY登录密码clientPwdstringY入参用户 IPclientIpstringYIsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总

14、记录数RspCount实际返回的记录数RspPageSize分页查询的页大小RspPageIndex分页查询的页索引RspPageTotal分页查询的页总数出参EntList数据查询结果列表,采用泛型集合 List，自动序列化产生，根据查询接口不同，其中嵌套的对象与其字段名称也不同，以实际返回结果为准部署情况设备维护平台10 / 193.1.2.3基础数据，组织机构与设备分组查询服务名称BaseData_OrgList接口声明public EntSetSerialize_Rsp BaseData_OrgList(Int32 pageIndex, string clientUser, strin

15、g clientPwd, string clientIp)描述基础数据.组织机构与设备分组清单查询中文名字段名长度类型非空说明与数据要求页索引pageIndexInt32Y登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringYIsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总记录数RspCount实际返回的记录数RspPageSize分页查询的页大小RspPageIndex分页查询的页索引RspPageTotal分页查询的页总数出参EntList数据查询结果列表,采用泛型集合 Lis

16、t，自动序列化产生，根据查询接口不同，其中嵌套的对象与其字段名称也不同，以实际返回结果为准部署情况设备维护平台3.1.2.4基础数据，数据项查询服务名称BaseData_DictionaryList接口声明publicEntSetSerialize_Rsp BaseData_DictionaryList(Int32 pageIndex, string nodeCategory, string nodeType, string clientUser, string clientPwd, string clientIp)描述基础数据.数据字典代码项查询中文名字段名长度类型非空说明与数据要求页索引p

17、ageIndexInt32Y11 / 19节点大类nodeCategorystringY故障原因大类-900501010故障原因细类-900501020节点细类nodeTypestringN登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringYIsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总记录数RspCount实际返回的记录数RspPageSize分页查询的页大小RspPageIndex分页查询的页索引RspPageTotal分页查询的页总数出参EntList数据查询结果列表,采

18、用泛型集合 List，自动序列化产生，根据查询接口不同，其中嵌套的对象与其字段名称也不同，以实际返回结果为准部署情况设备维护平台3.1.2.5业务流程，故障上报查询服务名称DevRep_FaultSearch接口声明public EntSetSerialize_Rsp DevRep_FaultSearch(string reportUnitGuid, string faultAuditStatus, string devType, string faultType, string faultTimeStart, string faultTimeEnd, string repStatus, st

19、ring jobNo, string deviceGuid, int pageIndex, string clientUser, string clientPwd, string clientIp)描述业务流程.故障上报查询中文名字段名长度类型非空说明与数据要求上报单位 GUIDreportUnitGuidstringN作为维保方，其登录所属单位 GUID，可作为上报单位 GUID入参故障审核状态faultAuditStatusstringN12 / 19设备类型devTypestringN故障类型faultTypestringN开始时间faultTimeStartstringN故障时间结束时

20、间faultTimeEndstringN故障时间维修状态repStatusstringN工单号jobNostringN设备 GUIDdeviceGuidstringN页索引pageIndexInt32Y登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringYIsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总记录数RspCount实际返回的记录数RspPageSize分页查询的页大小RspPageIndex分页查询的页索引RspPageTotal分页查询的页总数出参EntList数据查询

21、结果列表,采用泛型集合 List，自动序列化产生，根据查询接口不同，其中嵌套的对象与其字段名称也不同，以实际返回结果为准部署情况设备维护平台3.1.2.6业务流程，故障上报服务名称DevRep_FaultReport接口声明public DataItem_Rsp DevRep_FaultReport(string deviceGuid, string fault_Time, string fault_Type, string fault_Remark, string clientUser, string clientPwd, string clientIp)描述故障上报13 / 19中文名字段

22、名长度类型非空说明与数据要求设备 GUIDdeviceGuidstringY故障时间fault_TimestringY故障类型fault_TypestringY故障类型编号，可在数据项中查询，参考参数如下节点大类，900501005节点细类，900504050故障描述fault_RemarkstringY登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringYIsError0：有错误；1：无错误ItemType 数据项类型ItemValue数据项取值出参ErrorDesc错误描述部署情况设备维护平台3.1.2.7业务流程，报修查询服

23、务名称DevRep_RepairSearch接口声明public EntSetSerialize_Rsp DevRep_RepairSearch(string reportUnitGuid, string repTransferStatus, string devType, string faultType , string faultTimeStart, string faultTimeEnd, string repStatus, string jobNo, string deviceGuid, int pageIndex , string clientUser, string client

24、Pwd, string clientIp)描述业务流程.报修查询中文名字段名长度类型非空说明与数据要求上报单位 GUIDreportUnitGuidstringN作为维保方，其登录所属单位 GUID，可作为上报单位 GUID维修移交状态repTransferStatusstringN入参设备类型devTypestringN14 / 19故障类型faultTypestringN开始时间faultTimeStartstringN故障时间结束时间faultTimeEndstringN故障时间维修状态repStatusstringN工单号jobNostringN设备 GUIDdeviceGuidstr

25、ingN页索引pageIndexInt32Y登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringYIsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总记录数RspCount实际返回的记录数RspPageSize分页查询的页大小RspPageIndex分页查询的页索引RspPageTotal分页查询的页总数出参EntList数据查询结果列表,采用泛型集合 List，自动序列化产生，根据查询接口不同，其中嵌套的对象与其字段名称也不同，以实际返回结果为准部署情况设备维护平台3.1.2.8业务

26、流程，维修报价申请服务名称DevRep_RepFeeApp接口声明public DataItem_Rsp DevRep_RepFeeApp(string fault_Repair_Unit_Guid, string repFeeMemo, decimal repFee, string clientUser, string clientPwd, string clientIp)描述维修报价申请中文名字段名长度类型非空说明与数据要求15 / 19维修记录 GUIDfault_Repair_Unit_GuidstringY申请描述repFeeMemostringY申请费用repFeedecimalY

27、登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringYIsError0：有错误；1：无错误ItemType 数据项类型ItemValue数据项取值出参ErrorDesc错误描述部署情况设备维护平台3.1.2.9业务流程，维修响应服务名称DevRep_FaultRsp接口声明public DataItem_Rsp DevRep_FaultRsp(string fault_Repair_Unit_Guid, string fault_Reason_Memo, string clientUser, string clientPwd, s

28、tring clientIp)描述维修响应中文名字段名长度类型非空说明与数据要求维修记录 GUIDfault_Repair_Unit_GuidstringY维修响应说明fault_Reason_MemostringY登录clientUserstringY登录密码clientPwdstringY用户 IPclientIpstringYIsError0：有错误；1：无错误ItemType 数据项类型ItemValue数据项取值出参ErrorDesc错误描述部署情况设备维护平台16 / 193.1.2.10业务流程，维修反馈服务名称DevRep_FaultFeedback接口声明public DataItem_Rsp DevRep_FaultFeedback(string fault_Repair_Unit_Guid, string feedback_Memo, int repairMinute_DelayAppaly, string fault_Reason_Category, string fault_Reason_Type,