1、523392482.doc BOS接口開發指南 目錄 BOS接口開發指南 1 1.1 概述1 1.1.1 設計思想1 1.1.2 Portal框架簡介 錯誤！未定義書簽。 1.2 身份認證2 1.3 數據格式2 1.3.1 必選參數2 1.3.2 業務參數3 1.3.3 返回內容 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設計思想 我們將可快速開發作為首要設計出發點。 目前的web接口主要有以下幾種方式 xml-rpc soap rest 作為輕量級的接口設計模型，rest具有開發快速，接口完全自定義的特點，考慮以此模式進 行。 由于網站接口的上傳和下載數據都比較大，封裝這些數據的方法在XML和JSON之間考 慮，JS

3、ON的特點就是簡單，相比XML有以下問題： 1. 沒有命名空間 n amespace 2. 不像xml那樣區分屬性 attribute和元素element 3. 不支持屬性的排放順序控制 我們的系統里不存在多個namespace,且都可以element來顯示，另外用數組來控制元素間 的順序，以JSON來封裝數據是可行的。 在服務器上給出專用URL來處理所有接口內容： 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里有處理結果，為JSON格式 tra nsact ion-resp on se,. tran sact ion-resp on se: id:, code: , message:, :, 一個transaction里的多個操作將全部成功，或全部失敗，code=0表示成功，其他都為失敗， 失敗的信息在 message里 1.4命令 命令說明：在命令中都涉及到定位記錄在數據庫中位置的請求操作，一般可以通過ID來定 位，若不清楚I

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

25、命令參數 n ame* Stri ng 對應AD SQL的名稱 values 綁疋變量的值，注意順序必須與SQL語句中的變量順序一 直。另外，變量類型與SQL變量的類型也必須相符。目前支 持的變量類型包括：String，Integer， Long, Double， Date。 Date也是字符串，在設置變量時，必須加前綴$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 內容， 由于sql必須指明其類型，故使用$null_int, $null_str, $null_double, $null_date來表示，直接設置null將等同于 $n ull str 返回補充數據 result 當sql為查詢語句時，與預期ResultSet相對應的結構。考慮 系統性能，最大值將由系統參數設定 (perties#rest.query.max.range，缺省為 100) cou nt int 當sql為非查詢語句時，為更新的行數 1.4.12 ExecuteBatch 此命令能將本文其他命令打包執行，但是作為一個事務。 參數名 類型 描述 命令參數 tran sact ions* 每個兀素都是一個命令，如ObjectCreate, ObjectModify 等， 任何一個執行失敗都將導致全部回滾。 返回補充數據 1.4.13 ExecuteAudit 執行工作流實例的批準、駁回或指派，要求當前操作人必須有相應審核權限。 參數名 類型 描述 命令參數 table* in t/Stri ng 對應表的ID或名稱，或快捷碼 id* int 要操作的記錄的I