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

1、 设备维护平台接口技术规范说明书（版本号 V1.0）杭州天梦科技有限公司二一年五月更改履历版本号修改编号更改时间更改的图表和章节更改简要描述更改人批准人V1.02013-05-13创建，形成初稿叶庆国V1.12014-06-09维修业务操作接口调整，仅开放维保单位相关操作接口叶庆国注：更改人除形成初稿，以后每次修改在未批准确认前均需采用修订的方式进行修改。目 录1概述21.1编写目的21.2预期读者21.3参考文献22接口平台设计22.1技术架构2接口架构图2业务流图32.2部署方式42.3接口标准4技术标准4数据规约5示例63WEBSERVICE服务73.1设备维护平台提供的服务7接口服务清

2、单7接口服务设计81 概述1.1 编写目的为设备维护平台的信息同步和共享，制定了统一的接口规范，用来指导各系统的接口设计、开发、联调及迁移工作。范围：本文档主要是对设备维护平台与外围业务系统的数据交互需求进行说明。1.2 调试要求强烈要求第三方调用者，先做测试库的接口调试，确保接口及参数调用正确，否则将对正式库可能出现的系统故障承担主要责任。1.3 预期读者项目组人员、各交互系统涉及到的开发厂家。1.4 参考文献智能交通设备维护管理系统设备接入标准杭州天梦科技有限公司2 接口平台设计2.1 技术架构2.1.1 接口架构图（暂缺）2.1.2 业务流图说明：用户通过接口。2.2 部署方式接口服务层

3、包括Webservice服务、展现集成服务。1、 Webservice服务各系统提供的接口服务统一部署在设备维护平台接口服务层上，各系统客户端和接口服务层用SOAP协议通过HTTP来交互，客户端根据WSDL描述文档生成SOAP请求消息发送到服务端，服务端解析收到的SOAP请求，调用Web service，然后再生成相应的SOAP应答送回到客户端。2、 展现集成服务展现集成服务主要是应用界面集成服务，由服务提供方提供详细的URL及相关参数说明，调用方传入参数，调用服务方提供的页面进行展现。3、 平台Service组件服务平台Service组件服务统一部署在设备维护平台接口服务层上，通过平台接口服

4、务层进行查询操作。2.3 接口标准2.3.1 技术标准 简述客户端和服务器用SOAP协议通过HTTP来交互，客户端根据WSDL描述文档生成SOAP请求消息发送到服务端，服务端解析收到的SOAP请求，调用Web service，然后再生成相应的SOAP应答送回到客户端。 认证机制设备维护平台提供的所有WebService服务均需要认证授权才能被调用，Webservice服务接收到请求后从传入参数中获取用户名和密码，进行认证，认证通过后再调用具体服务。2.3.2 数据规约 简述客户端和服务端采用XML格式的字符串来交互业务数据，客户端将业务数据组织成XML

5、格式的字符串作为最后一个入参调用服务端接口，服务端解析XML格式的字符串得到业务数据处理业务并把结果组织成XML格式的字符串返回给客户端。接口调用的结果，自动序列化后，以XML格式的字符串返回，其中包含了接口调用中出现的错误描述。 格式约定若是业务接口调用，将以DataItem_Rsp类实例序列化，表示单一数据项，内容包括操作结果、错误描述，无数据集。若是查询接口调用，将以EntSetSerialize_Rsp类实例序列化，表示查询结果，其中包括错误描述，有数据集。XML字符串中，若是节点取值为null，则是<BANK_CODE xsi:nil="true&qu

6、ot;></BANK_CODE>，在节点中存在属性xsi:nil="true"；若是节点取值为空字符串，则是<BANK_NAME/>。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

7、.2.3 格式DTD暂缺2.3.3 示例 示例：查询接口，包含数据集<?xml version="1.0" encoding="utf-8" ?><EntSetSerialize_RspOfMNG_DATA_DICTIONARY xmlns:xsi="/2001/XMLSchema-instance" xmlns:xsd="/2001/XMLSchema" xmlns="/&q

8、uot;> <IsError>0</IsError> <ErrorNo>0</ErrorNo> <ErrorDesc>操作成功</ErrorDesc> <TotalCount>3</TotalCount> <RspCount>3</RspCount> <RspPageSize>10</RspPageSize> <RspPageIndex>0</RspPageIndex> <RspPageTotal>1</

9、RspPageTotal> <EntList> <MNG_DATA_DICTIONARY> <IsCreated>true</IsCreated> <NODE_GUID>e4fb99cf-108b-4688-b124-43ae8a2b5787</NODE_GUID> <NODE_NAME>可控的故障维修</NODE_NAME> <NODE_CODE>900308010</NODE_CODE> <NODE_PARENT>ead3b6fb-0c5e-482c-8

10、92d-d629f57b75ef</NODE_PARENT> <NODE_VALUE /> <NODE_LEVEL xsi:nil="true" /> <NODE_CATEGORY>900501010</NODE_CATEGORY> <NODE_TYPE>900308010</NODE_TYPE> <NODE_SORT>10</NODE_SORT> <ENABLE_STATE>1</ENABLE_STATE> <NODE_MEMO>

11、可控的故障维修</NODE_MEMO> <ADD_TIME>2011-09-26T17:20:17</ADD_TIME> <UPDATE_TIME xsi:nil="true" /> </MNG_DATA_DICTIONARY> <MNG_DATA_DICTIONARY> <IsCreated>true</IsCreated> <NODE_GUID>195a341c-35dc-43ab-a2fc-b050be12ea0c</NODE_GUID> <N

12、ODE_NAME>不可控的故障维修</NODE_NAME> <NODE_CODE>900308020</NODE_CODE> <NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT> <NODE_VALUE /> <NODE_LEVEL xsi:nil="true" /> <NODE_CATEGORY>900501010</NODE_CATEGORY> <NODE_TYPE>900

13、308020</NODE_TYPE> <NODE_SORT>20</NODE_SORT> <ENABLE_STATE>1</ENABLE_STATE> <NODE_MEMO>不可控的故障维修</NODE_MEMO> <ADD_TIME>2011-09-26T17:20:32.187</ADD_TIME> <UPDATE_TIME xsi:nil="true" /> </MNG_DATA_DICTIONARY> <MNG_DATA_DICT

14、IONARY> <IsCreated>true</IsCreated> <NODE_GUID>c648d4d3-9a7e-4f3f-8a2f-96f94cb9d978</NODE_GUID> <NODE_NAME>频繁上下线</NODE_NAME> <NODE_CODE>900308030</NODE_CODE> <NODE_PARENT>ead3b6fb-0c5e-482c-892d-d629f57b75ef</NODE_PARENT> <NODE_VALUE

15、/> <NODE_LEVEL xsi:nil="true" /> <NODE_CATEGORY>900501010</NODE_CATEGORY> <NODE_TYPE>900308030</NODE_TYPE> <NODE_SORT>22</NODE_SORT> <ENABLE_STATE>1</ENABLE_STATE> <NODE_MEMO>频繁上下线</NODE_MEMO> <ADD_TIME>2011-11-24T2

16、3:28:17.953</ADD_TIME> <UPDATE_TIME xsi:nil="true" /> </MNG_DATA_DICTIONARY> </EntList></EntSetSerialize_RspOfMNG_DATA_DICTIONARY> 示例：业务接口，只有返回标识<?xml version="1.0" encoding="utf-8" ?> <DataItem_Rsp xmlns:xsi="http:/www

17、./2001/XMLSchema-instance" xmlns:xsd="/2001/XMLSchema" xmlns="/">  <IsError>0</IsError>   <ErrorNo>0</ErrorNo>   <ErrorDesc>授权帐号验证失败</ErrorDesc>   <ItemType>System.Boolean

18、</ItemType>   <ItemValue>False</ItemValue> </DataItem_Rsp>3 Webservice服务3.1 设备维护平台提供的服务由于各用户单独安装部署，故对于WebService服务地址，另外单独提供。3.1.1 接口服务清单序号服务名称接口名称说明调用方频率1ClientUserCheck客户端信息验证第三方实时2BaseData_DevList基础数据.设备清单查询第三方实时3BaseData_OrgList基础数据.组织机构及设备分组清单查询第三方实时4BaseData_Diction

19、aryList基础数据.数据字典代码项查询第三方实时5DevRep_FaultSearch业务流程.故障上报查询第三方半小时6DevRep_FaultReport故障上报第三方半小时7DevRep_RepairSearch业务流程.报修查询第三方半小时8DevRep_RepFeeApp维修报价申请第三方半小时9DevRep_FaultRsp维修响应第三方半小时10DevRep_FaultFeedback维修反馈第三方半小时11DevRep_RepairAudit维修审核第三方半小时123.1.2 接口服务设计 客户端信息验证服务名称ClientUserCheck接口声明publi

20、c DataItem_Rsp ClientUserCheck(string clientUser, string clientPwd, string clientIp)描述客户端信息验证中文名字段名长度类型非空说明及数据要求入参登录帐号clientUserstringY登录密码clientPwdstringY用户IPclientIpstringY出参IsError0：有错误；1：无错误ItemType 数据项类型ItemValue数据项取值ErrorDesc错误描述部署情况设备维护平台 基础数据，设备清单查询服务名称BaseData_DevList接口声明public EntSe

21、tSerialize_Rsp<View_DEVICE_PURCHASE> BaseData_DevList(string devType, string devIp, string devGuid, string devCodeSdk, string devChannel, string unitRepGuid, Int32 pageIndex, string clientUser, string clientPwd, string clientIp)描述基础数据.设备清单查询中文名字段名长度类型非空说明及数据要求入参设备类型devTypestringN设备IPdevIpstrin

22、gN设备GUIDdevGuidstringN设备接口编号 devCodeSdkstringN来自第三方设备平台设备通道号devChannelstringN维保单位GUIDunitRepGuidstringN作为维保方，其登录帐号所属单位GUID，可作为维保单位GUID页索引pageIndexInt32Y登录帐号clientUserstringY登录密码clientPwdstringY用户IPclientIpstringY出参IsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总记录数RspCount实际返回的记录数RspPageSize分页查询的页大

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

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

25、序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准部署情况设备维护平台 基础数据，数据项查询服务名称BaseData_DictionaryList接口声明public EntSetSerialize_Rsp<MNG_DATA_DICTIONARY> BaseData_DictionaryList(Int32 pageIndex, string nodeCategory, string nodeType, string clientUser, string clientPwd, string clientIp)描述基础数据.数据字典代码项

26、查询中文名字段名长度类型非空说明及数据要求页索引pageIndexInt32Y节点大类nodeCategorystringY故障原因大类-900501010故障原因细类-900501020节点细类nodeTypestringN登录帐号clientUserstringY登录密码clientPwdstringY用户IPclientIpstringY出参IsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总记录数RspCount实际返回的记录数RspPageSize分页查询的页大小RspPageIndex分页查询的页索引RspPageTotal分页查询的页

27、总数EntList数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准部署情况设备维护平台 业务流程，故障上报查询服务名称DevRep_FaultSearch接口声明public EntSetSerialize_Rsp<View_RECORD_FAULT_REPAIR> DevRep_FaultSearch(string reportUnitGuid, string faultAuditStatus, string devType, string faultType, stri

28、ng faultTimeStart, string faultTimeEnd, string repStatus, string jobNo, string deviceGuid, int pageIndex, string clientUser, string clientPwd, string clientIp)描述业务流程.故障上报查询中文名字段名长度类型非空说明及数据要求入参上报单位GUIDreportUnitGuidstringN作为维保方，其登录帐号所属单位GUID，可作为上报单位GUID故障审核状态faultAuditStatusstringN设备类型devTypestringN

29、故障类型faultTypestringN开始时间faultTimeStartstringN故障时间结束时间faultTimeEndstringN故障时间维修状态repStatusstringN工单号jobNostringN设备GUIDdeviceGuidstringN页索引pageIndexInt32Y登录帐号clientUserstringY登录密码clientPwdstringY用户IPclientIpstringY出参IsError0：有错误；1：无错误ErrorDesc错误描述TotalCount数据查询结果的总记录数RspCount实际返回的记录数RspPageSize分页查询的页大

30、小RspPageIndex分页查询的页索引RspPageTotal分页查询的页总数EntList数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准部署情况设备维护平台 业务流程，故障上报服务名称DevRep_FaultReport接口声明public DataItem_Rsp DevRep_FaultReport(string deviceGuid, string fault_Time, string fault_Type, string fault_Remark, string cli

31、entUser, string clientPwd, string clientIp)描述故障上报中文名字段名长度类型非空说明及数据要求设备GUIDdeviceGuidstringY故障时间fault_TimestringY故障类型fault_TypestringY故障类型编号，可在数据项中查询，参考参数如下节点大类，900501005节点细类，900504050故障描述fault_RemarkstringY登录帐号clientUserstringY登录密码clientPwdstringY用户IPclientIpstringY出参IsError0：有错误；1：无错误ItemType 数据项类型

32、ItemValue数据项取值ErrorDesc错误描述部署情况设备维护平台 业务流程，报修查询服务名称DevRep_RepairSearch接口声明public EntSetSerialize_Rsp<View_RECORD_FAULT_REPAIR_UNIT> DevRep_RepairSearch(string reportUnitGuid, string repTransferStatus, string devType, string faultType , string faultTimeStart, string faultTimeEnd, string

33、repStatus, string jobNo, string deviceGuid, int pageIndex , string clientUser, string clientPwd, string clientIp)描述业务流程.报修查询中文名字段名长度类型非空说明及数据要求入参上报单位GUIDreportUnitGuidstringN作为维保方，其登录帐号所属单位GUID，可作为上报单位GUID维修移交状态repTransferStatusstringN设备类型devTypestringN故障类型faultTypestringN开始时间faultTimeStartstringN故障

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

35、t数据查询结果列表,采用泛型集合List<T>，自动序列化产生，根据查询接口不同，其中嵌套的对象及其字段名称也不同，以实际返回结果为准部署情况设备维护平台 业务流程，维修报价申请服务名称DevRep_RepFeeApp接口声明public DataItem_Rsp DevRep_RepFeeApp(string fault_Repair_Unit_Guid, string repFeeMemo, decimal repFee, string clientUser, string clientPwd, string clientIp)描述维修报价申请中文名字段名长度类型

36、非空说明及数据要求维修记录GUIDfault_Repair_Unit_GuidstringY申请描述repFeeMemostringY申请费用repFeedecimalY登录帐号clientUserstringY登录密码clientPwdstringY用户IPclientIpstringY出参IsError0：有错误；1：无错误ItemType 数据项类型ItemValue数据项取值ErrorDesc错误描述部署情况设备维护平台 业务流程，维修响应服务名称DevRep_FaultRsp接口声明public DataItem_Rsp DevRep_FaultRsp(string fault_Repair_Unit_Guid, string fault_Reason_Memo, string clientUser, string clientPwd, string clientIp)描述维修响应中文名字段名长度类型非空说明及数据要求维修记录GUIDfault_Repair_Unit_GuidstringY维修响应说明fault_Reason_MemostringY登录帐号clientUserstringY登录密码clientPwdstringY用户IPclientIpstringY出参IsError0：有错误