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

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

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

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

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

5、格式的字符串作為最后一個入?yún)⒄{用服務端接口，服務端解析XML格式的字符串得到業(yè)務數(shù)據(jù)處理業(yè)務并把結果組織成XML格式的字符串返回給客戶端。接口調用的結果，自動序列化后，以XML格式的字符串返回，其中包含了接口調用中出現(xiàn)的錯誤描述。 格式約定若是業(yè)務接口調用，將以DataItem_Rsp類實例序列化，表示單一數(shù)據(jù)項，內(nèi)容包括操作結果、錯誤描述，無數(shù)據(jù)集。若是查詢接口調用，將以EntSetSerialize_Rsp類實例序列化，表示查詢結果，其中包括錯誤描述，有數(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類型的默認為“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è)務接口，只有返回標識<?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基礎數(shù)據(jù).設備清單查詢第三方實時3BaseData_OrgList基礎數(shù)據(jù).組織機構及設備分組清單查詢第三方實時4BaseData_Diction

19、aryList基礎數(shù)據(jù).數(shù)據(jù)字典代碼項查詢第三方實時5DevRep_FaultSearch業(yè)務流程.故障上報查詢第三方半小時6DevRep_FaultReport故障上報第三方半小時7DevRep_RepairSearch業(yè)務流程.報修查詢第三方半小時8DevRep_RepFeeApp維修報價申請第三方半小時9DevRep_FaultRsp維修響應第三方半小時10DevRep_FaultFeedback維修反饋第三方半小時11DevRep_RepairAudit維修審核第三方半小時123.1.2 接口服務設計 客戶端信息驗證服務名稱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ù)據(jù)，設備清單查詢服務名稱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)描述基礎數(shù)據(jù).設備清單查詢中文名字段名長度類型非空說明及數(shù)據(jù)要求入?yún)⒃O備類型devTypestringN設備IPdevIpstrin

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

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

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

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

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

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

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

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

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

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

35、t數(shù)據(jù)查詢結果列表,采用泛型集合List<T>，自動序列化產(chǎn)生，根據(jù)查詢接口不同，其中嵌套的對象及其字段名稱也不同，以實際返回結果為準部署情況設備維護平臺 業(yè)務流程，維修報價申請服務名稱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錯誤描述部署情況設備維護平臺 業(yè)務流程，維修響應服務名稱DevRep_FaultRsp接口聲明public DataItem_Rsp DevRep_FaultRsp(string fault_Repair_Unit_Guid, string fault_Reason_Memo, string clientUser, string clientPwd, string clientIp)描述維修響應中文名字段名長度類型非空說明及數(shù)據(jù)要求維修記錄GUIDfault_Repair_Unit_GuidstringY維修響應說明fault_Reason_MemostringY登錄帳號clientUserstringY登錄密碼clientPwdstringY用戶IPclientIpstringY出參IsError0：有錯誤