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

1、文檔編號：T-JKJS文檔版本：0.01項目編號：XX-DX-PECSXX電信工程外部協(xié)作系統(tǒng)Project Exterior Cooperati onSystem施工單位接口技術(shù)解決方案編寫人：南瘋?cè)掌冢?006-10-30審核人：日期：批準(zhǔn)人：日期：XXXXX信息科技股份有限公司地址：XXXXXXX由E編：XXXXXX電話：XXXXXXXX傳真：XXXXXX網(wǎng)站：XXXXXXXXX修改記錄(RevisionChart )版本號批準(zhǔn)人修改人修0.01南瘋2006-10-300.02詳細修改記錄:1.2 覆蓋范圍1.3 預(yù)期讀者與閱讀建議3 接口方式4 接口安全4.1 接口認(rèn)證-4.2數(shù)據(jù)安全

2、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修改一條記錄.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ù)8.3.2發(fā)送變更后的字典 一833文檔發(fā)送請求9 信息數(shù)據(jù)

3、項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)項目組施工系統(tǒng)接口開發(fā)技術(shù)組1.3預(yù)期讀者與閱讀建議XX電信企業(yè)信息化部XX電信工程建設(shè)部XXXX公司開發(fā)人員 施工系統(tǒng)開發(fā)人員1.4文檔約定粗體正文

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)的目標(biāo)，是在工程項目的管理、建設(shè)、使用和實施單位之間 搭建起數(shù)據(jù)交換和協(xié)同工作的信息平臺，延伸與拓展工程建設(shè)管理信息化的應(yīng)用范圍，實現(xiàn)通 信工程建設(shè)過程的信息化管理，促進工程項目的管理部門、建設(shè)部門、實施部門和使用部門之 間業(yè)務(wù)流程協(xié)調(diào)有序地開展，實現(xiàn)工程項目設(shè)計、施工、監(jiān)理管理功能，將相關(guān)的設(shè)計、施工、 監(jiān)理單位納入到工程

5、建設(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)的接口，實現(xiàn)工程部與三家實施單位的信息交互與業(yè)務(wù)協(xié) 作；本技

6、術(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ù)傳輸采用XML數(shù)據(jù)交換格式，utf-8編碼。在外協(xié)系統(tǒng)中提

7、供 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)系。夕卜協(xié)系統(tǒng)要求能夠有目的，信息有過濾的把業(yè)務(wù)信息通過接口正確

8、的發(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ù)，也會主動請求外協(xié)系統(tǒng)發(fā)送數(shù)據(jù)。4 接口安全4.1 接口認(rèn)證調(diào)用認(rèn)證

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

10、b服務(wù)（通過Mach in e.c onfig 中的processModel 元素來酉2置）。接口不支持動態(tài)生成WSDL因此作為服務(wù)端，應(yīng)該禁止文檔協(xié)議。在服務(wù)端禁用跟蹤，禁用調(diào)式編譯業(yè)務(wù)用戶認(rèn)證：由于接口涉及電信工程中的各個不同的業(yè)務(wù)，有獲取字典、獲得項目信息、發(fā)送開工 報告等，所以，建立一套業(yè)務(wù)的用戶認(rèn)證機制是必須的。不同的用戶，所具備有的授權(quán)不 一樣，所能執(zhí)行的業(yè)務(wù)也不一樣。同時，業(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)限

11、，應(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ù)在傳輸?shù)倪^程中的數(shù)據(jù)的完整性兩個方面。Web Service采用XML數(shù)據(jù)格式來傳輸信息。所以，無論是發(fā)送數(shù)據(jù)還是返回結(jié)果,都要求采用對XML數(shù)據(jù)加密之后來傳輸。至于采用何種方式的加密技術(shù)，本方案為了保密，只能

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

13、e）對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ù)據(jù)的 任何更改是永久的。不論系統(tǒng)崩潰或是發(fā)生其他無法預(yù)料的事件，更改都必須是持久的。 即使只有一個參與者無法保證這一點，整個事務(wù)也將失敗，在事務(wù)范圍內(nèi)對數(shù)據(jù)的任何更 改均將回滾。外協(xié)系統(tǒng)和施工系統(tǒng)是處于網(wǎng)絡(luò)之上的兩個分布式接口，

14、使用的是分布式事務(wù)。要啟 用分布式事務(wù)，可能需要通過網(wǎng)絡(luò)啟用MS DTC （考慮外協(xié)平臺和施工平臺都是運行在Windows上），以便在使用應(yīng)用了最新的 Service Pack的較新操作系統(tǒng)（例如WindowsXP或 Windows 2003）時使用分布式事務(wù)。如果啟用了Windows防火墻（Windows XPService Pack 2的默認(rèn)設(shè)置），必須允許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ù)會造成性能損失，因 為可能需要繼承原來的上下文，但

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

16、于消息的編程而不是遠程過程調(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ù)不能正常傳輸。 這樣，客戶端應(yīng)該能夠記錄發(fā)送的日志，按照一定的時間間隔重試發(fā)送。本

17、方案 定為重試發(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)當(dāng)能夠捕捉異常信息，比如“非法XML格式”等，然后反饋給客戶端。客戶端在接受到這類的錯誤信息之后，應(yīng)當(dāng)進仃日志記錄，能夠自動或手工分析異常的信息。網(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ù)格

18、式在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格式?？蛻舳税l(fā)送請求報文，服 務(wù)器解析調(diào)用報文，執(zhí)行報文中所在接口對應(yīng)的服務(wù)功能。生成結(jié)果報文，以xml格式頁返回給請求者。請求者拿到結(jié)果報文，進行解析，然后再進行相應(yīng)的處理。8.1 約定報文中所有的字典信息（比如性別 1-男，2-女），都以代碼的值（1或者2）來傳遞。施 工單位向外協(xié)系統(tǒng)發(fā)送的報文中的代碼都需要轉(zhuǎn)

19、換成外協(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 nt5012368.36報文中數(shù)值不支持科學(xué)計數(shù)的方式。報文中數(shù)值的單位使用國標(biāo)的單位，比如貨幣使 用“元”，長度使用“米”等。無國標(biāo)的單位以約定為準(zhǔn)。報文中的日期信息，轉(zhuǎn)換成 YYYYMMDtHHmms文本格式（24小時制）。如果是空日期， 則轉(zhuǎn)換成空文本。報文中的true和false數(shù)據(jù)類型，轉(zhuǎn)換成 0（表示false）、1 （表示true）

20、 報文中的二進制數(shù)據(jù)，轉(zhuǎn)換成 Base64字符方式發(fā)送。報文中的記錄集，放在 Records標(biāo)簽中；報文中一條記錄，放在 Records標(biāo)簽中。報文中如果存在多條記錄，則在 Records標(biāo)簽中就包含多個的Record標(biāo)簽。如果報 文中僅有一條記錄，則Records標(biāo)簽中只包含一個Record標(biāo)簽.如果沒有記錄，則僅僅 包含一個vRecords標(biāo)簽，沒有Record標(biāo)簽。如果返回結(jié)果數(shù)據(jù)集非常多，在性能考慮和數(shù)據(jù)量沖突的情況下，可以使用分頁返回 數(shù)據(jù)集的方式分批返回數(shù)據(jù)（每次返回最多100條記錄）。服務(wù)端提供分批結(jié)果返回的功能。至于如何使用分頁查詢的功能，參見下面的XML匡架說明。8.2施工系

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

22、請求看作是數(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 Userlnfo ZhangSan 123456 0 123 20061018153000 20061019153000 響應(yīng)報文： 100 Value1 Value2 Value3 Value4 Value1 Value2 Value3 Va

23、lue4 Value1 Value2 Value3 Value4Records報文說明：1標(biāo)簽名說明報文數(shù)據(jù)主體報文頭部信息 vUserlnfo vQueryBeg in Time vQueryE ndTime記錄集合一行記錄業(yè)務(wù)認(rèn)證的用戶信息業(yè)務(wù)用戶登錄名 業(yè)務(wù)用戶驗證口令第一次請求的時候，客戶端 RowID發(fā)送0,表示從第0條記錄開發(fā)返 回。服務(wù)端根據(jù)條件查詢，發(fā)現(xiàn)結(jié)果超過100條記錄，則在返回的結(jié)果中，RowID的值為99，表示服務(wù)端當(dāng)前的記錄位置處在第100條的位置上，后面還會有剩余的記錄?？蛻舳藱z查返回的結(jié)果，如果發(fā)現(xiàn)RowID大于0,則繼續(xù)發(fā)送請求進行查詢。但是，客戶端第二次發(fā)送請

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

25、端提供了主鍵的值，則服務(wù)端將忽略vQueryBegi nTimexQueryE ndTime 中的值。字典、用戶信息、單位信息，因為沒有查詢時間范圍，所以 vKeyValue即表示字典類型。查詢時時間段范圍。vQueryBeg in Time 是起始時間，vQueryE ndTime是結(jié)束時間。表示客戶端要求服務(wù)端查詢在這個時間范 圍之內(nèi)所有變更過的記錄（包括新增、修改、刪除）。在外協(xié)中，一條記錄新增的時候，它的創(chuàng)建時間和最后修改時間是 一樣的，以后修改記錄的時候，創(chuàng)建時間不變，改變的僅僅是最后修改 時間。同時，外協(xié)系統(tǒng)中刪除記錄僅僅在“記錄是否刪除”字段中標(biāo)記“ 1”，并不是真正的物理刪除記

26、錄。這里的時間指的是記錄變更的時間，不是記錄中的某個業(yè)務(wù)時間。 如果用戶需要按照業(yè)務(wù)時間來查詢數(shù)據(jù)，則施工系統(tǒng)把外協(xié)系統(tǒng)的數(shù)據(jù) 獲取到本地進行保存，在施工系統(tǒng)中提供按照業(yè)務(wù)時間查詢的功能。vQueryBegi nTimexQueryE ndTimeH vKeyValue是互斥的。如果客 戶端需要按照時間范圍來查詢，則必須 vKeyValue 空。一行記錄中的英文字段名稱。實際中，這些標(biāo)簽都是字典的英文名。字 段的標(biāo)簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型8.2.1新增一條記錄，得到記錄的鍵值為了簡化數(shù)據(jù)模型的處理，本方案不考慮主從表的并發(fā)處理情況。如果存在主從表的數(shù)據(jù)需要上傳，那么，在

27、一個事務(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ù)中來解決）；鍵值的返回：

28、在調(diào)用新增接口之后，外協(xié)會按照記錄的順序返回外外協(xié)中所生成的鍵值。施工單位獲得鍵值之后，可以在本地表中更新記錄的主鍵值。請求報文：v? xml version=1.0encoding=utf-8? ZhangSan 123456 開工報告 / Value1 Value2 Value3 Value4 Value1 Value2 Value3 Value4?響應(yīng)報文：? xml version=1.0encoding=utf-8成功!-如果失敗，則 里面內(nèi)容是：失敗：（錯誤原因）- Valuel Value2 報文說明：標(biāo)簽名說明報文數(shù)據(jù)主體vDescripti on 報文頭部信息記錄集合一行記錄

29、vUserlnfo 業(yè)務(wù)認(rèn)證的用戶信息業(yè)務(wù)用戶登錄名業(yè)務(wù)用戶驗證口令業(yè)務(wù)的簡單描述。比如：開工報告、施工組織方案等請求中的vKeyField 一行記錄中的主鍵字段。在新增的時候，施工系統(tǒng)所給的主鍵字段內(nèi)容 為空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容為空，認(rèn)為這是一條新增的記錄響應(yīng)中的vKeyField 一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工 系統(tǒng)發(fā)送的記錄的順序是一一對應(yīng)的。vResult 反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失敗：（后面是錯誤的詳細信息）”8.2.3 修改一條記錄施工系統(tǒng)在修改了一條記錄的時候，上傳的報文中與新增的

30、報文類似，只是主鍵的信息不能為 空。外協(xié)系統(tǒng)判斷主鍵的信息，如果發(fā)現(xiàn)主鍵的信息不為空，則認(rèn)為是修改了一條記錄。如果施工 系統(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)志。這種情況對記錄來說，也是修改的范圍。只是需要在業(yè)務(wù)的簡單描述中說明“邏輯

31、刪除”。即使是邏輯刪除記錄，施工系統(tǒng)也必須上傳全部的字段到外協(xié)系統(tǒng)。?請求報文：? xml version=1.0encoding=utf-8 ZhangSan 123456停工通知確認(rèn) KeyValue1 Value1 Value2 Value3 Value4 KeyValue2 Value1 Value2 Value3 Value4響應(yīng)報文:成功!-如果失敗，則 里面內(nèi)容是：失?。海ㄥe誤原因）- Valuel Value2 報文說明:1標(biāo)簽名說明報文數(shù)據(jù)主體報文頭部信息記錄集合一行記錄vUserlnfo 業(yè)務(wù)認(rèn)證的用戶信息業(yè)務(wù)用戶登錄名業(yè)務(wù)用戶驗證口令業(yè)務(wù)的簡單描述。比如：開工報告、施工組

32、織方案等請求中的vKeyField 一行記錄中的主鍵字段。在修改的時候，施工系統(tǒng)所給的主鍵字段內(nèi)容 不能為空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容不為空，認(rèn)為這是一條修改的 記錄響應(yīng)中的vKeyField 一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工 系統(tǒng)發(fā)送的記錄的順序是一一對應(yīng)的。vResult 反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細信息）”vNormalField 一行記錄中的英文字段名稱。實際中，這些標(biāo)簽都是字典的英文名。字 段的標(biāo)簽全部是大寫。具體的字段名稱請參見提供的數(shù)據(jù)模型8.2.4刪除一條記錄這里的刪

33、除指的是物理刪除。邏輯刪除在記錄修改的時候已經(jīng)說明物理刪除是徹底的從數(shù)據(jù)庫中刪除一條記錄，不能恢復(fù)。物理刪除的時候，施工系統(tǒng)只要在報 文中提供主鍵的信息提交，就能夠?qū)崿F(xiàn)。同樣的，外協(xié)系統(tǒng)在反饋的報文中返回成功刪除主鍵的信息，如果其中一條記錄不能正常物理 刪除，則外協(xié)自動回滾所有刪除的操作。即一條記錄不能刪除，則所有的記錄都不能刪除。請求報文：vUserlnfo Zha ngSar123456vDescription 物理刪除 vKeyField Value1 Value2 響應(yīng)報文：成功!-如果失敗，則里面內(nèi)容是：失?。海ㄥe誤原因）,同時，KeyField的值為空-Value1 Value2

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

35、檔獲得文檔ID之后，賦值，再上傳基本業(yè)務(wù)信息。一個文檔報文當(dāng)中，只能上傳一個文檔。 文檔報文如下：v?xml versio n=1.0en cod in g=utf-8 ?vUserlnfo Zha ngSarv/ User123456vDescription 123456 401FILE_NAME施工組織方案.DO/FILE_NAME 電信工程公司 FILE_MAN 張三 / FILE_MANFILE_CREATE_TIME0061031 153005E 張三 /FILE_AUTHOR項目 XXX施工組織方案 vKeepMutiFile 1 vFileData /e5asfdfgafa#sd

36、gsdg 響應(yīng)報文：成功 123456 報文說明：標(biāo)簽名說明報文數(shù)據(jù)主體vDescripti on 報文頭部信息記錄集合一行記錄vUserlnfo 業(yè)務(wù)認(rèn)證的用戶信息業(yè)務(wù)用戶登錄名業(yè)務(wù)用戶驗證口令文檔的ID，在新增上傳一個文檔的時候，這個ID永遠都是空的。外協(xié)系 統(tǒng)根據(jù)這個文件ID是否為空來判斷是否是新的文件。文檔所屬的項目ID，對于工程協(xié)作系統(tǒng)來說，一個文檔永遠都是會屬于 某個項目的。這個項目ID可以是一級項目，也可以是三級項目。文件類型。標(biāo)識文件的歸類。比如：D401施工組織設(shè)計=401D402施工項目計劃進度=402D403施工日報=403vFILE TYP匡里面的值是代碼，文件類型的代

37、碼可以從字典接口中獲得。FILE_NAME文檔的文件名稱，帶有擴展名。文件創(chuàng)建單位，中文名文檔創(chuàng)建人（上傳人）vFILE_CREATE_TIME文檔創(chuàng)建時間FILE_AUTHOR文檔作者（可為空）文檔標(biāo)題（可為空）vKeepMutiFile 是否允許多個文檔同時有效。這個標(biāo)簽的值為1或0。當(dāng)值為1的時候，則在同樣的項目ID、同樣的文件類型中，同時可以存在多個的文檔同時 有效存在。這種情況下，多個文檔之間是兄弟之間的關(guān)系，當(dāng)前的文檔 是弟弟，以前的文檔是兄長。當(dāng)這個值為 0的時候，則在同樣的項目ID、 同樣的文件類型中，只有最后上傳的文檔有效，后面上傳的文檔會把前 面的文檔“擠”到歷史中，成為當(dāng)

38、前文檔的“父親”。這種情況下，當(dāng)前 的文檔和以前上傳的文檔之間是父子的關(guān)系。更詳細的解釋請參見后面的“一條記錄中一個FilelD的字段如何上傳多個文件”主題相關(guān)內(nèi)容。vFileData 文件實體內(nèi)容。文件實體內(nèi)容用二進制讀取岀來之后，然后轉(zhuǎn)換成base64的格式。vResult 反饋報文中的保存成功與否信息。如果保存成功，則信息是“成功”如果保存失敗，則信息是“失?。海ê竺媸清e誤的詳細信息）”826 條記錄中一個文檔字段上傳多個文件外協(xié)系統(tǒng)中，文檔是以一種“有關(guān)系”的方式來存儲的。假設(shè)有這樣一個業(yè)務(wù)表Tabie1 ，里面有一個文檔的外鍵字段File_ID 。當(dāng)我們往Tablel表里面插入一條記

39、錄的時候，針對這一條記 錄，我們希望在File_ID字段中可以帶有多個的文檔，也即會有多個的File_ID 。當(dāng)然，我們可以把這個表字段的數(shù)據(jù)模型這個定義：FilelD，F(xiàn)ile2_ID,File3_ID，需要多少個文件，我們就定義幾個的File ID字段。但是這樣就會帶來問題了，如果你定義了5個的File ID 字段，但是，用戶如果想在一條記錄中上傳6個文檔，那么，這樣的數(shù)據(jù)模型就會滿足不了用戶的要求。還有一種情況，如果用戶僅僅上傳了2個文檔，那么剩下的3個File_ID字段就會白白空著。甚至用戶對這條記錄沒有上傳文件，這樣定義的數(shù)據(jù)模型就白白浪費了數(shù)據(jù)庫的資源。還有一種說法，我可以用記錄的

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