設(shè)備維護(hù)平臺接口技術(shù)規(guī)范說明書

1、 設(shè)備維護(hù)平臺接口技術(shù)規(guī)范說明書（版本號 V1.0）杭州天夢科技有限公司二一年五月更改履歷版本號修改編號更改時間更改的圖表和章節(jié)更改簡要描述更改人批準(zhǔn)人V1.02013-05-13創(chuàng)建，形成初稿葉慶國V1.12014-06-09維修業(yè)務(wù)操作接口調(diào)整，僅開放維保單位相關(guān)操作接口葉慶國注：更改人除形成初稿，以后每次修改在未批準(zhǔn)確認(rèn)前均需采用修訂的方式進(jìn)行修改。目 錄1概述21.1編寫目的21.2預(yù)期讀者21.3參考文獻(xiàn)22接口平臺設(shè)計22.1技術(shù)架構(gòu)2接口架構(gòu)圖2業(yè)務(wù)流圖32.2部署方式42.3接口標(biāo)準(zhǔn)4技術(shù)標(biāo)準(zhǔn)4數(shù)據(jù)規(guī)約5示例63WEBSERVICE服務(wù)73.1設(shè)備維護(hù)平臺提供的服務(wù)7接口服務(wù)清

2、單7接口服務(wù)設(shè)計81 概述1.1 編寫目的為設(shè)備維護(hù)平臺的信息同步和共享，制定了統(tǒng)一的接口規(guī)范，用來指導(dǎo)各系統(tǒng)的接口設(shè)計、開發(fā)、聯(lián)調(diào)及遷移工作。范圍：本文檔主要是對設(shè)備維護(hù)平臺與外圍業(yè)務(wù)系統(tǒng)的數(shù)據(jù)交互需求進(jìn)行說明。1.2 調(diào)試要求強(qiáng)烈要求第三方調(diào)用者，先做測試庫的接口調(diào)試，確保接口及參數(shù)調(diào)用正確，否則將對正式庫可能出現(xiàn)的系統(tǒng)故障承擔(dān)主要責(zé)任。1.3 預(yù)期讀者項目組人員、各交互系統(tǒng)涉及到的開發(fā)廠家。1.4 參考文獻(xiàn)智能交通設(shè)備維護(hù)管理系統(tǒng)設(shè)備接入標(biāo)準(zhǔn)杭州天夢科技有限公司2 接口平臺設(shè)計2.1 技術(shù)架構(gòu)2.1.1 接口架構(gòu)圖（暫缺）2.1.2 業(yè)務(wù)流圖說明：用戶通過接口。2.2 部署方式接口服務(wù)層

3、包括Webservice服務(wù)、展現(xiàn)集成服務(wù)。1、 Webservice服務(wù)各系統(tǒng)提供的接口服務(wù)統(tǒng)一部署在設(shè)備維護(hù)平臺接口服務(wù)層上，各系統(tǒng)客戶端和接口服務(wù)層用SOAP協(xié)議通過HTTP來交互，客戶端根據(jù)WSDL描述文檔生成SOAP請求消息發(fā)送到服務(wù)端，服務(wù)端解析收到的SOAP請求，調(diào)用Web service，然后再生成相應(yīng)的SOAP應(yīng)答送回到客戶端。2、 展現(xiàn)集成服務(wù)展現(xiàn)集成服務(wù)主要是應(yīng)用界面集成服務(wù)，由服務(wù)提供方提供詳細(xì)的URL及相關(guān)參數(shù)說明，調(diào)用方傳入?yún)?shù)，調(diào)用服務(wù)方提供的頁面進(jìn)行展現(xiàn)。3、 平臺Service組件服務(wù)平臺Service組件服務(wù)統(tǒng)一部署在設(shè)備維護(hù)平臺接口服務(wù)層上，通過平臺接口服

4、務(wù)層進(jìn)行查詢操作。2.3 接口標(biāo)準(zhǔn)2.3.1 技術(shù)標(biāo)準(zhǔn) 簡述客戶端和服務(wù)器用SOAP協(xié)議通過HTTP來交互，客戶端根據(jù)WSDL描述文檔生成SOAP請求消息發(fā)送到服務(wù)端，服務(wù)端解析收到的SOAP請求，調(diào)用Web service，然后再生成相應(yīng)的SOAP應(yīng)答送回到客戶端。 認(rèn)證機(jī)制設(shè)備維護(hù)平臺提供的所有WebService服務(wù)均需要認(rèn)證授權(quán)才能被調(diào)用，Webservice服務(wù)接收到請求后從傳入?yún)?shù)中獲取用戶名和密碼，進(jìn)行認(rèn)證，認(rèn)證通過后再調(diào)用具體服務(wù)。2.3.2 數(shù)據(jù)規(guī)約 簡述客戶端和服務(wù)端采用XML格式的字符串來交互業(yè)務(wù)數(shù)據(jù)，客戶端將業(yè)務(wù)數(shù)據(jù)組織成XML

5、格式的字符串作為最后一個入?yún)⒄{(diào)用服務(wù)端接口，服務(wù)端解析XML格式的字符串得到業(yè)務(wù)數(shù)據(jù)處理業(yè)務(wù)并把結(jié)果組織成XML格式的字符串返回給客戶端。接口調(diào)用的結(jié)果，自動序列化后，以XML格式的字符串返回，其中包含了接口調(diào)用中出現(xiàn)的錯誤描述。 格式約定若是業(yè)務(wù)接口調(diào)用，將以DataItem_Rsp類實例序列化，表示單一數(shù)據(jù)項，內(nèi)容包括操作結(jié)果、錯誤描述，無數(shù)據(jù)集。若是查詢接口調(diào)用，將以EntSetSerialize_Rsp類實例序列化，表示查詢結(jié)果，其中包括錯誤描述，有數(shù)據(jù)集。XML字符串中，若是節(jié)點取值為null，則是<BANK_CODE xsi:nil="true&qu

6、ot;></BANK_CODE>，在節(jié)點中存在屬性xsi:nil="true"；若是節(jié)點取值為空字符串，則是<BANK_NAME/>。XML編碼格式為“UTF-8”；字段為日期的遵循以下約定：1. 年月日格式統(tǒng)一為“YYYY-MM-DD”，如“2006-06-22”。2. 年月格式為“YYYYMM”，如“200606”。3. 包含時間的日期格式統(tǒng)一為“YYYY-MM-DDTHH:MI:SS”，如“2006-06-22T14:00:00”。4. 如果未約定日期格式，則DATE類型的默認(rèn)為“YYYY-MM-DD”，如“2006-06-22”。2.3

7、.2.3 格式DTD暫缺2.3.3 示例 示例：查詢接口，包含數(shù)據(jù)集<?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> 示例：業(yè)務(wù)接口，只有返回標(biāo)識<?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>授權(quán)帳號驗證失敗</ErrorDesc>   <ItemType>System.Boolean

18、</ItemType>   <ItemValue>False</ItemValue> </DataItem_Rsp>3 Webservice服務(wù)3.1 設(shè)備維護(hù)平臺提供的服務(wù)由于各用戶單獨安裝部署，故對于WebService服務(wù)地址，另外單獨提供。3.1.1 接口服務(wù)清單序號服務(wù)名稱接口名稱說明調(diào)用方頻率1ClientUserCheck客戶端信息驗證第三方實時2BaseData_DevList基礎(chǔ)數(shù)據(jù).設(shè)備清單查詢第三方實時3BaseData_OrgList基礎(chǔ)數(shù)據(jù).組織機(jī)構(gòu)及設(shè)備分組清單查詢第三方實時4BaseData_Diction

19、aryList基礎(chǔ)數(shù)據(jù).數(shù)據(jù)字典代碼項查詢第三方實時5DevRep_FaultSearch業(yè)務(wù)流程.故障上報查詢第三方半小時6DevRep_FaultReport故障上報第三方半小時7DevRep_RepairSearch業(yè)務(wù)流程.報修查詢第三方半小時8DevRep_RepFeeApp維修報價申請第三方半小時9DevRep_FaultRsp維修響應(yīng)第三方半小時10DevRep_FaultFeedback維修反饋第三方半小時11DevRep_RepairAudit維修審核第三方半小時123.1.2 接口服務(wù)設(shè)計 客戶端信息驗證服務(wù)名稱ClientUserCheck接口聲明publi

20、c DataItem_Rsp ClientUserCheck(string clientUser, string clientPwd, string clientIp)描述客戶端信息驗證中文名字段名長度類型非空說明及數(shù)據(jù)要求入?yún)⒌卿泿ぬ朿lientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ItemType 數(shù)據(jù)項類型ItemValue數(shù)據(jù)項取值ErrorDesc錯誤描述部署情況設(shè)備維護(hù)平臺 基礎(chǔ)數(shù)據(jù)，設(shè)備清單查詢服務(wù)名稱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)描述基礎(chǔ)數(shù)據(jù).設(shè)備清單查詢中文名字段名長度類型非空說明及數(shù)據(jù)要求入?yún)⒃O(shè)備類型devTypestringN設(shè)備IPdevIpstrin

22、gN設(shè)備GUIDdevGuidstringN設(shè)備接口編號 devCodeSdkstringN來自第三方設(shè)備平臺設(shè)備通道號devChannelstringN維保單位GUIDunitRepGuidstringN作為維保方，其登錄帳號所屬單位GUID，可作為維保單位GUID頁索引pageIndexInt32Y登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ErrorDesc錯誤描述TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù)RspCount實際返回的記錄數(shù)RspPageSize分頁查詢的頁大

23、小RspPageIndex分頁查詢的頁索引RspPageTotal分頁查詢的頁總數(shù)EntList數(shù)據(jù)查詢結(jié)果列表,采用泛型集合List<T>，自動序列化產(chǎn)生，根據(jù)查詢接口不同，其中嵌套的對象及其字段名稱也不同，以實際返回結(jié)果為準(zhǔn)部署情況設(shè)備維護(hù)平臺 基礎(chǔ)數(shù)據(jù)，組織機(jī)構(gòu)及設(shè)備分組查詢服務(wù)名稱BaseData_OrgList接口聲明public EntSetSerialize_Rsp<BASIC_ORG_DOMAIN> BaseData_OrgList(Int32 pageIndex, string clientUser, string clientPwd,

24、string clientIp)描述基礎(chǔ)數(shù)據(jù).組織機(jī)構(gòu)及設(shè)備分組清單查詢中文名字段名長度類型非空說明及數(shù)據(jù)要求頁索引pageIndexInt32Y登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ErrorDesc錯誤描述TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù)RspCount實際返回的記錄數(shù)RspPageSize分頁查詢的頁大小RspPageIndex分頁查詢的頁索引RspPageTotal分頁查詢的頁總數(shù)EntList數(shù)據(jù)查詢結(jié)果列表,采用泛型集合List<T>，自動

25、序列化產(chǎn)生，根據(jù)查詢接口不同，其中嵌套的對象及其字段名稱也不同，以實際返回結(jié)果為準(zhǔn)部署情況設(shè)備維護(hù)平臺 基礎(chǔ)數(shù)據(jù)，數(shù)據(jù)項查詢服務(wù)名稱BaseData_DictionaryList接口聲明public EntSetSerialize_Rsp<MNG_DATA_DICTIONARY> BaseData_DictionaryList(Int32 pageIndex, string nodeCategory, string nodeType, string clientUser, string clientPwd, string clientIp)描述基礎(chǔ)數(shù)據(jù).數(shù)據(jù)字典代碼項

26、查詢中文名字段名長度類型非空說明及數(shù)據(jù)要求頁索引pageIndexInt32Y節(jié)點大類nodeCategorystringY故障原因大類-900501010故障原因細(xì)類-900501020節(jié)點細(xì)類nodeTypestringN登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ErrorDesc錯誤描述TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù)RspCount實際返回的記錄數(shù)RspPageSize分頁查詢的頁大小RspPageIndex分頁查詢的頁索引RspPageTotal分頁查詢的頁

27、總數(shù)EntList數(shù)據(jù)查詢結(jié)果列表,采用泛型集合List<T>，自動序列化產(chǎn)生，根據(jù)查詢接口不同，其中嵌套的對象及其字段名稱也不同，以實際返回結(jié)果為準(zhǔn)部署情況設(shè)備維護(hù)平臺 業(yè)務(wù)流程，故障上報查詢服務(wù)名稱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)描述業(yè)務(wù)流程.故障上報查詢中文名字段名長度類型非空說明及數(shù)據(jù)要求入?yún)⑸蠄髥挝籊UIDreportUnitGuidstringN作為維保方，其登錄帳號所屬單位GUID，可作為上報單位GUID故障審核狀態(tài)faultAuditStatusstringN設(shè)備類型devTypestringN

29、故障類型faultTypestringN開始時間faultTimeStartstringN故障時間結(jié)束時間faultTimeEndstringN故障時間維修狀態(tài)repStatusstringN工單號jobNostringN設(shè)備GUIDdeviceGuidstringN頁索引pageIndexInt32Y登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ErrorDesc錯誤描述TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù)RspCount實際返回的記錄數(shù)RspPageSize分頁查詢的頁大

30、小RspPageIndex分頁查詢的頁索引RspPageTotal分頁查詢的頁總數(shù)EntList數(shù)據(jù)查詢結(jié)果列表,采用泛型集合List<T>，自動序列化產(chǎn)生，根據(jù)查詢接口不同，其中嵌套的對象及其字段名稱也不同，以實際返回結(jié)果為準(zhǔn)部署情況設(shè)備維護(hù)平臺 業(yè)務(wù)流程，故障上報服務(wù)名稱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)描述故障上報中文名字段名長度類型非空說明及數(shù)據(jù)要求設(shè)備GUIDdeviceGuidstringY故障時間fault_TimestringY故障類型fault_TypestringY故障類型編號，可在數(shù)據(jù)項中查詢，參考參數(shù)如下節(jié)點大類，900501005節(jié)點細(xì)類，900504050故障描述fault_RemarkstringY登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ItemType 數(shù)據(jù)項類型

32、ItemValue數(shù)據(jù)項取值ErrorDesc錯誤描述部署情況設(shè)備維護(hù)平臺 業(yè)務(wù)流程，報修查詢服務(wù)名稱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)描述業(yè)務(wù)流程.報修查詢中文名字段名長度類型非空說明及數(shù)據(jù)要求入?yún)⑸蠄髥挝籊UIDreportUnitGuidstringN作為維保方，其登錄帳號所屬單位GUID，可作為上報單位GUID維修移交狀態(tài)repTransferStatusstringN設(shè)備類型devTypestringN故障類型faultTypestringN開始時間faultTimeStartstringN故障

34、時間結(jié)束時間faultTimeEndstringN故障時間維修狀態(tài)repStatusstringN工單號jobNostringN設(shè)備GUIDdeviceGuidstringN頁索引pageIndexInt32Y登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ErrorDesc錯誤描述TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù)RspCount實際返回的記錄數(shù)RspPageSize分頁查詢的頁大小RspPageIndex分頁查詢的頁索引RspPageTotal分頁查詢的頁總數(shù)EntLis

35、t數(shù)據(jù)查詢結(jié)果列表,采用泛型集合List<T>，自動序列化產(chǎn)生，根據(jù)查詢接口不同，其中嵌套的對象及其字段名稱也不同，以實際返回結(jié)果為準(zhǔn)部署情況設(shè)備維護(hù)平臺 業(yè)務(wù)流程，維修報價申請服務(wù)名稱DevRep_RepFeeApp接口聲明public DataItem_Rsp DevRep_RepFeeApp(string fault_Repair_Unit_Guid, string repFeeMemo, decimal repFee, string clientUser, string clientPwd, string clientIp)描述維修報價申請中文名字段名長度類型

36、非空說明及數(shù)據(jù)要求維修記錄GUIDfault_Repair_Unit_GuidstringY申請描述repFeeMemostringY申請費用repFeedecimalY登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤；1：無錯誤ItemType 數(shù)據(jù)項類型ItemValue數(shù)據(jù)項取值ErrorDesc錯誤描述部署情況設(shè)備維護(hù)平臺 業(yè)務(wù)流程，維修響應(yīng)服務(wù)名稱DevRep_FaultRsp接口聲明public DataItem_Rsp DevRep_FaultRsp(string fault_Repair_Unit_Guid, string fault_Reason_Memo, string clientUser, string clientPwd, string clientIp)描述維修響應(yīng)中文名字段名長度類型非空說明及數(shù)據(jù)要求維修記錄GUIDfault_Repair_Unit_GuidstringY維修響應(yīng)說明fault_Reason_MemostringY登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤