【文章內容簡介】 數的方式。報文中數值的單位使用國標的單位，比如貨幣使用“元”，長度使用“米”等。無 國標的單位以約定為準。 ? 報文中的日期信息，轉換成 YYYYMMDD HHmmss 文本格式（ 24 小時制）。如果是空日期，則轉換成空文本。 ? 報文中的 true 和 false 數據類型，轉換成 0(表示 false)、 1（表示 true） ? 報文中的二進制數據，轉換成 Base64字符方式發(fā)送。 ? 報文中的記錄集，放在 Records標簽中；報文中一條記錄，放在 Records標簽中。 ? 報文中如果存在多條記錄，則在 Records標簽中就包含 多個的 Record標簽。如果報文中僅有一條記錄，則 Records標簽中只包含一個 Record標簽 .如果沒有記錄，則僅僅包含一個 Records標簽 ,沒有 Record標簽。 ? 如果返回結果數據集非常多，在性能考慮和數據量沖突的情況下，可以使用分頁返回數據集的方式分批返回數據（每次返回最多 100 條記錄）。服務端提供分批結果返回的功能。至于如何使用分頁查詢的功能，參見下面的 XML 框架說明。 施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求 施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請求的數據目前有幾點需要考慮 ： ? 如何請求查詢一個業(yè)務數據 ? 如何新增一條記錄，新增之后如何點到記錄的鍵值 ? 如何修改一條記錄 ? 如何刪除一條記錄 ? 文檔如何上傳 ? 一條記錄中一個 FileID 的字段如何上傳多個文件 ? 如何在一條記錄中補充上傳文檔 ? 如何在一條記錄中刪除一個文檔 ? 如何獲得文檔的基本信息 ? 如何獲得文檔的所有兄弟信息 ? 如何獲得文檔的所有父親信息 ? 如何 下載一個文檔 針對這些問題，接口方案的解決方法如下： 請求查詢一個業(yè)務數據 施工系統(tǒng)針對外協(xié)系統(tǒng)發(fā)送的業(yè)務數據查詢請求根據業(yè)務類型有很多種。為了簡化接口，而不是在接口上進行業(yè)務操作，所以，外協(xié)系統(tǒng)將施工系統(tǒng)發(fā)起的數據查詢請求看作是數據下載的一種方式，而不為了復雜的業(yè)務查詢請求提供復雜的條件解析。 外協(xié)系統(tǒng)提供的數據查詢接口是從數據下載和數據延期性來考慮的。為了滿足數據的下載，外協(xié)系統(tǒng)提供了按照某一個表的主鍵來下載數據和按照記錄的變更時間范圍來下載數據的兩種方式查詢請求。 請求報文： ?xml version= encoding=utf8 ? XmlData UserInfo UserZhangSan/User PassWord123456/PassWord /UserInfo Description RowID0/RowID KeyValue123/KeyValue QueryBeginTime20202018 153000/QueryBeginTime QueryEndTime20202019 153000/QueryEndTime /Description /XmlData 響應報文： ?xml version= encoding=utf8? XmlData Description RowID100/RowID /Description Records Record Field1Value1/Field1 Field2Value2/Field2 Field3Value3/Field3 Field4Value4/Field4 /Record Record Field1Value1/Field1 Field2Value2/Field2 Field3Value3/Field3 Field4Value4/Field4 /Record Record Field1Value1/Field1 Field2Value2/Field2 Field3Value3/Field3 Field4Value4/Field4 /Record /Records /XmlData 報文說明： 標簽名 說明 XmlData 報文數據主體 Description 報文頭部信息 Records 記錄集合 Record 一行記錄 UserInfo 業(yè)務認證的用戶信 息 User 業(yè)務用戶登錄名 PassWord 業(yè)務用戶驗證口令 RowID 第一次請求的時候，客戶端 RowID 發(fā)送 0，表示從第 0 條記錄開發(fā)返回。服務端根據條件查詢，發(fā)現結果超過 100 條記錄，則在返回的結果中， RowID的值為 99，表示服務端當前的記錄位置處在第 100條的位置上，后面還會有剩余的記錄。客戶端檢查返回的結果，如果發(fā)現 RowID 大于 0,則繼續(xù)發(fā)送請求進行查詢。但是，客戶端第二次發(fā)送請求繼續(xù)查詢的時候， RowID的值要賦值為第一次返回的值，即RowID=99。服務端第二次收到請求 的時候，發(fā)現 RowID 是 99,則從第100條返回結果。以此類推循環(huán)調用，直到服務端達到記錄的末尾，這時候，服務端在返回的結果中 RowID= RowID=0，終止循環(huán)調用。 字典、用戶信息、單位信息，因為返回的字段比較少，不受 100條記錄返回的限制。一次調用，就返回全部的結果。 KeyValue 查詢時主鍵的值。這個 KeyValue和下面的QueryBeginTimeQueryEndTime是互斥的。如果在請求的時候提供了主鍵的值，表示客戶端要求服務器按照主鍵的值查詢一條記 錄。如果客戶端提供了主鍵的值，則服務端將忽略QueryBeginTimeQueryEndTime中的值。 字典、用戶信息、單位信息，因為沒有查詢時間范圍，所以KeyValue即表示字典類型。 QueryBeginTime QueryEndTime 查詢時時間段范圍。 QueryBeginTime是起始時間，QueryEndTime是結束時間。表示客戶端要求服務端查詢在這個時間范圍之內所有變更過的記錄（包括新增、修改、刪除）。 在外協(xié)中，一條記錄新增的時候，它的創(chuàng)建時間和最后修改時 間是一樣的，以后修改記錄的時候，創(chuàng)建時間不變，改變的僅僅是最后修改時間。同時，外協(xié)系統(tǒng)中刪除記錄僅僅在“記錄是否刪除”字段中標記“ 1”，并不是真正的物理刪除記錄。 這里的時間指的是記錄變更的時間，不是記錄中的某個業(yè)務時間。如果用戶需要按照業(yè)務時間來查詢數據，則施工系統(tǒng)把外協(xié)系統(tǒng)的數據獲取到本地進行保存，在施工系統(tǒng)中提供按照業(yè)務時間查詢的功能。 QueryBeginTimeQueryEndTime和 KeyValue是互斥的。如果客戶端需要按照時間范圍來查詢，則必須 KeyValue空。 Field1 Field2 Field3 Field4 一行記錄中的英文字段名稱。實際中，這些標簽都是字典的英文名。字段的標簽全部是大寫。 具體的字段名稱請參見提供的數據模型 新增一條記錄，得到記錄的鍵值 為了簡化數據模型的處理，本方案不考慮主從表的并發(fā)處理情況。如果存在主從表的數據需要上傳，那么，在一個事務中，施工單位首先先上傳主表的記錄，從反饋信息中獲得主表的主鍵值。然后，把剛剛獲得的主表的主鍵值賦值給從表的對應外鍵，再上傳從表數據，得到從表的主鍵值。 如果不是主從表，而 是單表，則直接上傳數據，從反饋信息中得到主鍵值。 這種情況的優(yōu)點是：數據和表相關，施工單位可以靈活的控制表之間的關系；同時，數據包中的報文比較簡單，容易解析；接口上面比較清晰，與業(yè)務的耦合比較低。 缺點是：一個業(yè)務涉及的主從表不能在同一個報文中（這個缺點可以通過施工系統(tǒng)靈活的控制表之間關系來解決）；一個業(yè)務中可能會使用到兩個或兩個以上的接口，造成業(yè)務完整性上面的分離（這種缺點可以通過把業(yè)務放在一個事務中來解決）； 鍵值的返回：在調用新增接口之后，外協(xié)會按照記錄的 順序 返回外外協(xié)中所生成的鍵值。 施工單位獲得鍵 值之后，可以在本地表中更新記錄的主鍵值。 請求報文： ?xml version= encoding=utf8? XmlData UserInfo UserZhangSan/User PassWord123456/PassWord /UserInfo Description Note開工報告 /Note /Description Records Record KeyField/KeyField NormalField1Value1/NormalField1 NormalField2Value2/NormalField2 NormalField3Value3/NormalField3 NormalField4Value4/NormalField4 /Record Record KeyField/KeyField NormalField1Value1/NormalField1 NormalField2Value2/NormalField2 NormalField3Value3/NormalField3 NormalField4Value4/NormalField4 /Record /Records /XmlData 響應報文： ?xml version= encoding=utf8? XmlData Description Result成功 /Result !如果失敗，則 Result里面內容是：失敗：（錯誤原因） /Description Records Record KeyFieldValue1/KeyField /Record Record KeyFieldValue2/KeyField /Record /Records /XmlData 報文說明： 標簽名 說明 XmlData 報文數據主體 Description 報文頭部信息 Records 記錄集合 Record 一行記錄 UserInfo 業(yè)務認證的用戶信息 User 業(yè)務用戶登錄名 PassWord 業(yè)務用戶驗證口令 Note 業(yè)務的簡單描述。比如：開工報告、施工組織方案 等 請求中的 KeyField 一行記錄中的主鍵字段。在新增的時候，施工系統(tǒng)所給的主鍵字段內容為空。外協(xié)系統(tǒng)中根據主鍵字段內容為空，認為這是一條新增的記錄 響應中的 KeyField 一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系統(tǒng)發(fā)送的記錄的順序是一一對應的。 Result 反饋報文中的保存成功與否信息。 如果保存成功，則信息是“成功” 如果保存失敗，則信息是“失?。海ê竺媸清e 誤的詳細信息）” 修改一條記錄 施工系統(tǒng)在修改了一條記錄的時候，上傳的報文中與新增的報文類似，只是主鍵的信息不能為空。外協(xié)系統(tǒng)判斷主鍵的信息，如果發(fā)現主鍵的信息不為空，則認為是修改了一條記錄。如果施工系統(tǒng)報文中主鍵不為空，而外協(xié)系統(tǒng)在數據庫對應的表中又沒有發(fā)現對應的記錄，則自動轉換成新增的方式來處理這條記錄。 外協(xié)系統(tǒng)在反饋中，還是會把主鍵返回給施工系統(tǒng)。但是，這種情況下，施工系統(tǒng)可能不再需要維護這個主鍵。 即使是僅僅修改了一個字段，施工單位還得需要上傳全部的字段信 息（包含被修改的字段）給外協(xié)系統(tǒng)。 施工系統(tǒng)不是對記錄做物理刪除，而僅僅是作了邏輯刪除，即僅僅在記錄的刪除標志位上面做了“ 1”的標志。這種情況對記錄來說，也是修改的范圍。只是需要在 Note業(yè)務的簡單描述中說明“邏輯刪除”。即使是邏輯刪除記錄，施工系統(tǒng)也必須上傳全部的字段到外協(xié)系統(tǒng)。 請求報文： ?xml version= encoding=utf8? XmlData UserInfo UserZhangSan/User PassWord123456/PassWord /UserInfo