設(shè)備維護平臺接口技術(shù)規(guī)范說明書[2013-05-13].doc

設(shè)備維護平臺設(shè)備維護平臺 接口技術(shù)規(guī)范說明書接口技術(shù)規(guī)范說明書 版本號 V1 0 杭州天夢科技有限公司杭州天夢科技有限公司 二二 一一 年五月年五月 更改履歷 版本版本 號號 修改編修改編 號號 更改時間更改時間 更改的更改的 圖表和章節(jié)圖表和章節(jié) 更改簡要描述更改簡要描述更改人更改人批準人批準人 V1 02013 05 13創(chuàng)建 形成初稿葉慶國 V1 12014 06 09維修業(yè)務操作接口調(diào)整 僅開放維保單位相關(guān)操作 接口 葉慶國 注 更改人除形成初稿 以后每次修改在未批準確認前均需采用修訂的方式 進行修改 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 I 目 錄 1概述概述 2 1 1 編寫目的 2 1 2 預期讀者 2 1 3 參考文獻 2 2接口平臺設(shè)計接口平臺設(shè)計 2 2 1 技術(shù)架構(gòu) 2 2 1 1 接口架構(gòu)圖 2 2 1 2 業(yè)務流圖 3 2 2 部署方式 4 2 3 接口標準 4 2 3 1 技術(shù)標準 4 2 3 2 數(shù)據(jù)規(guī)約 5 2 3 3 示例 6 3WEBSERVICE 服務服務 7 3 1 設(shè)備維護平臺提供的服務 7 3 1 1 接口服務清單 7 3 1 2 接口服務設(shè)計 8 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 2 1概述 1 1 編寫目的 為設(shè)備維護平臺的信息同步和共享 制定了統(tǒng)一的接口規(guī)范 用來指導各系 統(tǒng)的接口設(shè)計 開發(fā) 聯(lián)調(diào)及遷移工作 范圍 本文檔主要是對設(shè)備維護平臺與外圍業(yè)務系統(tǒng)的數(shù)據(jù)交互需求進行說 明 1 2 調(diào)試要求 強烈要求第三方調(diào)用者 先做測試庫的接口調(diào)試 確保接口及參數(shù)調(diào)用正確 否則將對正式庫可能出現(xiàn)的系統(tǒng)故障承擔主要責任 1 3 預期讀者 項目組人員 各交互系統(tǒng)涉及到的開發(fā)廠家 1 4 參考文獻 智能交通設(shè)備維護管理系統(tǒng)設(shè)備接入標準 杭州天夢科技有限公司 2接口平臺設(shè)計 2 1 技術(shù)架構(gòu) 2 1 1接口架構(gòu)圖 暫缺 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 3 2 1 2業(yè)務流圖 說明 用戶通過接口 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 4 2 2 部署方式 接口服務層包括 Webservice 服務 展現(xiàn)集成服務 1 Webservice 服務 各系統(tǒng)提供的接口服務統(tǒng)一部署在設(shè)備維護平臺接口服務層上 各系統(tǒng)客戶 端和接口服務層用 SOAP 協(xié)議通過 HTTP 來交互 客戶端根據(jù) WSDL 描述文檔生 成 SOAP 請求消息發(fā)送到服務端 服務端解析收到的 SOAP 請求 調(diào)用 Web service 然后再生成相應的 SOAP 應答送回到客戶端 2 展現(xiàn)集成服務 展現(xiàn)集成服務主要是應用界面集成服務 由服務提供方提供詳細的 URL 及 相關(guān)參數(shù)說明 調(diào)用方傳入?yún)?shù) 調(diào)用服務方提供的頁面進行展現(xiàn) 3 平臺 Service 組件服務 平臺 Service 組件服務統(tǒng)一部署在設(shè)備維護平臺接口服務層上 通過平臺接 口服務層進行查詢操作 2 3 接口標準 2 3 1技術(shù)標準 2 3 1 1 簡述 客戶端和服務器用 SOAP 協(xié)議通過 HTTP 來交互 客戶端根據(jù) WSDL 描述文 檔生成 SOAP 請求消息發(fā)送到服務端 服務端解析收到的 SOAP 請求 調(diào)用 Web service 然后再生成相應的 SOAP 應答送回到客戶端 2 3 1 2 認證機制 設(shè)備維護平臺提供的所有 WebService 服務均需要認證授權(quán)才能被調(diào)用 Webservice 服務接收到請求后從傳入?yún)?shù)中獲取用戶名和密碼 進行認證 認證 通過后再調(diào)用具體服務 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 5 2 3 2數(shù)據(jù)規(guī)約 2 3 2 1 簡述 客戶端和服務端采用 XML 格式的字符串來交互業(yè)務數(shù)據(jù) 客戶端將業(yè)務數(shù) 據(jù)組織成 XML 格式的字符串作為最后一個入?yún)⒄{(diào)用服務端接口 服務端解析 XML 格式的字符串得到業(yè)務數(shù)據(jù)處理業(yè)務并把結(jié)果組織成 XML 格式的字符串返 回給客戶端 接口調(diào)用的結(jié)果 自動序列化后 以 XML 格式的字符串返回 其中包含了 接口調(diào)用中出現(xiàn)的錯誤描述 2 3 2 2 格式約定 若是業(yè)務接口調(diào)用 將以 DataItem Rsp 類實例序列化 表示單一數(shù)據(jù)項 內(nèi)容包括操作結(jié)果 錯誤描述 無數(shù)據(jù)集 若是查詢接口調(diào)用 將以 EntSetSerialize Rsp 類實例序列化 表示查詢 結(jié)果 其中包括錯誤描述 有數(shù)據(jù)集 XML 字符串中 若是節(jié)點取值為null 則是 在節(jié)點中存在屬性 xsi nil true 若是節(jié)點取值為空字符串 則是 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 2 3 格式 DTD 暫缺 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 6 2 3 3示例 2 3 3 1 示例 查詢接口 包含數(shù)據(jù)集 0 0 操作成功 3 3 10 0 1 true e4fb99cf 108b 4688 b124 43ae8a2b5787 可控的故障維修 900308010 ead3b6fb 0c5e 482c 892d d629f57b75ef 900501010 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 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 7 true c648d4d3 9a7e 4f3f 8a2f 96f94cb9d978 頻繁上下線 900308030 ead3b6fb 0c5e 482c 892d d629f57b75ef 900501010 900308030 22 1 頻繁上下線 2011 11 24T23 28 17 953 2 3 3 2 示例 業(yè)務接口 只有返回標識 0 0 0 0 授權(quán)帳號驗證失敗授權(quán)帳號驗證失敗 System BooleanSystem Boolean FalseFalse 3Webservice 服務 3 1 設(shè)備維護平臺提供的服務 由于各用戶單獨安裝部署 故對于 WebService 服務地址 另外單獨提供 3 1 1接口服務清單 序 號 服務名稱接口名稱說明調(diào)用方頻率 1ClientUserCheck客戶端信息驗證第三方實時 2BaseData DevList基礎(chǔ)數(shù)據(jù) 設(shè)備清單查詢第三方實時 3BaseData OrgList基礎(chǔ)數(shù)據(jù) 組織機構(gòu)及設(shè)備分組 清單查詢 第三方實時 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 8 4BaseData DictionaryList基礎(chǔ)數(shù)據(jù) 數(shù)據(jù)字典代碼項查詢第三方實時 5DevRep FaultSearch業(yè)務流程 故障上報查詢第三方半小時 6DevRep FaultReport故障上報第三方半小時 7DevRep RepairSearch業(yè)務流程 報修查詢第三方半小時 8DevRep RepFeeApp維修報價申請第三方半小時 9DevRep FaultRsp維修響應第三方半小時 10DevRep FaultFeedback維修反饋第三方半小時 11DevRep RepairAudit維修審核第三方半小時 12 3 1 2接口服務設(shè)計 3 1 2 1 客戶端信息驗證 服務名稱ClientUserCheck 接口聲明public DataItem Rsp ClientUserCheck string clientUser string clientPwd string clientIp 描述客戶端信息驗證 中文名字段名長度類型非空說明及數(shù)據(jù)要求 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 用戶 IPclientIpstringY 入?yún)?IsError 0 有錯誤 1 無錯誤 ItemType 數(shù)據(jù)項類型 ItemValue數(shù)據(jù)項取值 出參 ErrorDesc錯誤描述 部署情況設(shè)備維護平臺 3 1 2 2 基礎(chǔ)數(shù)據(jù) 設(shè)備清單查詢 服務名稱BaseData DevList 接口聲明public EntSetSerialize Rsp BaseData DevList string 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 9 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ù)要求 設(shè)備類型devTypestringN 設(shè)備 IPdevIpstringN 設(shè)備 GUIDdevGuidstring N 設(shè)備接口編號 devCodeSdkstring N 來自第三方設(shè)備平臺 設(shè)備通道號devChannelstring N 維保單位 GUID unitRepGuidstring N作為維保方 其登錄帳 號所屬單位 GUID 可作 為維保單位 GUID 頁索引pageIndexInt32Y 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 入?yún)?用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ErrorDesc錯誤描述 TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù) RspCount實際返回的記錄數(shù) RspPageSize分頁查詢的頁大小 RspPageIndex分頁查詢的頁索引 RspPageTotal分頁查詢的頁總數(shù) 出參 EntList 數(shù)據(jù)查詢結(jié)果列表 采用泛 型集合 List 自動序 列化產(chǎn)生 根據(jù)查詢接口 不同 其中嵌套的對象及 其字段名稱也不同 以實 際返回結(jié)果為準 部署情況設(shè)備維護平臺 3 1 2 3 基礎(chǔ)數(shù)據(jù) 組織機構(gòu)及設(shè)備分組查詢 服務名稱BaseData OrgList 接口聲明public EntSetSerialize Rsp BaseData OrgList Int32 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 10 pageIndex string clientUser string clientPwd string clientIp 描述基礎(chǔ)數(shù)據(jù) 組織機構(gòu)及設(shè)備分組清單查詢 中文名字段名長度類型非空說明及數(shù)據(jù)要求 頁索引pageIndexInt32Y 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ErrorDesc錯誤描述 TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù) RspCount實際返回的記錄數(shù) RspPageSize分頁查詢的頁大小 RspPageIndex分頁查詢的頁索引 RspPageTotal分頁查詢的頁總數(shù) 出參 EntList 數(shù)據(jù)查詢結(jié)果列表 采用泛 型集合 List 自動序 列化產(chǎn)生 根據(jù)查詢接口 不同 其中嵌套的對象及 其字段名稱也不同 以實 際返回結(jié)果為準 部署情況設(shè)備維護平臺 3 1 2 4 基礎(chǔ)數(shù)據(jù) 數(shù)據(jù)項查詢 服務名稱BaseData DictionaryList 接口聲明public EntSetSerialize Rsp BaseData DictionaryList Int32 pageIndex string nodeCategory string nodeType string clientUser string clientPwd string clientIp 描述基礎(chǔ)數(shù)據(jù) 數(shù)據(jù)字典代碼項查詢 中文名字段名長度類型非空說明及數(shù)據(jù)要求 頁索引pageIndexInt32Y 節(jié)點大類nodeCategorystringY 故障原因大類 900501010 故障原因細類 900501020 節(jié)點細類nodeTypestringN 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 11 用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ErrorDesc錯誤描述 TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù) RspCount實際返回的記錄數(shù) RspPageSize分頁查詢的頁大小 RspPageIndex分頁查詢的頁索引 RspPageTotal分頁查詢的頁總數(shù) 出參 EntList 數(shù)據(jù)查詢結(jié)果列表 采用泛 型集合 List 自動序 列化產(chǎn)生 根據(jù)查詢接口 不同 其中嵌套的對象及 其字段名稱也不同 以實 際返回結(jié)果為準 部署情況設(shè)備維護平臺 3 1 2 5 業(yè)務流程 故障上報查詢 服務名稱DevRep FaultSearch 接口聲明public EntSetSerialize Rsp DevRep FaultSearch string reportUnitGuid string faultAuditStatus string devType string faultType string faultTimeStart string faultTimeEnd string repStatus string jobNo string deviceGuid int pageIndex string clientUser string clientPwd string clientIp 描述業(yè)務流程 故障上報查詢 中文名字段名長度類型非空說明及數(shù)據(jù)要求 上報單位 GUID reportUnitGuidstringN 作為維保方 其登錄帳 號所屬單位 GUID 可作 為上報單位 GUID 故障審核狀態(tài)faultAuditStatusstringN 設(shè)備類型devTypestring N 故障類型faultTypestring N 開始時間faultTimeStartstring N 故障時間 結(jié)束時間faultTimeEndstring N 故障時間 維修狀態(tài)repStatusstring N 入?yún)?工單號jobNostring N 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 12 設(shè)備 GUIDdeviceGuidstring N 頁索引pageIndexInt32Y 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ErrorDesc錯誤描述 TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù) RspCount實際返回的記錄數(shù) RspPageSize分頁查詢的頁大小 RspPageIndex分頁查詢的頁索引 RspPageTotal分頁查詢的頁總數(shù) 出參 EntList 數(shù)據(jù)查詢結(jié)果列表 采用泛 型集合 List 自動序 列化產(chǎn)生 根據(jù)查詢接口 不同 其中嵌套的對象及 其字段名稱也不同 以實 際返回結(jié)果為準 部署情況設(shè)備維護平臺 3 1 2 6 業(yè)務流程 故障上報 服務名稱DevRep FaultReport 接口聲明public DataItem Rsp DevRep FaultReport string deviceGuid string fault Time string fault Type string fault Remark string clientUser string clientPwd string clientIp 描述故障上報 中文名字段名長度類型非空說明及數(shù)據(jù)要求 設(shè)備 GUIDdeviceGuidstring Y 故障時間fault Timestring Y 故障類型fault Typestring Y故障類型編號 可在數(shù) 據(jù)項中查詢 參考參數(shù) 如下 節(jié)點大類 900501005 節(jié)點細類 900504050 故障描述fault Remarkstring Y 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 13 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ItemType 數(shù)據(jù)項類型 ItemValue數(shù)據(jù)項取值 出參 ErrorDesc錯誤描述 部署情況設(shè)備維護平臺 3 1 2 7 業(yè)務流程 報修查詢 服務名稱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 clientPwd string clientIp 描述業(yè)務流程 報修查詢 中文名字段名長度類型非空說明及數(shù)據(jù)要求 上報單位 GUID reportUnitGuidstringN 作為維保方 其登錄帳 號所屬單位 GUID 可作 為上報單位 GUID 維修移交狀態(tài)repTransferStatusstringN 設(shè)備類型devTypestring N 故障類型faultTypestring N 開始時間faultTimeStartstring N 故障時間 結(jié)束時間faultTimeEndstring N 故障時間 維修狀態(tài)repStatusstring N 工單號jobNostring N 設(shè)備 GUIDdeviceGuidstring N 入?yún)?頁索引pageIndexInt32Y 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 14 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ErrorDesc錯誤描述 TotalCount數(shù)據(jù)查詢結(jié)果的總記錄數(shù) RspCount實際返回的記錄數(shù) RspPageSize分頁查詢的頁大小 RspPageIndex分頁查詢的頁索引 RspPageTotal分頁查詢的頁總數(shù) 出參 EntList 數(shù)據(jù)查詢結(jié)果列表 采用泛 型集合 List 自動序 列化產(chǎn)生 根據(jù)查詢接口 不同 其中嵌套的對象及 其字段名稱也不同 以實 際返回結(jié)果為準 部署情況設(shè)備維護平臺 3 1 2 8 業(yè)務流程 維修報價申請 服務名稱DevRep RepFeeApp 接口聲明public DataItem Rsp DevRep RepFeeApp string fault Repair Unit Guid string repFeeMemo decimal repFee string clientUser string clientPwd string clientIp 描述維修報價申請 中文名字段名長度類型非空說明及數(shù)據(jù)要求 維修記錄 GUID fault Repair Unit G uid string Y 申請描述repFeeMemostring Y 申請費用repFeedecimal Y 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ItemType 數(shù)據(jù)項類型 出參 ItemValue數(shù)據(jù)項取值 設(shè)備維護平臺接口技術(shù)規(guī)范說明書 15 ErrorDesc錯誤描述 部署情況設(shè)備維護平臺 3 1 2 9 業(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ù)要求 維修記錄 GUID fault Repair Unit G uid string Y 維修響應說明fault Reason Memostring Y 登錄帳號clientUserstringY 登錄密碼clientPwdstringY 用戶 IPclientIpstringY IsError 0 有錯誤 1 無錯誤 ItemType 數(shù)據(jù)項類型 ItemValue數(shù)據(jù)項取值 出參 ErrorDesc錯誤描述 部署情況設(shè)備維護平臺 3 1 2 10 業(yè)務流程 維修反饋 服務名稱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 string clientUser string clientPwd