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

1、文檔編號：T-JKJS文檔版本：0.01項目編號：XX-DX- PECSXX電信工程外部協(xié)作系統(tǒng)Project Exterior Cooperation System 施工單位接口技術(shù)解決方案編寫人：南瘋?cè)掌冢?006-10-30審核人：日期： 批準(zhǔn)人：日期： XXXXXX信息科技股份有限公司 地址：XXXXXXX郵編：XXXXXX電話：XXXXXXXX傳真：XXXXXX網(wǎng)站：XXXXXXXXX修改記錄（Revision Chart）版本號批準(zhǔn)人修改人修改日期修改記錄0.01 南瘋2006-10-30第一次創(chuàng)建 0.02詳細(xì)修改記錄：序號內(nèi)容 1 引言1.1 編寫目的1.2 覆蓋范圍1.3 預(yù)

2、期讀者與閱讀建議1.4 文檔約定1.5 術(shù)語與縮略語1.6 參考文獻2 概述3 接口方式4 接口安全4.1 接口認(rèn)證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.

3、2.13 獲得字典8.3 外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送請求8.3.1發(fā)送變更后的數(shù)據(jù)8.3.2發(fā)送變更后的字典8.3.3文檔發(fā)送請求9 信息數(shù)據(jù)項9.1 數(shù)據(jù)表9.2 字段信息9.3 字典類型10 網(wǎng)頁地址11 Web 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è)計標(biāo)準(zhǔn)。1.2 覆蓋范圍 XX電信工程外部協(xié)作系統(tǒng)項目組

4、施工系統(tǒng)接口開發(fā)技術(shù)組1.3 預(yù)期讀者與閱讀建議 XX電信企業(yè)信息化部 XX電信工程建設(shè)部 XXXX公司開發(fā)人員 施工系統(tǒng)開發(fā)人員1.4 文檔約定粗體正文表示強調(diào)內(nèi)容 紅色正文表示未完成或需要今后考慮的內(nèi)容 藍(lán)色正文表示待討論內(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)的目標(biāo)，是在工程項目的管理、建設(shè)、使用和實施單位之間搭建起數(shù)據(jù)交換和協(xié)同工作的信息平臺，延伸與拓展工程建設(shè)管理信息化的應(yīng)用范圍，實現(xiàn)通信工程建設(shè)過程的信息化管理

5、，促進工程項目的管理部門、建設(shè)部門、實施部門和使用部門之間業(yè)務(wù)流程協(xié)調(diào)有序地開展，實現(xiàn)工程項目設(shè)計、施工、監(jiān)理管理功能，將相關(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ù)，保證工程建

6、設(shè)實施流程的開展；Ø 在建立工程協(xié)作服務(wù)模塊的基礎(chǔ)上，建立工程外部協(xié)作系統(tǒng)與郵電設(shè)計院、電話監(jiān)理公司、電信工程公司信息系統(tǒng)的接口，實現(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)用，那么它就是客戶端，另一方就

7、是服務(wù)端。反之亦然。4 接口方式u 工程外協(xié)系統(tǒng)與施工系統(tǒng)之間的接口采用Web Service接口形式來進行業(yè)務(wù)數(shù)據(jù)的交互。u 接口數(shù)據(jù)傳輸采用XML數(shù)據(jù)交換格式，utf-8編碼。u 在外協(xié)系統(tǒng)中提供Web Service的API接口。提供由施工系統(tǒng)調(diào)用獲得信息；并且提供施工系統(tǒng)提交信息的API接口。u 同樣，在施工系統(tǒng)中提供Web Service的API接口。提供由外協(xié)系統(tǒng)提交信息的API接口。u 考慮到工程外協(xié)中的數(shù)據(jù)信息不僅包括了XX電信工程公司的數(shù)據(jù)而且還包含了其他的施工單位的數(shù)據(jù)信息。而這些單位也各有其各自工程應(yīng)用系統(tǒng)。這樣，外協(xié)系統(tǒng)對各個施工單位系統(tǒng)所提供的接口API及其參數(shù)信息、

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

9、發(fā)送信息。u 外協(xié)系統(tǒng)不主動請求施工系統(tǒng)獲得數(shù)據(jù)，但是外協(xié)系統(tǒng)會主動請求施工系統(tǒng)發(fā)送數(shù)據(jù)。u 施工系統(tǒng)主動請求外協(xié)系統(tǒng)獲得數(shù)據(jù)，也會主動請求外協(xié)系統(tǒng)發(fā)送數(shù)據(jù)。4 接口安全4.1 接口認(rèn)證調(diào)用認(rèn)證：雖然接口雙方都是存在于電信內(nèi)部網(wǎng)絡(luò)中，但是，仍不能排除接口服務(wù)被攻擊、惡意調(diào)用以及非法調(diào)用等。所以，從接口調(diào)用上，必須考慮調(diào)用的認(rèn)證安全問題。u 本方案中的接口，在客戶端調(diào)用服務(wù)端的時候，必須經(jīng)過調(diào)用身份認(rèn)證?？紤]施工系統(tǒng)的開發(fā)平臺的多樣性，但同時接口服務(wù)運行平臺都是Windows的情況，本方案采用Windows安全身份認(rèn)證的方式。即在訪問接口所在的服務(wù)的時候，都必須進行資格審查（使用Credenti

10、als發(fā)送認(rèn)證信息）。u 另外，接口采用SOAP協(xié)議，因此在接口配置上面需要屏蔽HTTP GET 和HTTP POST等其他協(xié)議。u 在接口中審核并進行日志的記錄。u 使用最低權(quán)限的進程帳戶運行 Web 服務(wù)（通過 Machine.config 中的 <processModel> 元素來配置）。u 接口不支持動態(tài)生成WSDL,因此作為服務(wù)端，應(yīng)該禁止文檔協(xié)議。u 在服務(wù)端禁用跟蹤，禁用調(diào)式編譯業(yè)務(wù)用戶認(rèn)證：由于接口涉及電信工程中的各個不同的業(yè)務(wù)，有獲取字典、獲得項目信息、發(fā)送開工報告等，所以，建立一套業(yè)務(wù)的用戶認(rèn)證機制是必須的。不同的用戶，所具備有的授權(quán)不一樣，所能執(zhí)行的業(yè)務(wù)也不一

11、樣。同時，業(yè)務(wù)用戶認(rèn)證中的用戶信息也是記錄接口日志中的重要組成部分。本方案采用的是在接口信息中包含業(yè)務(wù)認(rèn)證用戶信息的方式來進行認(rèn)證。服務(wù)端在收到請求的時候，應(yīng)先驗證業(yè)務(wù)的授權(quán)用戶，如果該業(yè)務(wù)用戶沒有執(zhí)行當(dāng)前業(yè)務(wù)的權(quán)限，應(yīng)終止業(yè)務(wù)的執(zhí)行，并給出非法用戶的警告信息反饋回客戶端。一般情況下，業(yè)務(wù)認(rèn)證的用戶是系統(tǒng)中的用戶。業(yè)務(wù)認(rèn)證其實就是應(yīng)用系統(tǒng)認(rèn)證的組成部分。業(yè)務(wù)認(rèn)證的用戶信息經(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ù)

12、在傳輸?shù)倪^程中的數(shù)據(jù)的完整性兩個方面。Web Service采用XML數(shù)據(jù)格式來傳輸信息。所以，無論是發(fā)送數(shù)據(jù)還是返回結(jié)果，都要求采用對XML數(shù)據(jù)加密之后來傳輸。至于采用何種方式的加密技術(shù)，本方案為了保密，只能在開發(fā)的時候由開發(fā)人員口頭告知。涉及到加密技術(shù)就要涉及到加密的密鑰問題。目前，外協(xié)系統(tǒng)和施工系統(tǒng)接口上有很多種類型的業(yè)務(wù)，到底是每種類型的業(yè)務(wù)采用不同的密鑰，還是按分組來采用同一種密鑰的方式，還是所有的業(yè)務(wù)全部采用同一種的密鑰的方式，按照需求各有不同的選擇。本方案采用的是最后一種的方式。密鑰的發(fā)布由作為服務(wù)方來發(fā)布，由客戶端獲取。密鑰的發(fā)布方式待定。為了保證數(shù)據(jù)的完整性，首先：方案采用數(shù)

13、據(jù)簽名（SOAP Security Extensions: Digital Signature）。利用XML的數(shù)字簽名（XML Digital Signature syntax XML-Signature）對SOAP進行擴展，在SOAP的頭元素中定義簽名屬性（<SOAP-SEC:Signature>）來實現(xiàn)。其次：限制并驗證 Web 方法輸入的類型、長度、格式和范圍，驗證對 XML 輸入數(shù)據(jù)的驗證是基于已協(xié)商的架構(gòu)等。 5 事務(wù)處理事務(wù)是一組相關(guān)的任務(wù)，作為獨立于其他任務(wù)的獨立單元成功（提交）或失?。ㄖ兄梗?。分布式事務(wù)是影響多個資源的事務(wù)。要提交分布式事務(wù)，所有參與者都必須保證對數(shù)

14、據(jù)的任何更改是永久的。不論系統(tǒng)崩潰或是發(fā)生其他無法預(yù)料的事件，更改都必須是持久的。即使只有一個參與者無法保證這一點，整個事務(wù)也將失敗，在事務(wù)范圍內(nèi)對數(shù)據(jù)的任何更改均將回滾。外協(xié)系統(tǒng)和施工系統(tǒng)是處于網(wǎng)絡(luò)之上的兩個分布式接口，使用的是分布式事務(wù)。要啟用分布式事務(wù)，可能需要通過網(wǎng)絡(luò)啟用 MS DTC（考慮外協(xié)平臺和施工平臺都是運行在Windows上），以便在使用應(yīng)用了最新的 Service Pack 的較新操作系統(tǒng)（例如 Windows XP 或 Windows 2003）時使用分布式事務(wù)。如果啟用了 Windows 防火墻（Windows XP Service Pack 2 的默認(rèn)設(shè)置），必須允許

15、 MS DTC 服務(wù)使用網(wǎng)絡(luò)或打開 MS DTC 端口。接口中的服務(wù)端和客戶端的環(huán)境事務(wù)始終相同，客戶端創(chuàng)建的事務(wù)上下文并應(yīng)用對于服務(wù)端的當(dāng)前的事務(wù)，以便對于該事務(wù)上下文是當(dāng)前的。這樣的事務(wù)會造成性能損失，因為可能需要繼承原來的上下文，但是，這樣的事務(wù)確保了在數(shù)據(jù)庫操作的時候信息的完整性。接口中事務(wù)的發(fā)起總是由客戶端發(fā)起的，并負(fù)責(zé)事務(wù)的提交和回滾等控制。6 性能考慮在接口設(shè)計的時候就應(yīng)該考慮性能上面的問題，不要在事后再加入性能。同時，在項目的開發(fā)過程要反復(fù)進行測試，可以從機器的吞吐量和響應(yīng)時間兩個基本的指標(biāo)來衡量接口的性能。接口上面的性能考慮主要從下面幾個方面來優(yōu)化：u 使用一次連接，多次調(diào)用

16、，優(yōu)化連接資源。u 對于并行的接口調(diào)用使用異步的調(diào)用方式。u 優(yōu)化線程池減少競爭。u 考慮使用XML壓縮。u 如果不需要返回，考慮使用單工通訊的方式。u 適當(dāng)?shù)脑O(shè)置（如果有代理）代理超時，頁面超時，WebService超時。u 設(shè)計"大塊頭"的接口減少往返。u 基于消息的編程而不是遠(yuǎn)程過程調(diào)用(RPC) 。u 使用XML字串作為參數(shù)。u 盡量使用原始數(shù)據(jù)類型參數(shù)。u 避免在調(diào)用之間維護服務(wù)器狀態(tài)。u 考慮為復(fù)雜的WebMethod提供輸入校驗。u 考慮對WebMethod的結(jié)果使用緩存。u 選擇適用的大數(shù)據(jù)包傳送方式。u 避免調(diào)用本地的WebService。 7 容錯處理客

17、戶端向服務(wù)端發(fā)送數(shù)據(jù)，服務(wù)端解析數(shù)據(jù)，反饋信息給客戶端，這中間的環(huán)節(jié)只要某一個環(huán)節(jié)出現(xiàn)問題，都會造成接口的失敗。按照失敗產(chǎn)生的環(huán)節(jié)分類，我們可以從三個方面來處理接口的失敗。u 網(wǎng)絡(luò)連接失敗：在調(diào)用接口的時候，由于網(wǎng)絡(luò)不通，造成數(shù)據(jù)不能正常傳輸。這樣，客戶端應(yīng)該能夠記錄發(fā)送的日志，按照一定的時間間隔重試發(fā)送。本方案定為重試發(fā)送20次，每次時間間隔2小時。如果一直發(fā)生網(wǎng)絡(luò)不通的情況，該發(fā)送日志被保存下來，待后手工發(fā)送。所以，客戶端系統(tǒng)應(yīng)該實現(xiàn)手工發(fā)送數(shù)據(jù)的功能。u 反饋錯誤信息：服務(wù)端在解析數(shù)據(jù)包，執(zhí)行數(shù)據(jù)包業(yè)務(wù)的時候，可能會發(fā)生異常。所以，服務(wù)端應(yīng)當(dāng)能夠捕捉異常信息，比如“非法XML格式”等，然

18、后反饋給客戶端?？蛻舳嗽诮邮艿竭@類的錯誤信息之后，應(yīng)當(dāng)進行日志記錄，能夠自動或手工分析異常的信息。u 網(wǎng)絡(luò)連接正常，但是無信息反饋：這種情況下，一般是服務(wù)端出現(xiàn)了異常，但是又沒有捕捉到的情況下發(fā)生。這種情況下，客戶端把這種錯誤當(dāng)作“網(wǎng)絡(luò)連接失敗”來處理。服務(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ù)為報文。 客戶端發(fā)送報文，屬于調(diào)用；服務(wù)端接收報文，屬于被調(diào)用。 客戶端和服務(wù)端互相之間通訊的請求報文和結(jié)果報文遵循XML格

19、式?？蛻舳税l(fā)送請求報文，服務(wù)器解析調(diào)用報文，執(zhí)行報文中所在接口對應(yīng)的服務(wù)功能。生成結(jié)果報文，以xml格式頁返回給請求者。請求者拿到結(jié)果報文，進行解析，然后再進行相應(yīng)的處理。8.1 約定u 報文中所有的字典信息（比如性別1-男，2-女），都以代碼的值（1或者2）來傳遞。施工單位向外協(xié)系統(tǒng)發(fā)送的報文中的代碼都需要轉(zhuǎn)換成外協(xié)的代碼，外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送的報文中的代碼無需轉(zhuǎn)換。u 報文中的其他數(shù)據(jù)類型，比如貨幣、RowID,自定義對象類型等，根據(jù)需要轉(zhuǎn)換成文本、數(shù)值或二進制（最終轉(zhuǎn)換成Base64字符）的數(shù)據(jù)類型。u 報文中數(shù)值信息，轉(zhuǎn)換成文本，如：<ItemCount>50</I

20、temCount><ValueSum>12368.36</ValueSum>u 報文中數(shù)值不支持科學(xué)計數(shù)的方式。報文中數(shù)值的單位使用國標(biāo)的單位，比如貨幣使用“元”，長度使用“米”等。無國標(biāo)的單位以約定為準(zhǔn)。u 報文中的日期信息，轉(zhuǎn)換成YYYYMMDD HHmmss文本格式（24小時制）。如果是空日期，則轉(zhuǎn)換成空文本。u 報文中的true和false數(shù)據(jù)類型，轉(zhuǎn)換成 0(表示false)、1（表示true）u 報文中的二進制數(shù)據(jù)，轉(zhuǎn)換成Base64字符方式發(fā)送。u 報文中的記錄集，放在< Records>標(biāo)簽中；報文中一條記錄，放在< Record

21、s>標(biāo)簽中。u 報文中如果存在多條記錄，則在<Records>標(biāo)簽中就包含多個的<Record>標(biāo)簽。如果報文中僅有一條記錄，則<Records>標(biāo)簽中只包含一個<Record>標(biāo)簽.如果沒有記錄，則僅僅包含一個<Records>標(biāo)簽,沒有<Record>標(biāo)簽。u 如果返回結(jié)果數(shù)據(jù)集非常多，在性能考慮和數(shù)據(jù)量沖突的情況下，可以使用分頁返回數(shù)據(jù)集的方式分批返回數(shù)據(jù)（每次返回最多100條記錄）。服務(wù)端提供分批結(jié)果返回的功能。至于如何使用分頁查詢的功能，參見下面的XML框架說明。8.2 施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求施工系統(tǒng)向

22、外協(xié)系統(tǒng)發(fā)送請求的數(shù)據(jù)目前有幾點需要考慮：u 如何請求查詢一個業(yè)務(wù)數(shù)據(jù)u 如何新增一條記錄，新增之后如何點到記錄的鍵值u 如何修改一條記錄u 如何刪除一條記錄u 文檔如何上傳u 一條記錄中一個FileID的字段如何上傳多個文件u 如何在一條記錄中補充上傳文檔u 如何在一條記錄中刪除一個文檔u 如何獲得文檔的基本信息u 如何獲得文檔的所有兄弟信息u 如何獲得文檔的所有父親信息u 如何下載一個文檔針對這些問題，接口方案的解決方法如下：8.2.1 請求查詢一個業(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ā)起

23、的數(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="utf-8" ?><XmlData><UserInfo> <User>ZhangSan</User> <PassWord>123456</PassWo

24、rd> </UserInfo> <Description> <RowID>0</RowID> <KeyValue>123</KeyValue> <QueryBeginTime>20061018 153000</QueryBeginTime> <QueryEndTime>20061019 153000</QueryEndTime> </Description></XmlData>響應(yīng)報文：<?xml version="1.0&quo

25、t; encoding="utf-8"?><XmlData> <Description> <RowID>100</RowID> </Description> <Records> <Record> <Field1>Value1</Field1> <Field2>Value2</Field2> <Field3>Value3</Field3> <Field4>Value4</Field4> <

26、;/Record> <Record> <Field1>Value1</Field1> <Field2>Value2</Field2> <Field3>Value3</Field3> <Field4>Value4</Field4> </Record> <Record> <Field1>Value1</Field1> <Field2>Value2</Field2> <Field3>Value3</

27、Field3> <Field4>Value4</Field4> </Record> </Records></XmlData>報文說明：標(biāo)簽名說明<XmlData>報文數(shù)據(jù)主體<Description>報文頭部信息<Records>記錄集合<Record>一行記錄<UserInfo>業(yè)務(wù)認(rèn)證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<RowID>第一次請求的時候，客戶端RowID發(fā)送0，表示從第0條記錄開發(fā)

28、返回。服務(wù)端根據(jù)條件查詢，發(fā)現(xiàn)結(jié)果超過100條記錄，則在返回的結(jié)果中，RowID的值為99，表示服務(wù)端當(dāng)前的記錄位置處在第100條的位置上，后面還會有剩余的記錄?？蛻舳藱z查返回的結(jié)果，如果發(fā)現(xiàn)RowID大于0,則繼續(xù)發(fā)送請求進行查詢。但是，客戶端第二次發(fā)送請求繼續(xù)查詢的時候，RowID的值要賦值為第一次返回的值，即RowID=99。服務(wù)端第二次收到請求的時候，發(fā)現(xiàn)RowID是99,則從第100條返回結(jié)果。以此類推循環(huán)調(diào)用，直到服務(wù)端達到記錄的末尾，這時候，服務(wù)端在返回的結(jié)果中RowID=0.客戶端發(fā)現(xiàn)服務(wù)端RowID=0，終止循環(huán)調(diào)用。字典、用戶信息、單位信息，因為返回的字段比較少，不受100

29、條記錄返回的限制。一次調(diào)用，就返回全部的結(jié)果。<KeyValue>查詢時主鍵的值。這個<KeyValue>和下面的<QueryBeginTime><QueryEndTime>是互斥的。如果在請求的時候提供了主鍵的值，表示客戶端要求服務(wù)器按照主鍵的值查詢一條記錄。如果客戶端提供了主鍵的值，則服務(wù)端將忽略<QueryBeginTime><QueryEndTime>中的值。字典、用戶信息、單位信息，因為沒有查詢時間范圍，所以<KeyValue>即表示字典類型。<QueryBeginTime><Que

30、ryEndTime>查詢時時間段范圍。<QueryBeginTime>是起始時間，<QueryEndTime>是結(jié)束時間。表示客戶端要求服務(wù)端查詢在這個時間范圍之內(nèi)所有變更過的記錄（包括新增、修改、刪除）。在外協(xié)中，一條記錄新增的時候，它的創(chuàng)建時間和最后修改時間是一樣的，以后修改記錄的時候，創(chuàng)建時間不變，改變的僅僅是最后修改時間。同時，外協(xié)系統(tǒng)中刪除記錄僅僅在“記錄是否刪除”字段中標(biāo)記“1”，并不是真正的物理刪除記錄。這里的時間指的是記錄變更的時間，不是記錄中的某個業(yè)務(wù)時間。如果用戶需要按照業(yè)務(wù)時間來查詢數(shù)據(jù)，則施工系統(tǒng)把外協(xié)系統(tǒng)的數(shù)據(jù)獲取到本地進行保存，在施工系

31、統(tǒng)中提供按照業(yè)務(wù)時間查詢的功能。<QueryBeginTime><QueryEndTime>和<KeyValue>是互斥的。如果客戶端需要按照時間范圍來查詢，則必須<KeyValue>空。<Field1><Field2><Field3><Field4>一行記錄中的英文字段名稱。實際中，這些標(biāo)簽都是字典的英文名。字段的標(biāo)簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型 8.2.1 新增一條記錄，得到記錄的鍵值為了簡化數(shù)據(jù)模型的處理，本方案不考慮主從表的并發(fā)處理情況。如果存在主從表的數(shù)據(jù)需要上傳，那么，

32、在一個事務(wù)中，施工單位首先先上傳主表的記錄，從反饋信息中獲得主表的主鍵值。然后，把剛剛獲得的主表的主鍵值賦值給從表的對應(yīng)外鍵，再上傳從表數(shù)據(jù)，得到從表的主鍵值。如果不是主從表，而是單表，則直接上傳數(shù)據(jù)，從反饋信息中得到主鍵值。這種情況的優(yōu)點是：數(shù)據(jù)和表相關(guān)，施工單位可以靈活的控制表之間的關(guān)系；同時，數(shù)據(jù)包中的報文比較簡單，容易解析；接口上面比較清晰，與業(yè)務(wù)的耦合比較低。缺點是：一個業(yè)務(wù)涉及的主從表不能在同一個報文中（這個缺點可以通過施工系統(tǒng)靈活的控制表之間關(guān)系來解決）；一個業(yè)務(wù)中可能會使用到兩個或兩個以上的接口，造成業(yè)務(wù)完整性上面的分離（這種缺點可以通過把業(yè)務(wù)放在一個事務(wù)中來解決）；鍵值的返回

33、：在調(diào)用新增接口之后，外協(xié)會按照記錄的順序返回外外協(xié)中所生成的鍵值。 施工單位獲得鍵值之后，可以在本地表中更新記錄的主鍵值。請求報文： <?xml version="1.0" encoding="utf-8"?><XmlData> <UserInfo> <User>ZhangSan</User> <PassWord>123456</PassWord> </UserInfo> <Description> <Note>開工報告</No

34、te> </Description> <Records> <Record> <KeyField></KeyField> <NormalField1>Value1</NormalField1> <NormalField2>Value2</NormalField2> <NormalField3>Value3</NormalField3> <NormalField4>Value4</NormalField4> </Record>

35、 <Record> <KeyField></KeyField> <NormalField1>Value1</NormalField1> <NormalField2>Value2</NormalField2> <NormalField3>Value3</NormalField3> <NormalField4>Value4</NormalField4> </Record> </Records></XmlData>響應(yīng)報文：<?

36、xml version="1.0" encoding="utf-8"?><XmlData> <Description> <Result>成功</Result> <!-如果失敗，則<Result>里面內(nèi)容是：失?。海ㄥe誤原因）-> </Description> <Records> <Record> <KeyField>Value1</KeyField> </Record> <Record> <

37、;KeyField>Value2</KeyField> </Record> </Records></XmlData>報文說明：標(biāo)簽名說明<XmlData>報文數(shù)據(jù)主體<Description>報文頭部信息<Records>記錄集合<Record>一行記錄<UserInfo>業(yè)務(wù)認(rèn)證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<Note>業(yè)務(wù)的簡單描述。比如：開工報告、施工組織方案 等請求中的<KeyField&g

38、t;一行記錄中的主鍵字段。在新增的時候，施工系統(tǒng)所給的主鍵字段內(nèi)容為空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容為空，認(rèn)為這是一條新增的記錄響應(yīng)中的<KeyField>一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系統(tǒng)發(fā)送的記錄的順序是一一對應(yīng)的。<Result>反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細(xì)信息）” 8.2.3 修改一條記錄施工系統(tǒng)在修改了一條記錄的時候，上傳的報文中與新增的報文類似，只是主鍵的信息不能為空。外協(xié)系統(tǒng)判斷主鍵的信息，如果發(fā)現(xiàn)主鍵的信息不為空，則認(rèn)為是修改了一條記錄。如果施工

39、系統(tǒng)報文中主鍵不為空，而外協(xié)系統(tǒng)在數(shù)據(jù)庫對應(yīng)的表中又沒有發(fā)現(xiàn)對應(yīng)的記錄，則自動轉(zhuǎn)換成新增的方式來處理這條記錄。外協(xié)系統(tǒng)在反饋中，還是會把主鍵返回給施工系統(tǒng)。但是，這種情況下，施工系統(tǒng)可能不再需要維護這個主鍵。即使是僅僅修改了一個字段，施工單位還得需要上傳全部的字段信息（包含被修改的字段）給外協(xié)系統(tǒng)。施工系統(tǒng)不是對記錄做物理刪除，而僅僅是作了邏輯刪除，即僅僅在記錄的刪除標(biāo)志位上面做了“1”的標(biāo)志。這種情況對記錄來說，也是修改的范圍。只是需要在<Note>業(yè)務(wù)的簡單描述中說明“邏輯刪除”。即使是邏輯刪除記錄，施工系統(tǒng)也必須上傳全部的字段到外協(xié)系統(tǒng)。 請求報文：<?xml vers

40、ion="1.0" encoding="utf-8"?><XmlData> <UserInfo> <User>ZhangSan</User> <PassWord>123456</PassWord> </UserInfo> <Description> <Note>停工通知確認(rèn)</Note> </Description> <Records> <Record> <KeyField>KeyV

41、alue1</KeyField> <NormalField1>Value1</NormalField1> <NormalField2>Value2</NormalField2> <NormalField3>Value3</NormalField3> <NormalField4>Value4</NormalField4> </Record> <Record> <KeyField>KeyValue2</KeyField> <NormalF

42、ield1>Value1</NormalField1> <NormalField2>Value2</NormalField2> <NormalField3>Value3</NormalField3> <NormalField4>Value4</NormalField4> </Record> </Records></XmlData>響應(yīng)報文：<?xml version="1.0" encoding="utf-8"?>&l

43、t;XmlData> <Description> <Result>成功</Result> <!-如果失敗，則<Result>里面內(nèi)容是：失?。海ㄥe誤原因）-> </Description> <Records> <Record> <KeyField>Value1</KeyField> </Record> <Record> <KeyField>Value2</KeyField> </Record> </Rec

44、ords></XmlData>報文說明：標(biāo)簽名說明<XmlData>報文數(shù)據(jù)主體<Description>報文頭部信息<Records>記錄集合<Record>一行記錄<UserInfo>業(yè)務(wù)認(rèn)證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<Note>業(yè)務(wù)的簡單描述。比如：開工報告、施工組織方案 等請求中的<KeyField>一行記錄中的主鍵字段。在修改的時候，施工系統(tǒng)所給的主鍵字段內(nèi)容不能為空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容不為空，認(rèn)為這是一條

45、修改的記錄響應(yīng)中的<KeyField>一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系統(tǒng)發(fā)送的記錄的順序是一一對應(yīng)的。<Result>反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細(xì)信息）”<NormalField>一行記錄中的英文字段名稱。實際中，這些標(biāo)簽都是字典的英文名。字段的標(biāo)簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型 8.2.4 刪除一條記錄這里的刪除指的是物理刪除。邏輯刪除在記錄修改的時候已經(jīng)說明。物理刪除是徹底的從數(shù)據(jù)庫中刪除一條記錄，不能恢復(fù)。物理刪除的時候，施工

46、系統(tǒng)只要在報文中提供主鍵的信息提交，就能夠?qū)崿F(xiàn)。同樣的，外協(xié)系統(tǒng)在反饋的報文中返回成功刪除主鍵的信息，如果其中一條記錄不能正常物理刪除，則外協(xié)自動回滾所有刪除的操作。即一條記錄不能刪除，則所有的記錄都不能刪除。請求報文：<?xml version="1.0" encoding="utf-8"?><XmlData> <UserInfo> <User>ZhangSan</User> <PassWord>123456</PassWord> </UserInfo> &

47、lt;Description> <Note>物理刪除</Note> </Description> <Records> <Record> <KeyField>Value1</KeyField> </Record> <Record> <KeyField>Value2</KeyField> </Record> </Records></XmlData>響應(yīng)報文：<?xml version="1.0" en

48、coding="utf-8"?><XmlData> <Description> <Result>成功</Result> <!-如果失敗，則<Result>里面內(nèi)容是：失?。海ㄥe誤原因），同時，KeyField的值為空-> </Description> <Records> <Record> <KeyField>Value1</KeyField> </Record> <Record> <KeyField>V

49、alue2</KeyField> </Record> </Records></XmlData>報文說明：（參見數(shù)據(jù)修改說明）8.2.5 文檔上傳外協(xié)系統(tǒng)中，文檔的信息是保存在另外的一個表中當(dāng)中的，所以，許多的業(yè)務(wù)表，往往存在一個FileID的主鍵關(guān)聯(lián)到文檔表。在業(yè)務(wù)表中檔，可能有一個FileID的字段，也可能會有兩個或兩個以上的FileID字段關(guān)聯(lián)到文檔信息表。涉及到文檔的地方，往往文檔的信息會比較大，所以，文檔的信息不能包含在基礎(chǔ)業(yè)務(wù)數(shù)據(jù)的報文當(dāng)中一起上傳。處理的方法是：先上傳文檔的實體，從反饋的信息當(dāng)中得到生成的文檔ID（FileID），然后

50、，施工系統(tǒng)在本地記錄中的相應(yīng)字段賦值文檔的ID，最后再上傳基本業(yè)務(wù)信息。如果一條記錄中包含有兩個或兩個以上的文檔字段，則施工系統(tǒng)必須依次上傳文檔獲得文檔ID之后，賦值，再上傳基本業(yè)務(wù)信息。一個文檔報文當(dāng)中，只能上傳一個文檔。文檔報文如下：<?xml version="1.0" encoding="utf-8"?><XmlData> <UserInfo> <User>ZhangSan</User> <PassWord>123456</PassWord> </UserI

51、nfo> <Description> </Description> <Records><Record> <ID></ID> <FILE_PRJ_ID>123456</FILE_PRJ_ID> <FILE_TYPE>401</FILE_TYPE> <FILE_NAME>施工組織方案.DOC</FILE_NAME> <FILE_UNIT>電信工程公司</FILE_UNIT> <FILE_MAN>張三</FIL

52、E_MAN><FILE_CREATE_TIME>20061031 153005</FILE_CREATE_TIME><FILE_AUTHOR>張三</FILE_AUTHOR><FILE_TITLE>項目XXX施工組織方案</FILE_TITLE><KeepMutiFile>1</KeepMutiFile> <FileData>/e5asfdfgafa#sdgsdg</FileData> </Record> </Records></XmlDa

53、ta>響應(yīng)報文：<?xml version="1.0" encoding="utf-8"?><XmlData> <Description> <Result>成功</Result> <!-如果失敗，則返回信息是“失?。海ㄥe誤信息）”-> </Description> <Records> <Record> <ID>123456</ID> </Record> </Records></XmlDat

54、a>報文說明：標(biāo)簽名說明<XmlData>報文數(shù)據(jù)主體<Description>報文頭部信息<Records>記錄集合<Record>一行記錄<UserInfo>業(yè)務(wù)認(rèn)證的用戶信息<User>業(yè)務(wù)用戶登錄名<PassWord>業(yè)務(wù)用戶驗證口令<ID>文檔的ID，在新增上傳一個文檔的時候，這個ID永遠(yuǎn)都是空的。外協(xié)系統(tǒng)根據(jù)這個文件ID是否為空來判斷是否是新的文件。<FILE_PRJ_ID>文檔所屬的項目ID，對于工程協(xié)作系統(tǒng)來說，一個文檔永遠(yuǎn)都是會屬于某個項目的。這個項目ID可以是一

55、級項目，也可以是三級項目。<FILE_TYPE>文件類型。標(biāo)識文件的歸類。比如：D401施工組織設(shè)計= 401D402施工項目計劃進度= 402D403施工日報= 403<FILE_TYPE>里面的值是代碼，文件類型的代碼可以從字典接口中獲得。<FILE_NAME>文檔的文件名稱，帶有擴展名。<FILE_UNIT>文件創(chuàng)建單位，中文名<FILE_MAN>文檔創(chuàng)建人(上傳人)<FILE_CREATE_TIME>文檔創(chuàng)建時間<FILE_AUTHOR>文檔作者 （可為空）<FILE_TITLE>文檔標(biāo)題

56、（可為空）<KeepMutiFile>是否允許多個文檔同時有效。這個標(biāo)簽的值為 1 或 0。當(dāng)值為1 的時候，則在同樣的項目ID、同樣的文件類型中，同時可以存在多個的文檔同時有效存在。這種情況下，多個文檔之間是兄弟之間的關(guān)系，當(dāng)前的文檔是弟弟，以前的文檔是兄長。當(dāng)這個值為0的時候，則在同樣的項目ID、同樣的文件類型中，只有最后上傳的文檔有效，后面上傳的文檔會把前面的文檔“擠”到歷史中，成為當(dāng)前文檔的“父親”。這種情況下，當(dāng)前的文檔和以前上傳的文檔之間是父子的關(guān)系。更詳細(xì)的解釋請參見后面的“一條記錄中一個FileID的字段如何上傳多個文件”主題相關(guān)內(nèi)容。<FileData>

57、;文件實體內(nèi)容。文件實體內(nèi)容用二進制讀取出來之后，然后轉(zhuǎn)換成base64的格式。<Result>反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細(xì)信息）”8.2.6 一條記錄中一個文檔字段上傳多個文件外協(xié)系統(tǒng)中，文檔是以一種“有關(guān)系”的方式來存儲的。假設(shè)有這樣一個業(yè)務(wù)表Table1，里面有一個文檔的外鍵字段File_ID。當(dāng)我們往Table1表里面插入一條記錄的時候，針對這一條記錄，我們希望在File_ID字段中可以帶有多個的文檔，也即會有多個的File_ID。當(dāng)然，我們可以把這個表字段的數(shù)據(jù)模型這個定義：File1_ID，

58、File2_ID,File3_ID，需要多少個文件，我們就定義幾個的File_ID字段。但是這樣就會帶來問題了，如果你定義了5個的File_ID字段，但是，用戶如果想在一條記錄中上傳6個文檔，那么，這樣的數(shù)據(jù)模型就會滿足不了用戶的要求。還有一種情況，如果用戶僅僅上傳了2個文檔，那么剩下的3個File_ID字段就會白白空著。甚至用戶對這條記錄沒有上傳文件，這樣定義的數(shù)據(jù)模型就白白浪費了數(shù)據(jù)庫的資源。還有一種說法，我可以用記錄的形式來表示啊。對的。上傳多個文件，是可以在Table1中新增多條記錄方式來表示。但是，我們的前提是，Table1是一個業(yè)務(wù)表，里面的一條記錄就是一筆業(yè)務(wù)。如果你產(chǎn)生了多條記

59、錄，那么意味這這樣的業(yè)務(wù)進行了多次。顯然違背了業(yè)務(wù)數(shù)據(jù)保存的初衷。外協(xié)系統(tǒng)引入了“父子”，“兄弟”的文檔保存機制, 即在文檔信息表(Files表)中保存文檔的基本信息和他們之間的關(guān)系。在同樣的項目ID、同樣的文件類型中，如果可以存在多個的文檔同時有效存在，這種情況下，多個文檔之間是兄弟之間的關(guān)系。后來者文檔是弟弟，先到的文檔是兄長。在同樣的項目ID、同樣的文件類型中，只有最后上傳的文檔有效，后面上傳的文檔會把前面的文檔“擠”到歷史中，成為當(dāng)前文檔的“父親”。這種情況下，后來的文檔和以前上傳的文檔之間是父子的關(guān)系。如果文檔之間是兄弟關(guān)系的話，則僅僅在業(yè)務(wù)表Table1中保存最小兄弟的File_ID；如果文檔之間是父子關(guān)系的話，則僅僅保存最小輩分的文檔File_ID。 兄弟和父子的文檔保存方式其實都是多個文檔串聯(lián)的一種保存方式，但是，還是會有使用上面的區(qū)別的。兄弟關(guān)系一般使用在文檔之間是平級的情況下。比如施工組織方案，可以有多個文件，但是，這多個文件是互為補充的一部分，互相依賴，又缺一不可。這種情況下，施工系統(tǒng)可以把這類型的文件上傳給外協(xié)系統(tǒng)，以兄弟的方式保存，施工系統(tǒng)僅僅在業(yè)務(wù)