完整的接口解決方案說明書教材

1、文檔編號T-JKJS文檔版本0.01項目編號XX-DX- PECSXX電信工程外部協(xié)作系統(tǒng)Project Exterior Cooperati onSystem施工單位接口技術(shù)解決方案編寫人：南瘋?cè)掌冢?006-10-30審核人：日期：批準人：日期：XXXXX)信息科技股份有限公司地址JXXXXXXX由E編：XXXXXX電話XXXXXXXX傳真：XXXXXX網(wǎng)站XXXXXXXXX修改記錄(Revision Chart )版本號批準人修改人修改0.01南瘋2006-10-300.02詳細修改記錄：序號1 引言1.1 編寫目的1.2 覆蓋范圍1.3 預(yù)期讀者與閱讀建議1.4 文檔約定1.5 術(shù)語與

2、縮略語1.6 參考文獻2 概述3 接口方式4 接口安全4.1 接口認證4.2 數(shù)據(jù)安全5 事務(wù)處理6 性能考慮7 容錯處理8 數(shù)據(jù)格式8.1約定8.2施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求8.2.1請求查詢一個業(yè)務(wù)數(shù)據(jù)8.2.2新增一條記錄，得到記錄的鍵值8.2.3修改一條記錄8.2.4刪除一條記錄8.2.5文檔上傳8.2.6一條記錄中一個文檔字段上傳多個文件8.2.7補充上傳文檔8.2.8在記錄中刪除一個文檔8.2.9獲得文檔的基本信息8.2.10獲得文檔的所有兄弟信息8.2.11獲得文檔的所有父親信息8.2.12下載一個文檔8.2.13獲得字典8.3外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送請求8.3.1發(fā)送變更后的數(shù)據(jù)

3、8.3.2發(fā)送變更后的字典8.3.3文檔發(fā)送請求9信息數(shù)據(jù)項9.1數(shù)據(jù)表9.2字段信息9.3字典類型10網(wǎng)頁地址11Web Service接口11.1 接口命名規(guī)范11.2 輸入?yún)?shù)11.3 輸岀參數(shù)11.4 外協(xié)系統(tǒng)提供的其他接口12附錄：待定問題1引言1.1 編寫目的本文檔為XX電信工程外部協(xié)作系統(tǒng)（以下簡稱外協(xié)系統(tǒng)）與電信工程施工單位內(nèi)部系統(tǒng)（以 下簡稱施工系統(tǒng)）接口技術(shù)解決方案，以此作為外協(xié)系統(tǒng)與施工系統(tǒng)實施接口的技術(shù)方案依據(jù)和 項目設(shè)計標準。1.2 覆蓋范圍XX電信工程外部協(xié)作系統(tǒng)項目組施工系統(tǒng)接口開發(fā)技術(shù)組1.3預(yù)期讀者與閱讀建議XX電信企業(yè)信息化部XX 電信工程建設(shè)部XXXX公司

4、開發(fā)人員施工系統(tǒng)開發(fā)人員1.4文檔約定粗體正文表示強調(diào)內(nèi)容紅色正文表示未完成或需要今后考慮的內(nèi)容藍色正文表示待討論內(nèi)容1.5術(shù)語與縮略語術(shù)語、縮略語定義外協(xié)系統(tǒng)XX電信工程外部協(xié)作系統(tǒng)施工系統(tǒng)電信工程施工單位內(nèi)部系統(tǒng)PECSXX電信工程外部協(xié)作糸統(tǒng)英文簡稱1.6 參考文獻(XXXX)2 概述建設(shè)XX電信工程外部協(xié)作系統(tǒng)的目標， 是在工程項目的管理、建設(shè)、使用和實施單位之間搭 建起數(shù)據(jù)交換和協(xié)同工作的信息平臺， 延伸與拓展工程建設(shè)管理信息化的應(yīng)用范圍，實現(xiàn)通信工程建設(shè)過程的信息化管理， 促進工程項目的管理部門、 建設(shè)部門、實施部門和使用部門之間業(yè)務(wù) 流程協(xié)調(diào)有序地開展，實現(xiàn)工程項目設(shè)計、施工、監(jiān)

5、理管理功能，將相關(guān)的設(shè)計、施工、監(jiān)理單 位納入到工程建設(shè)管理中， 完善工程項目建設(shè)過程管理體系， 通過信息化推動管理的規(guī)范化， 在 信息化的應(yīng)用過程中不斷探索市場環(huán)境下工程建設(shè)管理的新思路和新方法。根據(jù)工程部業(yè)務(wù)工作的實際情況， 項目首先滿足工程建設(shè)管理中應(yīng)用最廣泛、問題最突岀的基本求。項目功能需求包括：建立工程外部協(xié)作系統(tǒng)與 MSS等系統(tǒng)的接口；建立設(shè)計協(xié)作服務(wù)、監(jiān)理協(xié)作服務(wù)、施工協(xié)作服務(wù)模塊，為郵電設(shè)計院、電話監(jiān)理公司和電信工程公司提供工程部所需的協(xié)作服務(wù)，保證工程建設(shè)實施流程的開展；在建立工程協(xié)作服務(wù)模塊的基礎(chǔ)上，建立工程外部協(xié)作系統(tǒng)與郵電設(shè)計院、電話監(jiān)理 公司、電信工程公司信息系統(tǒng)的接

6、口， 實現(xiàn)工程部與三家實施單位的信息交互與業(yè)務(wù)協(xié)作；本技術(shù)解決方案就是針對實現(xiàn)工程建設(shè)部與三家實施單位信息交互與業(yè)務(wù)協(xié)作接口中施工 單位接口的技術(shù)解決方案的組成部分。在接口的調(diào)用過程中，存在施工系統(tǒng)調(diào)用外協(xié)系統(tǒng)接口的情況，這時候，施工系統(tǒng)作為客 戶端，外協(xié)系統(tǒng)作為服務(wù)端；也存在外協(xié)系統(tǒng)調(diào)用施工系統(tǒng)的情況，這時候，外協(xié)系統(tǒng)作為客 戶端，施工系統(tǒng)作為服務(wù)端。本方案中，除了特殊另外說明外，不考慮外協(xié)系統(tǒng)和施工系統(tǒng)角 色換位的問題。如果一方發(fā)起了調(diào)用，那么它就是客戶端，另一方就是服務(wù)端。反之亦然。4 接口方式工程外協(xié)系統(tǒng)與施工系統(tǒng)之間的接口采用Web Service接口形式來進行業(yè)務(wù)數(shù)據(jù)的交接口數(shù)據(jù)傳

7、輸采用XML數(shù)據(jù)交換格式，utf-8編碼。在外協(xié)系統(tǒng)中提供 Web Service的API接口。提供由施工系統(tǒng)調(diào)用獲得信息；并且提供 施工系統(tǒng)提交信息的API接口。同樣，在施工系統(tǒng)中提供 Web Service的API接口。提供由外協(xié)系統(tǒng)提交信息的 API接 口?？紤]到工程外協(xié)中的數(shù)據(jù)信息不僅包括了XX電信工程公司的數(shù)據(jù)而且還包含了其他的施工單位的數(shù)據(jù)信息。而這些單位也各有其各自工程應(yīng)用系統(tǒng)。這樣，外協(xié)系統(tǒng)對各個施 工單位系統(tǒng)所提供的接口 API及其參數(shù)信息、格式均是統(tǒng)一的。同時，也要求各個施工單 位所提供的接口 API及其參數(shù)、格式等也必須要求統(tǒng)一。外協(xié)系統(tǒng)與施工系統(tǒng)屬于一對多 的關(guān)系。夕卜

8、協(xié)系統(tǒng)要求能夠有目的，信息有過濾的把業(yè)務(wù)信息通過接口正確的發(fā)送給相應(yīng)施工系 統(tǒng)接口。非相關(guān)的信息不要發(fā)送給對應(yīng)的施工系統(tǒng)。施工系統(tǒng)建立用戶映像對照表、字典對照表、單位對照表等數(shù)據(jù)映像，傳遞給外協(xié)的數(shù) 據(jù)使用的是映像中轉(zhuǎn)換后的外協(xié)系統(tǒng)能夠識別數(shù)據(jù)；同時，接收到的數(shù)據(jù)也根據(jù)對照表轉(zhuǎn) 換成各自能夠解釋的數(shù)據(jù)格式。數(shù)據(jù)初始化的時候，由施工系統(tǒng)主動調(diào)用外協(xié)系統(tǒng)的接口，以獲得用戶信息、字典信息、單位信息、項目信息等基礎(chǔ)信息。以后，一旦發(fā)生數(shù)據(jù)的變動，由外協(xié)系統(tǒng)主動往施工系 統(tǒng)發(fā)送信息。外協(xié)系統(tǒng)不主動請求施工系統(tǒng)獲得數(shù)據(jù)，但是外協(xié)系統(tǒng)會主動請求施工系統(tǒng)發(fā)送數(shù)據(jù)。施工系統(tǒng)主動請求外協(xié)系統(tǒng)獲得數(shù)據(jù)，也會主動請求

9、外協(xié)系統(tǒng)發(fā)送數(shù)據(jù)。4 接口安全4.1 接口認證調(diào)用認證：雖然接口雙方都是存在于電信內(nèi)部網(wǎng)絡(luò)中，但是，仍不能排除接口服務(wù)被攻擊、惡意調(diào)用以及非法調(diào)用等。所以，從接口調(diào)用上，必須考慮調(diào)用的認證安全問題。本方案中的接口，在客戶端調(diào)用服務(wù)端的時候，必須經(jīng)過調(diào)用身份認證。考慮施工系統(tǒng)的開發(fā)平臺的多樣性，但同時接口服務(wù)運行平臺都是 Windows的情況，本方案采用 Windows 安全身份認證的方式。即在訪問接口所在的服務(wù)的時候，都必須進行資格審查（使用Credentials 發(fā)送認證信息）。另外，接口采用SOAP協(xié)議，因此在接口配置上面需要屏蔽 HTTPGET和HTTPPOST等其 他協(xié)議。在接口中審核

10、并進行日志的記錄。使用最低權(quán)限的進程帳戶運行 Web服務(wù)（通過Machine.config中的<processModel>元素來配置）。接口不支持動態(tài)生成WSDL因此作為服務(wù)端，應(yīng)該禁止文檔協(xié)議。在服務(wù)端禁用跟蹤，禁用調(diào)式編譯業(yè)務(wù)用戶認證：由于接口涉及電信工程中的各個不同的業(yè)務(wù)，有獲取字典、獲得項目信息、發(fā)送開工報告等，所以，建立一套業(yè)務(wù)的用戶認證機制是必須的。不同的用戶，所具備有的授權(quán)不一樣，所能執(zhí)行的業(yè)務(wù)也不一樣。同時，業(yè)務(wù)用戶認證中的用戶信息也是記錄接口日志中的重要組成部分。本方案采用的是在接口信息中包含業(yè)務(wù)認證用戶信息的方式來進行認證。服務(wù)端在收到請求的時候，應(yīng)先驗證業(yè)務(wù)的

11、授權(quán)用戶， 如果該業(yè)務(wù)用戶沒有執(zhí)行當前業(yè)務(wù)的權(quán)限， 應(yīng)終止 業(yè)務(wù)的執(zhí)行，并給出非法用戶的警告信息反饋回客戶端。一般情況下，業(yè)務(wù)認證的用戶是系統(tǒng)中的用戶。業(yè)務(wù)認證其實就是應(yīng)用系統(tǒng)認證的組成部分。業(yè)務(wù)認證的用戶信息經(jīng)過加密之后包含在要發(fā)送的信息（XML體）中，即在發(fā)送的信息中包含業(yè)務(wù)用戶的信息（參見下面的數(shù)據(jù)格式說明）。4 .2數(shù)據(jù)安全數(shù)據(jù)的安全表現(xiàn)為如何保證數(shù)據(jù)在網(wǎng)絡(luò)傳輸過程中不會被截獲并被解析其中的內(nèi)容而 引起信息泄露與如何保證數(shù)據(jù)在傳輸?shù)倪^程中的數(shù)據(jù)的完整性兩個方面。WebService采用XML數(shù)據(jù)格式來傳輸信息。所以，無論是發(fā)送數(shù)據(jù)還是返回結(jié)果，都 要求采用對XML數(shù)據(jù)加密之后來傳輸。至

12、于采用何種方式的加密技術(shù)，本方案為了保密，只能在開發(fā)的時候由開發(fā)人員口頭告知。涉及到加密技術(shù)就要涉及到加密的密鑰問題。目前， 外協(xié)系統(tǒng)和施工系統(tǒng)接口上有很多種類型的業(yè)務(wù)，到底是每種類型的業(yè)務(wù)采用不同的密鑰， 還是按分組來采用同一種密鑰的方式，還是所有的業(yè)務(wù)全部采用同一種的密鑰的方式，按照需求各有不同的選擇。本方案采用的是最后一種的方式。密鑰的發(fā)布由作為服務(wù)方來發(fā)布， 由客戶端獲取。密鑰的發(fā)布方式待定。為了保證數(shù)據(jù)的完整性，首先：方案采用數(shù)據(jù)簽名（SOAPSecurity Extensions: Digital Sig nature ）。利用 XML的 數(shù)字簽名（XML Digital Sig

13、nature syn tax XML-Sig nature）對SOARS行擴展，在SOAF的頭元素中定義簽名屬性（SOAP-SEC:Signature）來實現(xiàn)。其次：限制并驗證 Web方法輸入的類型、長度、格式和范圍，驗證對XML輸入數(shù)據(jù)的驗證是基于 已協(xié)商的架構(gòu)等。5 事務(wù)處理事務(wù)是一組相關(guān)的任務(wù)，作為獨立于其他任務(wù)的獨立單元成功（提交）或失敗（中止）C分布式事務(wù)是影響多個資源的事務(wù)。要提交分布式事務(wù)，所有參與者都必須保證對數(shù)據(jù)的任何更改是永久的。不論系統(tǒng)崩潰或是發(fā)生其他無法預(yù)料的事件，更改都必須是持久的。 即使只有一個參與者無法保證這一點，整個事務(wù)也將失敗，在事務(wù)范圍內(nèi)對數(shù)據(jù)的任何更改均將

14、回滾。使用的是分布式事務(wù)。要啟用外協(xié)系統(tǒng)和施工系統(tǒng)是處于網(wǎng)絡(luò)之上的兩個分布式接口，分布式事務(wù)，可能需要通過網(wǎng)絡(luò)啟用 MS DTC（考慮外協(xié)平臺和施工平臺都是運行在Win dows上），以便在使用應(yīng)用了最新的Service Pack的較新操作系統(tǒng)（例如 Windows XP或Windows 2003）時使用分布式事務(wù)。 如果啟用了 Windows防火墻（Windows XPService Pack 2的默認設(shè)置），必須允許 MS DTC服務(wù)使用網(wǎng)絡(luò)或打開 MS DTC端口。接口中的服務(wù)端和客戶端的環(huán)境事務(wù)始終相同，客戶端創(chuàng)建的事務(wù)上下文并應(yīng)用對于服務(wù)端的當前的事務(wù)，以便對于該事務(wù)上下文是當前的。

15、這樣的事務(wù)會造成性能損失，因為可能需要繼承原來的上下文，但是，這樣的事務(wù)確保了在數(shù)據(jù)庫操作的時候信息的完整性。接口中事務(wù)的發(fā)起總是由客戶端發(fā)起的，并負責事務(wù)的提交和回滾等控制。6 性能考慮在接口設(shè)計的時候就應(yīng)該考慮性能上面的問題，不要在事后再加入性能。同時，在項目的開發(fā)過程要反復(fù)進行測試，可以從機器的吞吐量和響應(yīng)時間兩個基本的指標來衡量接口的 性能。接口上面的性能考慮主要從下面幾個方面來優(yōu)化：使用一次連接，多次調(diào)用，優(yōu)化連接資源。 對于并行的接口調(diào)用使用異步的調(diào)用方式。 優(yōu)化線程池減少競爭?？紤]使用XML壓縮。 如果不需要返回，考慮使用單工通訊的方式。適當?shù)脑O(shè)置（如果有代理）代理超時，頁面超時

16、，WebService超時。設(shè)計”大塊頭”的接口減少往返?；谙⒌木幊潭皇沁h程過程調(diào)用（RPC）。使用XML字串作為參數(shù)。盡量使用原始數(shù)據(jù)類型參數(shù)。 避免在調(diào)用之間維護服務(wù)器狀態(tài)?？紤]為復(fù)雜的WebMethod提供輸入校驗。 考慮對WebMethod的結(jié)果使用緩存。選擇適用的大數(shù)據(jù)包傳送方式。避免調(diào)用本地的 WebService。7 容錯處理客戶端向服務(wù)端發(fā)送數(shù)據(jù)， 服務(wù)端解析數(shù)據(jù)，反饋信息給客戶端，這中間的環(huán)節(jié)只要某一個環(huán)節(jié)出現(xiàn)問題，都會造成接口的失敗。按照失敗產(chǎn)生的環(huán)節(jié)分類，我們可以從三個方面 來處理接口的失敗。網(wǎng)絡(luò)連接失敗：在調(diào)用接口的時候，由于網(wǎng)絡(luò)不通，造成數(shù)據(jù)不能正常傳輸。這樣，

17、客戶端應(yīng)該能夠記錄發(fā)送的日志，按照一定的時間間隔重試發(fā)送。本方案定為重試發(fā)送20次，每次時間間隔2小時。如果一直發(fā)生網(wǎng)絡(luò)不通的情況，該發(fā)送日 志被保存下來，待后手工發(fā)送。所以，客戶端系統(tǒng)應(yīng)該實現(xiàn)手工發(fā)送數(shù)據(jù)的功能。反饋錯誤信息：服務(wù)端在解析數(shù)據(jù)包，執(zhí)行數(shù)據(jù)包業(yè)務(wù)的時候，可能會發(fā)生異 常。所以，服務(wù)端應(yīng)當能夠捕捉異常信息，比如“非法XML格式”等，然后反饋給客戶端?？蛻舳嗽诮邮艿竭@類的錯誤信息之后，應(yīng)當進行日志記錄，能夠自動或手工分析異常的信息。網(wǎng)絡(luò)連接正常，但是無信息反饋：這種情況下，一般是服務(wù)端出現(xiàn)了異常，但 是又沒有捕捉到的情況下發(fā)生。這種情況下，客戶端把這種錯誤當作“網(wǎng)絡(luò)連接失 敗”來處

18、理。服務(wù)端應(yīng)能夠?qū)崿F(xiàn)相同數(shù)據(jù)包重新發(fā)送過來的處理機制。8 數(shù)據(jù)格式在Web Service的調(diào)用過程中，無論是外協(xié)系統(tǒng)還是施工系統(tǒng)，都有發(fā)送數(shù)據(jù)和接收數(shù)據(jù) 的要求，也即雙方系統(tǒng)同時作為客戶端又作為服務(wù)端。我們統(tǒng)稱這些傳遞的數(shù)據(jù)為報文?？蛻舳税l(fā)送報文，屬于調(diào)用；服務(wù)端接收報文，屬于被調(diào)用?？蛻舳撕头?wù)端互相之間通訊的請求報文和結(jié)果報文遵循XML格式。客戶端發(fā)送請求報文，服務(wù)器解析調(diào)用報文，執(zhí)行報文中所在接口對應(yīng)的服務(wù)功能。 生成結(jié)果報文，以xml格式頁返回給請求者。 請求者拿到結(jié)果報文，進行解析，然后再進行相應(yīng)的處理。8.1 約定報文中所有的字典信息（比如性別 1-男，2- 女），都以代碼的值（

19、1或者2）來傳遞。施 工單位向外協(xié)系統(tǒng)發(fā)送的報文中的代碼都需要轉(zhuǎn)換成外協(xié)的代碼，外協(xié)系統(tǒng)向施工系統(tǒng)發(fā) 送的報文中的代碼無需轉(zhuǎn)換。報文中的其他數(shù)據(jù)類型，比如貨幣、RowID，自定義對象類型等，根據(jù)需要轉(zhuǎn)換成文本、數(shù)值或二進制（最終轉(zhuǎn)換成 Base64字符）的數(shù)據(jù)類型。報文中數(shù)值信息，轉(zhuǎn)換成文本，如：vltemCou nt>50</ltemCou nt> <ValueSum>12368.36</ValueSum>報文中數(shù)值不支持科學計數(shù)的方式。報文中數(shù)值的單位使用國標的單位，比如貨幣使用 “元”，長度使用“米”等。無國標的單位以約定為準。報文中的日期信息，

20、轉(zhuǎn)換成 YYYYMMDD HHmi文本格式（24小時制）。如果是空日期， 則轉(zhuǎn)換成空文本。報文中的true和false數(shù)據(jù)類型，轉(zhuǎn)換成0（表示false）、1 （表示true）報文中的二進制數(shù)據(jù)，轉(zhuǎn)換成 Base64字符方式發(fā)送。報文中的記錄集，放在 < Records標簽中；報文中一條記錄，放在 < Records標簽中。 報文中如果存在多條記錄，則在 <Records>標簽中就包含多個的<Record>標簽。如果報 文中僅有一條記錄，則<Records>標簽中只包含一個<Record>標簽.如果沒有記錄，則僅僅包含一個vRecor

21、ds標簽，沒有Record標簽。如果返回結(jié)果數(shù)據(jù)集非常多，在性能考慮和數(shù)據(jù)量沖突的情況下，可以使用分頁返回數(shù)據(jù)集的方式分批返回數(shù)據(jù)（每次返回最多100條記錄）。服務(wù)端提供分批結(jié)果返回的功能。至于如何使用分頁查詢的功能，參見下面的XML框架說明。8.2施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求的數(shù)據(jù)目前有幾點需要考慮：如何請求查詢一個業(yè)務(wù)數(shù)據(jù)如何新增一條記錄，新增之后如何點到記錄的鍵值如何修改一條記錄如何刪除一條記錄文檔如何上傳一條記錄中一個FilelD的字段如何上傳多個文件如何在一條記錄中補充上傳文檔如何在一條記錄中刪除一個文檔如何獲得文檔的基本信息如何獲得文檔的所有兄弟信息如何獲得

22、文檔的所有父親信息如何下載一個文檔針對這些問題，接口方案的解決方法如下：請求查詢一個業(yè)務(wù)數(shù)據(jù)施工系統(tǒng)針對外協(xié)系統(tǒng)發(fā)送的業(yè)務(wù)數(shù)據(jù)查詢請求根據(jù)業(yè)務(wù)類型有很多種。為了簡化接口，而不是在接口上進行業(yè)務(wù)操作，所以，外協(xié)系統(tǒng)將施工系統(tǒng)發(fā)起的數(shù)據(jù)查詢請求看作是數(shù)據(jù)下載的一種方式， 而不為了復(fù)雜的業(yè)務(wù)查詢請求提供復(fù)雜的條件解析。外協(xié)系統(tǒng)提供的數(shù)據(jù)查詢接口是從數(shù)據(jù)下載和數(shù)據(jù)延期性來考慮的。為了滿足數(shù)據(jù)的下載，外協(xié)系統(tǒng)提供了按照某一個表的主鍵來下載數(shù)據(jù)和按照記錄的變更時間范圍來下載數(shù)據(jù)的兩種方式查詢 請求。請求報文：<? xml version="1.0" encoding="

23、utf-8"?>XmlData >UserI nfo >< User > ZhangSan</ User >< PassWord > 123456</ PassWord ></ UserInfo >< Description>< RowID > 0 </ RowID >< KeyValue > 123 </ KeyValue >< QueryBeginTime > 20061018153000</ QueryBeginTime&l

24、t; QueryEndTime> 20061019153000 </ QueryEndTime></ Description></ XmlData >響應(yīng)報文:<? xml version="1.0"en codi ng="utf-8"?>1< XmlData >< Description>< RowID> 100 </RowID >h</ Description>< Records >u< Record>< F

25、ield1> Value1</Field1>< Field2> Value2</Field2>< Field3> Value3</Field3>< Field4> Value4</Field4></ Record>n< Record>< Field1> Value1</Field1>u< Field2> Value2</Field2>n< Field3> Value3</Field3>< Field4&g

26、t; Value4</Field4>u</ Record>< Record>< Field1> Value1</Field1>n< Field2> Value2</Field2>< Field3> Value3</Field3>< Field4> Value4</Field4>n</ Record></ Records>u</ XmlData >報文說明：標簽名說明<XmlData>報文數(shù)據(jù)主體<Descrip

27、ti on >報文頭部信息<Records>記錄集合<Record >一行記錄<UserInfo >業(yè)務(wù)認證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<RowlD>第一次請求的時候，客戶端RowID發(fā)送0,表示從第0條記錄開發(fā)返回。 服務(wù)端根據(jù)條件查詢，發(fā)現(xiàn)結(jié)果超過100條記錄，則在返回的結(jié)果中，RowID 的值為99，表示服務(wù)端當前的記錄位置處在第100條的位置上，后面還會有剩余的記錄?？蛻舳藱z查返回的結(jié)果，如果發(fā)現(xiàn)RowID大于0,則繼續(xù)發(fā)送請求進行查詢。但是，客戶端第二次發(fā)送請求繼

28、續(xù)查詢的時候，RowID的值要賦值為第一次返回的值，即RowlD=99服務(wù)端第二次收到請求的時候，發(fā)現(xiàn)RowID是99,則從第100條返回結(jié)果。以此類推循環(huán)調(diào)用，直到服 務(wù)端達到記錄的末尾，這時候，服務(wù)端在返回的結(jié)果中 RowID=0.客戶端發(fā) 現(xiàn)服務(wù)端RowlD=0終止循環(huán)調(diào)用。字典、用戶信息、單位信息，因為返回的字段比較少，不受100條記錄返回的限制。一次調(diào)用，就返回全部的結(jié)果。vKeyValue >查詢時主鍵的值。這個KeyValue和下面的 vQueryBeginTimexQueryEndTime是互斥的。如果在請求的時候提供了主 鍵的值，表示客戶端要求服務(wù)器按照主鍵的值查詢一條

29、記錄。如果客戶端 提供了主鍵的值，則服務(wù)端將忽略vQueryBeginTimeQueryEndTime中的 值。字典、用戶信息、單位信息，因為沒有查詢時間范圍，所以KeyValue 即表示字典類型。vQueryBeg in Time > vQueryE ndTime>查詢時時間段范圍。vQueryBeginTime是起始時間，vQueryEndTime 是結(jié)束時間。表示客戶端要求服務(wù)端查詢在這個時間范圍之內(nèi)所有變更過 的記錄（包括新增、修改、刪除）。在外協(xié)中，一條記錄新增的時候，它的創(chuàng)建時間和最后修改時間是一 樣的，以后修改記錄的時候，創(chuàng)建時間不變，改變的僅僅是最后修改時間。 同時

30、，外協(xié)系統(tǒng)中刪除記錄僅僅在“記錄是否刪除”字段中標記“ 1”， 并不是真正的物理刪除記錄。這里的時間指的是記錄變更的時間，不是記錄中的某個業(yè)務(wù)時間。 如果用戶需要按照業(yè)務(wù)時間來查詢數(shù)據(jù)，則施工系統(tǒng)把外協(xié)系統(tǒng)的數(shù)據(jù)獲取 到本地進行保存，在施工系統(tǒng)中提供按照業(yè)務(wù)時間查詢的功能。vQueryBeginTimexQueryEndTime和KeyValue是互斥的。如果客戶 端需要按照時間范圍來查詢，則必須 KeyValue空。vFieldl ><Field2 ><Field3 ><Field4 >一行記錄中的英文字段名稱。實際中，這些標簽都是字典的英文名。字段

31、 的標簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型821新增一條記錄，得到記錄的鍵值為了簡化數(shù)據(jù)模型的處理，本方案不考慮主從表的并發(fā)處理情況。如果存在主從表的數(shù)據(jù)需要上 傳，那么，在一個事務(wù)中，施工單位首先先上傳主表的記錄， 從反饋信息中獲得主表的主鍵值。 然后， 把剛剛獲得的主表的主鍵值賦值給從表的對應(yīng)外鍵，再上傳從表數(shù)據(jù)，得到從表的主鍵值。如果不是主從表，而是單表，則直接上傳數(shù)據(jù)，從反饋信息中得到主鍵值。這種情況的優(yōu)點是：數(shù)據(jù)和表相關(guān)，施工單位可以靈活的控制表之間的關(guān)系；同時，數(shù)據(jù)包中的報文比較簡單，容易解析；接口上面比較清晰，與業(yè)務(wù)的耦合比較低。缺點是：一個業(yè)務(wù)涉及的主從表不能在同一

32、個報文中（這個缺點可以通過施工系統(tǒng)靈活的控制表之間關(guān)系來解決）；一個業(yè)務(wù)中可能會使用到兩個或兩個以上的接口，造成業(yè)務(wù)完整性上面的分離（這種缺點可以通過把業(yè)務(wù)放在一個事務(wù)中來解決）；工單位獲得鍵值之后，可以在本地表中更新記錄的主鍵值。請求報文：XmlData< UserInfoXmlData >< UserInfo ><? xml version="1.0"en codi ng="utf-8"?>< User > ZhangSan </ User >< PassWord > 12345

33、6</ PassWord ></ UserInfo>< Description>< Note > 開工報告 </ Note ></ Description>< Records >XmlData >< Record >< KeyField ></KeyField>< NormalField1> Value1</NormalField1>< NormalField2> Value2</NormalField2>< Nor

34、malField3> Value3</NormalField3>1< NormalField4> Value4</NormalField4></ Record >1< Record >< KeyField ></KeyField>< NormalField1> Value1</NormalField1>1< NormalField2> Value2</NormalField2>n< NormalField3> Value3</NormalF

35、ield3>< NormalField4> Value4</NormalField4></ Record >LI </ Records >響應(yīng)報文:<? xml version="1.0" 1_1en codi ng="utf-8"?>< XmlData >< Description>（錯誤原< Result >成功</ Result ><!-如果失敗，則<Result> 里面內(nèi)容是：失敗:因）</ Descripti

36、on</ Description >< Records >< Records< Record >< Record< KeyField > Value1 </ KeyField >KeyFieldValue1 </ KeyField</ Record ></ Record >< Record >< KeyField > Value2 </ KeyField > </ Record ></ Records ></ XmlData &

37、gt;u報文說明:標簽名說明<XmlData>報文數(shù)據(jù)主體vDescripti on >報文頭部信息<Records>記錄集合vRecord >一行記錄<UserInfo >業(yè)務(wù)認證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<Note>業(yè)務(wù)的簡單描述。比如：開工報告、施工組織方案等請求中的vKeyField >一行記錄中的主鍵字段。在新增的時候，施工系統(tǒng)所給的主鍵字段內(nèi)容為 空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容為空，認為這是一條新增的記錄響應(yīng)中的vKeyField >一行記錄

38、中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系 統(tǒng)發(fā)送的記錄的順序是一一對應(yīng)的。vResult >反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細信息）”修改一條記錄施工系統(tǒng)在修改了一條記錄的時候，上傳的報文中與新增的報文類似，只是主鍵的信息不能為空。 外協(xié)系統(tǒng)判斷主鍵的信息，如果發(fā)現(xiàn)主鍵的信息不為空，則認為是修改了一條記錄。如果施工系統(tǒng)報 文中主鍵不為空，而外協(xié)系統(tǒng)在數(shù)據(jù)庫對應(yīng)的表中又沒有發(fā)現(xiàn)對應(yīng)的記錄，則自動轉(zhuǎn)換成新增的方式來處理這條記錄。外協(xié)系統(tǒng)在反饋中，還是會把主鍵返回給施工系統(tǒng)。但是，這種情況下，施工系統(tǒng)可能

39、不再需要 維護這個主鍵。即使是僅僅修改了一個字段，施工單位還得需要上傳全部的字段信息（包含被修改的字段）給外 協(xié)系統(tǒng)。施工系統(tǒng)不是對記錄做物理刪除，而僅僅是作了邏輯刪除，即僅僅在記錄的刪除標志位上面做了“ 1”的標志。這種情況對記錄來說，也是修改的范圍。只是需要在Note業(yè)務(wù)的簡單描述中說明“邏 輯刪除”。即使是邏輯刪除記錄，施工系統(tǒng)也必須上傳全部的字段到外協(xié)系統(tǒng)。請求報文：<? xml versio n="1.0"en cod in g="utf-8"?>XmlData >< Userlnfo >< User >

40、; ZhangSan</ User >< Password > 123456</ Password ></ Userlnfo >< Description>< Note >停工通知確認</ Note ></ Description>< Records >< Record >< KeyField >KeyValuel</KeyField >< NormalFieldl> Valuel</NormalFieldl>< Norm

41、alField2> Value2</NormalField2>< NormalField3> Value3</NormalField3>< NormalField4> Value4</NormalField4></ Record >< Record >< KeyField >KeyValue2</KeyField >< NormalFieldl> Valuel</NormalFieldl>< NormalField2> Value2</No

42、rmalField2>< NormalField3> Value3</NormalField3>< NormalField4> Value4</NormalField4></ Record ></ Records >XmlData >響應(yīng)報文:Lv? xml version="1.0"en codi ng="utf-8"?>< Description>< XmlData >< Result > 成功 </ Result 因）

43、-></ Description> <!-如果失敗，則<Result>里面內(nèi)容是：失?。海ㄥe誤原< Records >< Record >< KeyField> Valuel </KeyField</ Record >< Record >< KeyField> Value2 </KeyField</ Record ></ Records >XmlData >報文說明:標簽名說明<XmlData>報文數(shù)據(jù)主體<Descripti

44、on >報文頭部信息<Records>記錄集合vRecord >一行記錄<UserInfo >業(yè)務(wù)認證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<Note>業(yè)務(wù)的簡單描述。比如：開工報告、施工組織方案等請求中的vKeyField >一行記錄中的主鍵字段。在修改的時候，施工系統(tǒng)所給的主鍵字段內(nèi)容不 能為空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容不為空，認為這是一條修改的記錄響應(yīng)中的vKeyField >一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系 統(tǒng)發(fā)送的記錄的順序是一一對應(yīng)

45、的。vResult >反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細信息）”vNormalField >一行記錄中的英文字段名稱。實際中，這些標簽都是字典的英文名。字段 的標簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型824刪除一條記錄這里的刪除指的是物理刪除。邏輯刪除在記錄修改的時候已經(jīng)說明物理刪除是徹底的從數(shù)據(jù)庫中刪除一條記錄，不能恢復(fù)。物理刪除的時候，施工系統(tǒng)只要在報文 中提供主鍵的信息提交，就能夠?qū)崿F(xiàn)。同樣的，夕卜協(xié)系統(tǒng)在反饋的報文中返回成功刪除主鍵的信息，如果其中一條記錄不能正常物理刪除，則外協(xié)自動回滾所有

46、刪除的操作。即一條記錄不能刪除，則所有的記錄都不能刪除。請求報文:v?xml version="1.0" encoding="utf-8"?><XmlData>vUserlnfo ><User>ZhangSar</ User><PassWord>123456</ PassWord></ UserInfo >vDescripti on ><Note>物理刪除 </ Note</ Description > <Records>&

47、lt;Record>nDUvKeyField >Value1 </ KeyField ></ Record ><Record><KeyField >Value2 </ KeyField ></ Record ></ Records ></ XmlData>響應(yīng)報文：<?xml versio n="1.0" en codi ng="utf-8"?><XmlData><Descripti on >vResult &g

48、t;成功</Result > <!-如果失敗，則<Result>里面內(nèi)容是：失?。海ㄥe誤原因），同 時，KeyField的值為空-></ Descripti on > vRecords ><Record>vKeyField >Value1 </ KeyField > </ Record ><Record>vKeyField >Value2 </ KeyField ></ Record ></ Records >IIXmlData>報文說明：

49、（參見數(shù)據(jù)修改說明）8.2.5文檔上傳外協(xié)系統(tǒng)中，文檔的信息是保存在另外的一個表中當中的，所以，許多的業(yè)務(wù)表，往往存在一個FileID的主鍵關(guān)聯(lián)到文檔表。在業(yè)務(wù)表中檔，可能有一個FilelD的字段，也可能會有兩個或兩個以上的FilelD字段關(guān)聯(lián)到文檔信息表。涉及到文檔的地方，往往文檔的信息會比較大，所以，文檔的信息不能包含在基礎(chǔ)業(yè)務(wù)數(shù)據(jù)的報 文當中一起上傳。處理的方法是：先上傳文檔的實體，從反饋的信息當中得到生成的文檔ID（FileID），然后，施工系統(tǒng)在本地記錄中的相應(yīng)字段賦值文檔的ID，最后再上傳基本業(yè)務(wù)信息如果一條記錄中包含有兩個或兩個以上的文檔字段，則施工系統(tǒng)必須依次上傳文檔獲得文檔I

50、D之后，賦值，再上傳基本業(yè)務(wù)信息一個文檔報文當中，只能上傳一個文檔?>文檔報文如下:<?xml versio n="1.0" en cod in g="utf-8" <XmlData>vUserlnfo ><User>ZhangSarv/ User><PassWord>123456v/ PassWord> </ UserInfo >vDescripti on ></ Description ><Records><Record><I

51、D></ID><FILE_PRJD>123456</ FILE_PRJD><FILE_TYPE401 </ FILE_TYPE><FILE_NAME施工組織方案.DO«/FILE_NAME<FILE_UNIT>電信工程公司 </FILE_UNIT><FILE_MAN 張三 </FILE_MAN<FILE_CREATE_TIMI20061031 153005</ FILE_CREATE_TIMEvFILE_AUTHO>R長三 </FILE_AUTHOR<F

52、ILE_TITLE>項目 XXX施工組織方案 </FILE_TITLE>eepMutiFile >1 </ KeepMutiFile >vFileData >/e5asfdfgafa#sdgsdg </FileData ></ Record ></ Records >XmlData>響應(yīng)報文:? xml version="1.0"XmlData >en codi ng="utf-8"?> </ Record ></ Records >&

53、lt; Description >< Result >成功</ Result ><!-如果失敗，則返回信息是"失?。海ㄥe誤信息）"-></ Description >< Records >< Record >< ID > 123456 </ ID ></ XmlData >u報文說明:標簽名說明<XmlData>報文數(shù)據(jù)主體vDescripti on >報文頭部信息<Records>記錄集合vRecord >一行記錄<U

54、serInfo >業(yè)務(wù)認證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<ID>文檔的ID，在新增上傳一個文檔的時候，這個ID永遠都是空的。外協(xié)系統(tǒng)根據(jù)這個文件ID是否為空來判斷是否是新的文件。<FILE_PRJ_ID>文檔所屬的項目ID，對于工程協(xié)作系統(tǒng)來說，一個文檔永遠都是會屬于某 個項目的。這個項目ID可以是一級項目，也可以是三級項目。<FILE_TYPE>文件類型。標識文件的歸類。比如：D401施工組織設(shè)計=401D402施工項目計劃進度 =402D403施工日報=403<FILE TYP

55、匡里面的值是代碼，文件類型的代碼可以從字典接口中獲得。<FILE_NAM文檔的文件名稱，帶有擴展名。<FILE_UNIT>文件創(chuàng)建單位，中文名<FILE_MAN>文檔創(chuàng)建人（上傳人）<FILE_CREATE_TIME文檔創(chuàng)建時間<FILE_AUTHOR文檔作者（可為空）<FILE_TITLE >文檔標題（可為空）<KeepMutiFile >是否允許多個文檔同時有效。這個標簽的值為1或0。當值為1的時候，則在同樣的項目ID、同樣的文件類型中，同時可以存在多個的文檔同時有 效存在。這種情況下，多個文檔之間是兄弟之間的關(guān)系，當前的文

56、檔是弟 弟，以前的文檔是兄長。當這個值為 0的時候，則在同樣的項目ID、同樣 的文件類型中，只有最后上傳的文檔有效，后面上傳的文檔會把前面的文 檔“擠”到歷史中，成為當前文檔的“父親”。這種情況下，當前的文檔 和以前上傳的文檔之間是父子的關(guān)系。更詳細的解釋請參見后面的“一條 記錄中一個FilelD的字段如何上傳多個文件”主題相關(guān)內(nèi)容。<FileData >文件實體內(nèi)容。文件實體內(nèi)容用二進制讀取岀來之后，然后轉(zhuǎn)換成base64 的格式。<Result >反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細信息）”82

57、6 條記錄中一個文檔字段上傳多個文件外協(xié)系統(tǒng)中，文檔是以一種“有關(guān)系”的方式來存儲的。假設(shè)有這樣一個業(yè)務(wù)表Tablel ，里面有一個文檔的外鍵字段 File_ID 。當我們往Tablel表里面插入一條記錄的時候，針對這一條記錄， 我們希望在File_ID字段中可以帶有多個的文檔，也即會有多個的File_ID 。當然，我們可以把這個表字段的數(shù)據(jù)模型這個定義：FilelD ，F(xiàn)ile2D,File3_ID，需要多少個文件，我們就定義幾個的File_ID字段。但是這樣就會帶來問題了，如果你定義了5個的File_ID 字段，但是，用戶如果想在一條記錄中上傳6個文檔，那么，這樣的數(shù)據(jù)模型就會滿足不了用戶

58、的要求。還有一種 情況，如果用戶僅僅上傳了 2個文檔，那么剩下的3個File_ID字段就會白白空著。甚至用戶對這條記錄沒有上傳文件，這樣定義的數(shù)據(jù)模型就白白浪費了數(shù)據(jù)庫的資源。還有一種說法，我可以用記錄的形式來表示啊。對的。上傳多個文件，是可以在Tablel中新增多條記錄方式來表示。但是，我們的前提是，Tablel是一個業(yè)務(wù)表，里面的一條記錄就是一筆業(yè)務(wù)。如果你產(chǎn)生了多條記錄，那么意味這這樣的業(yè)務(wù)進行了多次。顯然違背了業(yè)務(wù)數(shù)據(jù)保存的初衷。外協(xié)系統(tǒng)引入了“父子”，“兄弟”的文檔保存機制，即在文檔信息表（Files表）中保存文檔的基本信息和他們之間的關(guān)系。在同樣的項目ID、同樣的文件類型中，如果可以存在多個的文檔同時有效存在，這種情況下，多個文檔之間是兄弟之間的關(guān)系。后來者文檔是弟弟，先到的文檔是兄長。在同樣的項目ID、同樣的文件類型中，只有最后上傳的文檔有效，后面上傳的文檔會把前面的文檔“擠”到歷史中，成為當前文檔的“父親”。這種情況下，后來的文檔和以前上傳的文檔之間是父子 的關(guān)系。如果文檔之間是兄弟關(guān)系的話，則僅僅在業(yè)務(wù)表Tablel中保存最小兄弟的File_ID ；如果文檔 之間是父子關(guān)系的話，則僅僅保存最小輩分的文檔File_ID 。兄弟和父子的文檔保存方式其實都是多個文檔串聯(lián)的一種保存方式，但是，還是會有使用上面的區(qū)別的。兄弟關(guān)系一般使用在文檔之間是平級的情況下