1、523392482.doc BOS接口開發(fā)指南 目錄 BOS接口開發(fā)指南 1 1.1 概述1 1.1.1 設(shè)計思想1 1.1.2 Portal框架簡介 錯誤！未定義書簽。 1.2 身份認(rèn)證2 1.3 數(shù)據(jù)格式2 1.3.1 必選參數(shù)2 1.3.2 業(yè)務(wù)參數(shù)3 1.3.3 返回內(nèi)容 3 1.4 命令4 1.4.1 ObjectCreate 4 1.4.2 ObjectModify 4 1.4.3 ObjectDelete 5 1.4.4 ObjectSubmit 5 1.4.5 ObjectUnsubmit 5 1.4.6 ProcessOrder6 1.4.7 ExecuteWebAct io

2、n 7 1.4.8 Import 7 1.4.9 Query 8 1.4.10 GetObject 10 1.4.11 ExecuteSQL 10 1.4.12 ExecuteBatch 11 1.4.13 ExecuteAudit 11 1.4.14 SendSMS 12 1.1概述 1.1.1設(shè)計思想 我們將可快速開發(fā)作為首要設(shè)計出發(fā)點(diǎn)。 目前的web接口主要有以下幾種方式 xml-rpc soap rest 作為輕量級的接口設(shè)計模型，rest具有開發(fā)快速，接口完全自定義的特點(diǎn)，考慮以此模式進(jìn) 行。 由于網(wǎng)站接口的上傳和下載數(shù)據(jù)都比較大，封裝這些數(shù)據(jù)的方法在XML和JSON之間考 慮，JS

3、ON的特點(diǎn)就是簡單，相比XML有以下問題： 1. 沒有命名空間 n amespace 2. 不像xml那樣區(qū)分屬性 attribute和元素element 3. 不支持屬性的排放順序控制 我們的系統(tǒng)里不存在多個namespace,且都可以element來顯示，另外用數(shù)組來控制元素間 的順序，以JSON來封裝數(shù)據(jù)是可行的。 在服務(wù)器上給出專用URL來處理所有接口內(nèi)容： http:/portal.server/servlets/binserv/Rest ? transactions=%5B%7B%22id%22%3A112%2C%22command%22%3A%22ProcessOrder%22%

4、2C%22 params%22%3A%7B%22id%22%3A1327%2C%22table%22%3A12948%7D%7D%5D 需要提供用戶名 在Http body里有處理結(jié)果，為JSON格式 tra nsact ion-resp on se,. tran sact ion-resp on se: id:, code: , message:, :, 一個transaction里的多個操作將全部成功，或全部失敗，code=0表示成功，其他都為失敗， 失敗的信息在 message里 1.4命令 命令說明：在命令中都涉及到定位記錄在數(shù)據(jù)庫中位置的請求操作，一般可以通過ID來定 位，若不清楚I

5、D位置，可以通過傳輸 AK值來進(jìn)行定位。若仍然不行，系統(tǒng)提供額外的存 儲過程開發(fā)來支持相關(guān)數(shù)據(jù)檢索。一般形式如： id_find: procedurename（value1,） ld_find 為標(biāo)準(zhǔn)屬性名稱， procedure name需要按明確命名規(guī)則 fd_xxx 來進(jìn) 行，函數(shù)參數(shù)可以根據(jù)需求任意設(shè)定。例如，若要根據(jù)手機(jī)號搜索用戶（users）,應(yīng)該命名 為fd_users_by_phone。通過存儲過程命名規(guī)則，防止調(diào)用者執(zhí)行非預(yù)定存儲過程。 1.4.1 ObjectCreate 用于創(chuàng)建新的記錄。 特別說明：關(guān)于單據(jù)編號字段（通常也是表的AK ）, 一般新增時都不允許界面輸入。若

6、接 口中直接設(shè)置了此字段對應(yīng)的值，系統(tǒng)將不通過默認(rèn)規(guī)則創(chuàng)建編號，而直接使用此值。 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表的ID或名稱，或快捷碼 具體表的字段和值，詳見resthome幫助（對象新增需填字段） 返回補(bǔ)充數(shù)據(jù) objectid *int 創(chuàng)建記錄的ID 1.4.2 ObjectModify 修改已經(jīng)存在的記錄 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表的ID或名稱，或快捷碼 id* int 要修改的記錄的ID，對于不知道ID的情況，可以通過ak， “ id_find ” 搜索 partial update* b

7、oolea n 缺省值:true，表示僅修改傳入的 對應(yīng)的列 具體表的字段和值，詳見resthome幫助（對象修改需填字段） 返回補(bǔ)充數(shù)據(jù) 1.4.3 ObjectDelete 刪除已經(jīng)存在的記錄，系統(tǒng)自動維護(hù)諸如級聯(lián)刪除等的行為 參數(shù)名 類型 描述 命令參數(shù) table* int 對應(yīng)表的ID id* int 要修改的記錄的ID，對于不知道ID的情況，可以通過ak， “ id find ” 搜索 返回補(bǔ)充數(shù)據(jù) 1.4.4 ObjectSubmit 提交單據(jù)，在Portal中有提交按鈕的任何表 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表的ID或名稱，或快捷碼

8、id* int 要修改的記錄的ID，對于不知道ID的情況，可以通過ak， “ id find ” 搜索 返回補(bǔ)充數(shù)據(jù) 1.4.5 ObjectUnsubmit 取消提交單據(jù)，針對在Portal中有取消提交按鈕的任何表。一般而言，已提交的單據(jù)會將字 段名稱“ STATUS”設(shè)置為2 （已提交）。系統(tǒng)在識別到此信息時禁止任何用戶進(jìn)行修改。 如果系統(tǒng)配置開發(fā)員設(shè)置了允許取消提交，并且系統(tǒng)管理員將此對應(yīng)權(quán)限賦予了接口程序?qū)?應(yīng)賬戶，接口程序就可以執(zhí)行此動作。 接口可以先通過對”status”是否為2來確認(rèn)記錄能否“取消提交” 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表

9、的ID或名稱，或快捷碼 id* int 要修改的記錄的ID，對于不知道ID的情況，可以通過ak， “ id find ” 搜索 返回補(bǔ)充數(shù)據(jù) 1.4.6 ProcessOrder 處理單據(jù)，如同時創(chuàng)建頭和明細(xì)記錄 參數(shù)名 類型 描述 命令參數(shù) masterobj* 頭表記錄對象，將通過masterobj.id確認(rèn)是新增還是修改 操作。見后文屬性描述 detailobjs 明細(xì)表記錄對象，包含多個標(biāo)簽頁的內(nèi)容， 每個標(biāo)簽頁的 內(nèi)容可以是單一對象，也可能是列表。見后文屬性描述 pre_act ions in t 兀素為webaction.id。疋義在操作前的行為，請參考單據(jù) 上的動作定義，常用的如

10、：WebAction.對于網(wǎng)站訂單，例 如將取消付款，然后修改付款明細(xì)。pre_actions僅能用于 修改單據(jù)的情況 post_act ions in t 連續(xù)動作，在完成增刪改調(diào)整后的行為，action需要參考 單據(jù)上的動作定義，如對于網(wǎng)站訂單，保存單據(jù)后還需要 進(jìn)行配送分析(E_SHIPPING_ANAL YZE )和付款 (e retail pay) submit boolea n 若為true,在最后執(zhí)行提交動作，單據(jù)必須支持提交動作， 等同于在界面上點(diǎn)擊“提交”按鈕 masterobj 屬性 卜 table* in t/Stri ng 頭表id或名稱，或快捷碼 卜id* int 要

11、修改的記錄的ID，對于不知道ID的情況，可以通過 ak, “ id find ”搜索，-1表示新增 卜 具體表的字段和值，詳見resthome幫助(對象新增或修改 需填字段) detailobjs 屬性 卜 reftables in t 兀素reftableid為關(guān)聯(lián)表id,從rest幫助的關(guān)聯(lián)表位置獲 取。界面上雖然有多個關(guān)聯(lián)標(biāo)簽，但并非所有標(biāo)簽對應(yīng)的 關(guān)聯(lián)表都需要設(shè)置內(nèi)容。另外，注意數(shù)組元素的順序，不 必與界面一致。如果此參數(shù)未設(shè)置，則必須設(shè)置tables 參數(shù)，見下 卜 tables in t/Stri ng 在reftables參數(shù)不存在的時候使用。 此參數(shù)在表含有面向 同一個明細(xì)表的

12、多個標(biāo)簽頁時將產(chǎn)生錯誤，所以禁止在這 樣的主表上使用。參數(shù)的元素是明細(xì)表的id/名稱/快捷碼。 而不是大聯(lián)表的id。 卜 refobjs* 對象數(shù)組 對應(yīng)與reftables的數(shù)據(jù)內(nèi)容，注意兀素可以是單對象 （1:1）,也可以是數(shù)組（1:m）,必須按照關(guān)聯(lián)表定義來設(shè) 置。作為關(guān)聯(lián)表，必有一個子段與主表PK對應(yīng)，此子段 的值將有系統(tǒng)在主對象新增或修改后強(qiáng)制配置。其他屬性 見后文屬性描述 refobjs兀素（1:1）屬性 卜 table* in t/Stri ng 明細(xì)表id或名稱，或快捷碼 卜id* int 要修改的記錄的ID，對于不知道ID的情況，可以通過 ak, “ id find ”搜索，

13、-1表示新增 卜 具體表的字段和值，詳見resthome幫助（對象新增或修改 需填字段） refobjs 兀素（1:m）屬性 卜 table* in t/Stri ng 明細(xì)表id,或名稱，或快捷碼 卜 addList 對象數(shù)組，對象的內(nèi)容即為新增時的可選字段和相應(yīng)值 卜 modifyList 對象數(shù)組，對象的內(nèi)容即為修改時的可選字段和相應(yīng)值 卜 deleteList 對象數(shù)組，對象的內(nèi)容即為刪除時的可選字段和相應(yīng)值， 即為id ”,或ak”，或id find ” 返回補(bǔ)充數(shù)據(jù) objectid int 主表記錄的ID 1.4.7 ExecuteWebAction 執(zhí)行網(wǎng)站單對象界面的定制按鈕

14、動作，如網(wǎng)絡(luò)訂單上的付款按鈕 參數(shù)名 類型 描述 命令參數(shù) webacti on * in t/Stri ng 動作的ID/名稱 id* int 要操作的記錄的ID，對于不知道ID的情況，可以通過 ak, “ id find ” 搜索 返回補(bǔ)充數(shù)據(jù) 1.4.8 Import 批量導(dǎo)入，操作時，運(yùn)行部分行導(dǎo)入不成功，將提示用戶導(dǎo)入失敗的行。批量導(dǎo)入的每一行 記錄的事務(wù)是獨(dú)立的。 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表的ID或名稱，或快捷碼 update_ on_uniq ue_c on stra ints Stri ng yes”|”no”，在插入行時，若遇

15、到唯一索引出錯， 是否改插入為更新，默認(rèn)為” no ” 數(shù)組，數(shù)組長度即為準(zhǔn)備導(dǎo)入的記錄數(shù)。字段 的名稱同ObjectCreate。數(shù)組兀素的類型參見不 同字段的定義 返回補(bǔ)充數(shù)據(jù) errors* 有錯誤的行的信息構(gòu)造的數(shù)組，每個兀素為下 面的對象內(nèi)容 errors兀素屬性 卜 lineno* int 出錯行的行號，第一行的行號為1 卜 errmsg* Stri ng 出錯原因 1.4.9 Query 返回查詢結(jié)果，用戶設(shè)置查詢條件，系統(tǒng)返回查詢內(nèi)容。從本質(zhì)上將，下列參數(shù)將按如下規(guī) 則構(gòu)造SQL查詢語句： Select columns from table。in table,where par

16、ams and read permission filter order by orderby,并支持分頁返回結(jié)果 在構(gòu)造的過程中，系統(tǒng)將根據(jù)授權(quán)當(dāng)前API調(diào)用程序的賬戶權(quán)限進(jìn)行校驗(yàn)和額外的讀取條 件進(jìn)行限制。例如，調(diào)用者訪問全部春季商品資料，但系統(tǒng)根據(jù)調(diào)用者權(quán)限發(fā)現(xiàn)用戶訪問商 品時只能檢索09年的商品，則查詢結(jié)果集合為 09年的春季商品。通過結(jié)構(gòu)化的查詢參數(shù)設(shè) 置，系統(tǒng)就能夠添加額外的控制條件了。 支持分頁。 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表的ID或名稱，或快捷碼 qlcid int 在table上配置的查詢列選項(xiàng) QueryListConfig的

17、ID,如果設(shè) 置的對象是不可以訪冋的，則通過columns去讀取檢索字 段，否則通過查詢配置讀取。另外，如果orderby數(shù)組未設(shè) 疋，也將嘗試從 QueryListConfig上獲取排序字段并應(yīng)用。 colu mns Stri ng 通過數(shù)組指定要檢索的字段，字段必須起始于table指明的 表，可以通過ColumnLink方式關(guān)聯(lián)到外鍵對應(yīng)的表上的記 錄，詳見 Portal關(guān)于子段的配置。右未設(shè)置，將檢索 column_masks的內(nèi)容。關(guān)于可用的子段參見rest.jsp 檢索 字段”列表 colu mn _masks in t 根據(jù)字段的讀寫規(guī)則”獲取字段，若table上的字段的讀 與規(guī)則

18、在 column masks任意兀素指疋的位置上設(shè)置為 “1 ”，將加入到查詢中。例如，0,2,4表示在新增時顯示或 修改時顯示或大列表時顯示的字段將作為查詢返回。若未設(shè) 置，將默認(rèn)6，即單對象窗口可見的所有字段。有效字段 不包含UI控件類型的字段，如button, hr params 查詢過濾條件，將與用戶權(quán)限合并 start int 從結(jié)果集合的哪一行開始獲取記錄（從0計算） range int 取多獲取start仃開始的多少條記錄，考慮系統(tǒng)性能，取大 值將由系統(tǒng)參數(shù)設(shè)定（perties#rest.query.max.range , 缺省為100） cou nt boo

19、lea n 是否計算結(jié)果集的總行數(shù)，將體現(xiàn)在返回結(jié)果的count里， 缺省為false orderby 排序設(shè)置，對象數(shù)組。如果未設(shè)置，系統(tǒng)將嘗試從qlcid所 對應(yīng)的QueryListConfig對象上獲取設(shè)定的排序字段 params結(jié)構(gòu)，稱為 Expression，為嵌套一叉樹結(jié)構(gòu) 卜 combine Stri ng and” | 6r | and not | or not ”，若設(shè)置，必填 expr1 和 expr2 屬性，忽略 column 和 condition。 卜 expr1 Expressi on 通過combine指明兩個Expression之間的關(guān)系 卜 expr2 Exp

20、ressi on 卜 column Stri ng 在未設(shè)置combine對象時必填。column名稱或者 ColumnLink，必須起始于 table，忽略主表名稱 卜 condition Stri ng 在未設(shè)置combine對象時必填。字符串設(shè)置對應(yīng)字段的條 件,例如2009090120091021表示日期的范圍，10表示數(shù) 字字段的范圍，輸入方式與PORTAL界面一致。-SA001 , 表示完全匹配，SA001表示包含此內(nèi)容（相當(dāng)于%SA001% ）。 通過expression設(shè)疋某個字段滿足某個條件，對于諸如exists 類型的請求，可以設(shè)置 column為空，在condition里

21、直接輸 入exists（select x from y where z）類似的語句，注意主表在整 體SQL語句構(gòu)造時將被賦予全名稱。 orderby兀素屬性 卜 column Stri ng 排序字段名稱，可以是ColumnLink，字段不必在columns 里出現(xiàn)，但必須起始于 table指明的表，以通過 ColumnLink 方式關(guān)聯(lián)到外鍵對應(yīng)的表上的記錄 卜asc boolea n 排序，true為順序，否則為逆序 返回補(bǔ)充數(shù)據(jù) rows * 第一維是行，第二維是每行的列對應(yīng)值，列順序完全按照參 數(shù)columns的內(nèi)容順序 cou nt int 總結(jié)果集的長度（非當(dāng)前分頁），只在參數(shù)co

22、unt-true時計 算并返回 1.4.10 GetObject 獲取一個對象的信息，包括頭和明細(xì)，即標(biāo)簽頁的內(nèi)容。對應(yīng)UI即是單對象界面。 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表的ID或名稱，或快捷碼 id* int 要操作的記錄的ID，對于不知道ID的情況，可以通過ak, “ id find ”搜索 reftables in t 可選，通過數(shù)組來指明需要哪些標(biāo)簽頁的內(nèi)容，每個兀素都 是關(guān)聯(lián)表的id 返回補(bǔ)充數(shù)據(jù) 字段來自于表的“檢索用字段” reftables 與設(shè)定的參數(shù) reftables對應(yīng)，refobj可能是單對象(1:1)，也 可能是列表描述

23、(1:m)，單對象的字段即為界面上顯示的字 段，列表的內(nèi)容與Query命令的返回值類似，包括rows, count，由于未提供參數(shù)range，系統(tǒng)按默認(rèn)最大氾圍返回數(shù) 據(jù)。右count大于rows的長度，應(yīng)考慮通過 Query命令分頁 獲取所有值。 reftables數(shù)組兀素(1:1)屬性 卜 具體表的字段和值，詳見resthome幫助(“檢索用字段”) reftables數(shù)組兀素(1:m)屬性 卜 rows * 第一維是行，第二維是每行的列對應(yīng)值，列字段順序按照表 的“檢索用字段”的內(nèi)容順序。 卜 count * int 總結(jié)果集的長度(非當(dāng)前分頁)。右count大于rows的長度， 應(yīng)考慮

24、通過Query命令分頁獲取所有值 1.4.11 ExecuteSQL 執(zhí)行ad_sql表中的sql腳本，當(dāng)前用戶必須首先具有ad_sql相應(yīng)記錄的讀取權(quán)限。ad_sql 中的sql語句可以是任何可以被 PreparedStatement加載的語句，包括 select/insert/update/delete等，sql語句中可以包含環(huán)境變量(用戶相關(guān)屬性)，也可以接受綁 定變量。對于綁定變量，要求調(diào)用的程序員非常清楚變量順序，在調(diào)用時依照順序設(shè)定。返 回結(jié)果集將以json形式封裝。 ExecuteSQL給予界面程序設(shè)計人員一定的靈活性，設(shè)計人員也應(yīng)充分考慮可能的危險操 作。 參數(shù)名 類型 描述

25、命令參數(shù) n ame* Stri ng 對應(yīng)AD SQL的名稱 values 綁疋變量的值，注意順序必須與SQL語句中的變量順序一 直。另外，變量類型與SQL變量的類型也必須相符。目前支 持的變量類型包括：String，Integer， Long, Double， Date。 Date也是字符串，在設(shè)置變量時，必須加前綴$d來表示。 例如，sql= select id from c_store where creationdate=? ” 前端 可以配置values= $d2010/11/12 14:21:00 “.目前支持的 date 格式只有一種：yyyy/mm/dd hh:mi:ss 。

26、 對于 Null 內(nèi)容， 由于sql必須指明其類型，故使用$null_int, $null_str, $null_double, $null_date來表示，直接設(shè)置null將等同于 $n ull str 返回補(bǔ)充數(shù)據(jù) result 當(dāng)sql為查詢語句時，與預(yù)期ResultSet相對應(yīng)的結(jié)構(gòu)。考慮 系統(tǒng)性能，最大值將由系統(tǒng)參數(shù)設(shè)定 (perties#rest.query.max.range，缺省為 100) cou nt int 當(dāng)sql為非查詢語句時，為更新的行數(shù) 1.4.12 ExecuteBatch 此命令能將本文其他命令打包執(zhí)行，但是作為一個事務(wù)。 參數(shù)名 類型 描述 命令參數(shù) tran sact ions* 每個兀素都是一個命令，如ObjectCreate, ObjectModify 等， 任何一個執(zhí)行失敗都將導(dǎo)致全部回滾。 返回補(bǔ)充數(shù)據(jù) 1.4.13 ExecuteAudit 執(zhí)行工作流實(shí)例的批準(zhǔn)、駁回或指派，要求當(dāng)前操作人必須有相應(yīng)審核權(quán)限。 參數(shù)名 類型 描述 命令參數(shù) table* in t/Stri ng 對應(yīng)表的ID或名稱，或快捷碼 id* int 要操作的記錄的I