金蝶EAS_V81_WebService開發(fā)指南

1、Webservice開發(fā)指南版權聲明本書著作權屬于金蝶軟件(中國)有限公司所有，在未經本公司許可的情況下，任何單位或個人不得以任何方式對本書的部分或全部內容擅自進行增刪，改編，節(jié)錄，翻譯，翻印，改寫。金蝶軟件（中國）有限公司2015年8月BOSWebService1.1.BOSWebService原理21.2.發(fā)布WebService的約束31.3.BOSWebService發(fā)布31.3.1.發(fā)布流程31.3.2.發(fā)布WebService31.3.3.編輯WebService配置文件41.4.BOSWebService部署51.4.1.建立web工程51.4.2.部署發(fā)布文件51.4.3.測試

2、是否正確61.4.4.Web工程目錄及文件截圖61.5.客戶端代碼61.5.1.獲取wsdl服務描述文件61.5.2.下載工具71.5.3.建立一個新工程71.5.4.使用java客戶端111.5.5.importVoucher（憑證引入121.6.BOS webservice 安全性131.6.1.BOS webservice 安全性概述131.6.2.不啟用安全性131.6.3.啟用安全性131.6.4.如何安全性啟用141.7.EASLogin 登陸webservice 說明141.7.1.EASLogin 接口說明141.7.2.EASLogin 異常說明151.7.3.EASLogi

3、n 和前面版本的差別161.8.webservice 異常查看162.WebService 客戶端開發(fā)指南172.1.前提條件172.2.獲取WSDL文件172.3.生成客戶端182.3.1.生成Java客戶端182.3.2.建立一個新工程182.3.3.將獲取到的WSDL文件拷貝到工程的根目錄下：192.3.4.生成客戶端192.4.使用java客戶端232.5.生成C# 客戶端232.5.1.使用命令行232.5.2.運行命令生成客戶端242.5.3.使用客戶端代碼253.webservice FAQ273.1.在EAS 上如何發(fā)布一個webservice ?273.2.如何調用一個 we

4、bservice？273.3.有哪些工具能夠簡單的測試 webservice？273.4.EASLogin 服務登陸如何判斷失敗273.5.調用webservice時報 com.kingdee.bos.IllegalSessionStateException: Please login first 異常？273.6.EAS6.0調用webservice時報沒有 WSConfig.getSrvURL() 方法。283.7.調用webservice時報.SocketTimeoutException: Read timed out 異常28BOSWebService1.1. BOSWebServic

5、e原理Webservice 主要由SOAP，WSDL, 以及UDDI 等幾塊技術組成，以XML格式進行數(shù)據的傳輸。是建立可互操作的分布式應用程序的新平臺Webservice的一個最基本的目的就是提供在各個不同平臺的不同應用系統(tǒng)的協(xié)同工作能力。使各個異構系統(tǒng)之間實現(xiàn)無縫交互。在本質上是要為應用程序之間提供數(shù)據通訊的標準，為企業(yè)應用之間動態(tài)地提供大顆粒度的服務，并不適合于非常精細的基于會話的方法調用以及復雜的事務（transaction）處理之中。1.2. 發(fā)布WebService的約束 在BOS Studio中發(fā)布webService時，只能發(fā)布Entity和Façade兩種元數(shù)據類型

6、成WebService服務端的代碼。 由于Entity或Façade函數(shù)參數(shù)和返回值可能包含很多復雜的業(yè)務類型，在發(fā)布時會生成許多輔助類，一些復雜類型在其他異構系統(tǒng)中生成webService客戶端時不能很好的支持，因此建議在建立webService功能時，最好使用Façade，并且提供簡單類型的輸入和返回參數(shù)。1.3. BOSWebService發(fā)布1.3.1. 發(fā)布流程 先建立需要發(fā)布的Façade,建立粗粒度的業(yè)務方法，業(yè)務方法盡可能提供簡單數(shù)據類型的數(shù)據參數(shù)和返回參數(shù)。1.3.2. 發(fā)布WebService 運行BOS Studio，打開“包分類”視圖，在其

7、中選中要發(fā)布WebService的實體或Façade對象（可同時選中多個），點擊鼠標右鍵，在彈出菜單中選擇“發(fā)布WebService”,將彈出“發(fā)布WebService”向導： 選擇實體或Façade對象下要發(fā)布的方法，手工輸入或者點擊“瀏覽”按鈕來指定發(fā)布生成代碼存放的目錄，可以同時勾中“追加到配置文件”。這樣BOS Studio將會根據選中的對象和要發(fā)布的方法生成WebService代碼和wsdl描述1.3.3. 編輯WebService配置文件在“包分類”視圖中，選擇要編輯其配置文件的解決方案，點擊工具欄上的“編輯WebService 配置文件”按鈕，將會彈出配置文件

8、編輯向導在其間，可以增加或刪除要發(fā)布的對象（方法），選擇好要發(fā)布的對象（方法）后，點擊“完成”按鈕，即可完成對配置文件的編輯。配置文件位于解決方案的根目錄下。1.4. BOSWebService部署 1.4.1. 部署發(fā)布文件發(fā)布成功以后，在臨時目錄里會生成一個wsdd文件和一個目錄，例如：D:webtestAcctCussentCheckFacade.wsddD:webtestcomkingdeeeasfiglappwebserviceWSAcctCussentCheckFacadeSrvProxy.javaWSAcctCussentCheckFacadeSrvProxy.java文件拷貝到

9、解決方案src目錄中，注意包名和路徑一致；AcctCussentCheckFacade.wsdd處理方法如下：找到解決方案的runtimeserverdeployeas.ear目錄，用解壓縮軟件打開web.war，進入WEB-INF目錄把AcctCussentCheckFacade.wsdd添加進去；把AcctCussentCheckFacade.wsdd文件里的service節(jié)點內容添加到server-config.wsdd文件。操作方法建議：提取server-config.wsdd文件到臨時目錄，用編輯工具打開，再打開AcctCussentCheckFacade.wsdd，拷貝servic

10、e節(jié)點內容粘貼到server-config.wsdd文件，注意XML格式一致；保存server-config.wsdd文件并拷回到web.war壓縮包里。1.4.2. 測試是否正確上面的步驟操作完成后，快測已經可以看到新建的WebService。通過瀏覽器輸入服務的地址，訪問服務是否正確如輸入：http:/server-ip:port/ormrpc/services BOS快測啟動的默認端口為568981.4.3. 部署到正式服務器1、在BIM中部署代碼和元數(shù)據；2、把解決方案下改好的runtimeserverdeployeas.earweb.war文件拷貝到EAS服務器的serverdepl

11、oyeas.ear目錄中，3.將生成的Web Service的java代碼編譯為class,放在EAS服務器的easserverdeployeas.earweb.warWEB-INFclass下，把發(fā)布的wsdd文件中服務部分拷貝到server-config.wsdd中。4.重啟EAS服務器1.4.4. Web工程目錄及文件截圖1.5. 客戶端代碼1.5.1. 獲取wsdl服務描述文件WebService已經成功部署到應用服務器上（本文以Apusic為例進行說明），客戶端可以通過瀏覽器訪問到已部署的WebService。要構建相關的客戶端，就要獲取已經部署的WebService的相應的WSDL

12、文件，用鼠標右鍵點擊藍色的部分“(wsdl)”，選取“目標另存為”菜單，這時將出現(xiàn)選擇保存文件位置的對話框，在文件名處將文件的后綴名由xml改為wsdl，將wsdl文件保存至本地。1.5.2. 下載工具 通過下載eclipse（下載j2ee版本）或通過命令行來生成java -Djava.ext.dirs=lib org.apache.axis.wsdl.WSDL2Java 其中l(wèi)ib是axis包目錄生成客戶端代碼。1.5.3. 建立一個新工程 例如建立一個工程名為GenerateWSClient的Java工程：將獲取到的WSDL文件拷貝到工程的根目錄下用鼠標右鍵點

13、擊要生成客戶端的WSDL文件，選取菜單“Web Services”-“Generate Client”將會彈出生成客戶端向導如圖，使用默認值，點擊“Next >”，進入下一步：依然使用默認值，點擊“Next >”，進入下一步：依然使用默認值，點擊“Finish”，即可生成相應的客戶端工程（是一個Web工程）1.5.4. 使用java客戶端新生成的工程中有一個JavaSource目錄，我們要使用的java代碼就位于這個目錄，例如上圖中的WSLoginProxy.java。以下是一個使用Java客戶端的例子：import java.rmi.RemoteException;import

14、com.kingdee.WSLoginProxy;/此為發(fā)布的代碼import com.client.WSContext;public class LoginTest public static void main(String args) try WSLoginProxy proxy = new WSLoginProxy();/* * web service客戶端登陸 * userName 用戶名 * password 密碼 * slnName eas * dcName 數(shù)據中心,對應的是dataCenter中數(shù)據中心id * language 語言 L2簡體 * dbType 數(shù)據庫類型

15、0:sqlServer 1:db2 2:oracle * authPattern 驗證方式 默認 "BaseDB" ; 其他認證方式KEY可從easAuthPatterns.xml中獲取 */WSContext ctx = proxy.login("用戶", "", "eas", "數(shù)據中心id", "L2", 0); /成功登錄后打印sessionIdSystem.out.println(ctx.getSessionId(); /調用憑證業(yè)務webservice方法impo

16、rtVoucher（憑證引入），請看1.55節(jié) catch (RemoteException e) e.printStackTrace();1.5.5. importVoucher（憑證引入1、 憑證引入接口，兩個接口方法都可用，且用法一致2、 憑證 webService 接口生成客戶端，可參考 EASLogin 方法3、 憑證引入參數(shù)：importVoucher(wsvoucher, int isVerify, int isCashflow)l 傳參數(shù)第1個：WSWSVoucher 普通對象數(shù)組，見構造EAS憑證字段以及含義說明l 傳參數(shù)第2個：isverify 0 不核銷，暫存 1 核銷，

17、暫存 2 不核銷，提交 3 核銷，提交l 傳參數(shù)第3個：isImpCashflow是否引入現(xiàn)金流量 0 不引入1 引入4、 憑證引入代碼調用說明5、 返回值String是一個長度為憑證數(shù)，寬度是5的字符串數(shù)據寬度的定義：外部系統(tǒng)憑證號，憑證字，會計年度，會計期間，處理信息，異常信息，金蝶憑證號1.6. BOS webservice 安全性 1.6.1. BOS webservice 安全性概述BOS webservice 安全 有兩種模式，啟用安全性 和 不啟用安全性，默認配置是不啟用安全性。1.6.2. 不啟用安全性在不啟用安全性，則訪問業(yè)務webservice前，先成功調用 EASLogi

18、n 登陸的webservice服務，則系統(tǒng)將記住相關登陸信息，下次調用業(yè)務方法是，直接從服務器中獲取相關登陸信息。如果多次調用 EASLogin webservice服務，則以最后一次為準。1.6.3. 啟用安全性在啟用安全性后，每次WEBSERVICE 訪問，必須帶上相關的 SessionID 信息，如下紅字部分。系統(tǒng)將根據 SOAP頭中的SessionID 信息，獲取相關的上下文信息。<SOAP-ENV:Envelope xmlns:SOAP-ENV="/soap/envelope/" xmlns:SOAP-ENC

19、="/soap/encoding/" xmlns:xsi="/2001/XMLSchema-instance" xmlns:xsd="/2001/XMLSchema" xmlns:m0="http:/com.kingdee.eas.base.btp.app.BTPManager/isPropOwner/parameter/promote"><SOAP-ENV:Header><ns

20、1:SessionId xmlns:ns1="">ada894c0-8223-41dc-b816-61eb67dc38bd</ns1:SessionId></SOAP-ENV:Header><SOAP-ENV:Body><m:isPropOwner xmlns:m="http:/com.kingdee.eas.base.btp.app.BTPManager/Service"><m0:bosTypeString>BF76D8D1</m0:bosTypeString><m0:

21、propName>id</m0:propName></m:isPropOwner></SOAP-ENV:Body></SOAP-ENV:Envelope>1.6.4. 如何安全性啟用一、修改easSpetties文件 isRomoteLocate=falseisRomoteUserCheck=true二、修改easServereasserverdeployeas.ear web.war 壓縮文件中 WEB-INF 目錄下server-confi

22、g.wsdd 文件 . <handler name="Authenticate" type= "java:org.apache.axis.handlers.SimpleAuthenticationHandler"/> <handler name="LoginHandler" type="java:com.kingdee.bos.webservice.LoginHandler"/> . <transport name="http"> <requestFlo

23、w> . <handler type="LoginHandler"/> </requestFlow> </transport>1.7. EASLogin 登陸webservice 說明1.7.1. EASLogin 接口說明EASLogin 中有兩個方法 方法一、public WSContext login(String userName,String password,String slnName,String dcName,String language ,int dbType) throws AxisFault方法二、publ

24、ic WSContext login( String userName, String password, String slnName, String dcName, String language , int dbType, String authPattern) throws AxisFault參數(shù)說明:userName: 登陸用戶名password: 登陸密碼slnName：解決方案名稱（通常為 eas）dcName: 數(shù)據中心 numberlanguage： L1（英文）、L2(中文簡體)、 L3(中文繁體)dbType: 數(shù)據中心數(shù)據庫類型 0(MS SQL Server)、1(D

25、B2 UDB)、2(Oracle)(歷史遺留參數(shù))authPattern: EAS 的驗證方式, 在方法一種默然為 BaseDB1.7.2. EASLogin 異常說明在 BOS6.2 版本中，EASLogin 登陸出錯將會返回 失敗返回報文SOAP 協(xié)議中 soapenv:Fault 標簽的相關說明<faultcode>供識別故障的代碼<faultstring>可供人閱讀的有關故障的說明<faultactor>有關是誰引發(fā)故障的信息<detail>存留涉及 Body 元素的應用程序專用錯誤信息1.7.3. EASLogin 和前面版本的差別EA

26、SLogin 在BOS 6.2 之前，登陸失敗后，返回WSContext對象，當 WSContext. sessionId 是為null 或 空 時，表明登陸失敗，失敗的具體日志信息在 服務器日志中可以查看。BOS 6.2 修改為當?shù)顷懯。瑢⒎祷?Fault 報文(通?？蛻舳艘娲a會用異常方式表示)， Fault 中將包含具體的錯誤信息。同時服務器日志中也會打印出錯誤日志。1.8. webservice 異常查看webservice 調用錯誤，將可以在 EAS 相應的系統(tǒng)日志中查看到相應的信息。如 $EASHOME/ /server/profiles/server1/logs/ apusi

27、c.log.0有的異常信息也會通過 SOAP 返回到客戶端?？蓞⒖挤祷豐OAP的faultstring元素中的錯誤詳細信息。2. WebService 客戶端開發(fā)指南2.1. 前提條件WebService已經成功部署到應用服務器上（本文以Apusic為例進行說明），客戶端可以通過瀏覽器訪問到已部署的WebService，例如通過以下地址訪問到已部署的WebService：http:/localhost:6888/easws/services2.2. 獲取WSDL文件如上圖所示，應用服務器已經部署了相關的WebService。要構建相關的客戶端，就要獲取已經部署的WebService的相應的WS

28、DL文件，用鼠標右鍵點擊藍色的部分“(wsdl)”，選取“目標另存為”菜單，這時將出現(xiàn)選擇保存文件位置的對話框，在文件名處將文件的后綴名由xml改為wsdl，將wsdl文件保存至本地。2.3. 生成客戶端2.3.1. 生成Java客戶端下面將以使用Eclipse3.1來生成java客戶端為例進行說明。Eclipse3.1可以到免費下載。運行后，要為Eclipse配置至少一個相應的應用服務器，例如Tomcat5.5。2.3.2. 建立一個新工程例如建立一個工程名為GenerateWSClient的Java工程：2.3.3. 將獲取到的WSDL文件拷貝到工程的根目錄下

29、：2.3.4. 生成客戶端用鼠標右鍵點擊要生成客戶端的WSDL文件，選取菜單“Web Services”-“Generate Client”將會彈出生成客戶端向導：如圖，使用默認值，點擊“Next >”，進入下一步：依然使用默認值，點擊“Next >”，進入下一步：依然使用默認值，點擊“Finish”，即可生成相應的客戶端工程（是一個Web工程）。2.4. 使用java客戶端新生成的工程中有一個JavaSource目錄，我們要使用的java代碼就位于這個目錄，例如上圖中的WSLoginProxy.java。以下是一個使用Java客戶端的例子：import java.rmi.Remo

30、teException;import _111._19._168._192.easwebservice.services.easlogin.WSLoginProxy;import client.WSContext;public class LoginTest /* * param args */public static void main(String args) try WSLoginProxy proxy = new WSLoginProxy();WSContext ctx = proxy.login("fanfan", "", "eas

31、", "eas50", "l2", 0);System.out.println(ctx.getSessionId(); catch (RemoteException e) e.printStackTrace();所調用的方法中的參數(shù)可以從WebService提供者處獲得。2.5. 生成C# 客戶端在此，以Microsoft Visual Studio .Net 2003為例說明如何生成C# 客戶端。用戶在正確安裝完Microsoft Visual Studio .Net 2003后，需要設置一個環(huán)境變量Path= C:Program Files

32、Microsoft Visual Studio .NET 2003SDKv1.1Bin，其中C:Program FilesMicrosoft Visual Studio .NET 2003是Microsoft Visual Studio .NET 2003的安裝路徑。2.5.1. 使用命令行運行“cmd”，打開命令行窗口，并進入WSDL文件所在目錄（在此為C:wsdl目錄）：2.5.2. 運行命令生成客戶端運行命令wsdl XXX.wsdl（XXX為wsdl文件的文件名），即可生成C# 的WebService客戶端代碼：輸入途中命令，按回車鍵，即可自動生成C# 客戶端代碼：如上圖所示，生成了一

33、個文件WSLoginService.cs，這就是我們所需要的客戶斷代碼2.5.3. 使用客戶端代碼運行Microsoft Visual Studio .NET 2003，建立一個工程，將剛剛生成的WSLoginService.cs文件拷貝到工程的根目錄，手工為該代碼配置合適的命名空間：這時就可以調用該客戶端代碼了。例如以下代碼：using System;namespace ConsoleApplication1/ <summary>/ Summary description for Class1./ </summary>class Class1/ <summary

34、>/ The main entry point for the application./ </summary>STAThreadstatic void Main(string args)WSLoginService proxy = new WSLoginService();WSContext ctx = proxy.login("fanfan", "", "eas", "eas50", "l2", 0);Console.WriteLine(ctx.sessionId);Con

35、sole.ReadLine();所調用的方法中的參數(shù)可以從WebService提供者處獲得。3. webservice FAQ3.1. 在EAS 上如何發(fā)布一個webservice ?請看 BOS開發(fā)指南_WebService文檔3.2. 如何調用一個 webservice？請看 BOS開發(fā)指南_WebService客戶端開發(fā)文檔3.3. 有哪些工具能夠簡單的測試 webservice？可采用xmlspy 軟件。在 SOAPàCreate new SOAP requestà選擇wsdl 文件，點擊OK à 選擇測試的方法à 在返回的SOAP報文中，輸入相

36、應的參數(shù)信息在SOAP àSend request to server xmlspy 將訪問服務，并列出返回的 SOAP 報文。3.4. EASLogin 服務登陸如何判斷失敗在 BOS6.2 之前，EASLogin 服務返回 WSContext, 當 WSContext. sessionId 是為null 或 空 時，表明登陸失敗，失敗的具體日志信息在 服務器日志中可以查看。在 BOS6.2 登陸失敗，返回SOAP報文則BODY為FAULT標簽（即客戶端webservice引擎將拋出異常）3.5. 調用webservice時報 com.kingdee.bos.IllegalSess

37、ionStateException: Please login first 異常？1、在調用 業(yè)務的webservice前，需要先調用 EASLogin webservice 登陸。2、判斷調用 EASLogin webservice 是否成功。3.6. EAS6.0調用webservice時報沒有 WSConfig.getSrvURL() 方法。打補丁 PT0247173.7. 調用webservice時報.SocketTimeoutException: Read timed out 異常在使用webservice客戶端調用 webservice時，客戶端默認會設置一個超時時間，當調用超過該

38、時間后，客戶端將會報 .SocketTimeoutException: Read timed out 異常。可以通過客戶端參數(shù)設置改變超時時間如果采用axis1客戶端：call = (Call) service.createCall(); call.setTimeout(TIMEOUT);如果采用axis2客戶端：ServiceClient call = new ServiceClient();call.setOptions(options);call.getOptions().setTimeOutInMilliSeconds(Constants.WSTIMEOUT);4. Webservic

39、e返回復雜對象 List 或者JAVABEAN中包含List axis返回對象的基本要求，Axis開發(fā)的Webservice中不能直接返回List對象，只能通過數(shù)組的方式返回，當然在直接返回List的例子中，服務端代碼是返回List，但通過傳輸后客戶端必須以數(shù)組的方式進行解讀，因此建議直接返回數(shù)組方式。4.1. 以下為例子源碼 服務端代碼： package com.kingdee.model;import java.util.List;/書本public class Book implements java.io.Serializable/* * */private static final

40、long serialVersionUID = -8798284029723517521L;/書本名稱private String name;/書本價格private Double price;/一本書有多個作者進行編寫 最好只能用數(shù)組方式，請勿用其他方式private BookAuthor bookAuthor;public String getName() return name;public void setName(String name) = name;public Double getPrice() return price;public void setPri

41、ce(Double price) this.price = price;public BookAuthor getBookAuthor() return bookAuthor;public void setBookAuthor(BookAuthor bookAuthor) this.bookAuthor = bookAuthor;Package com.kingdee.model;/作者public class BookAuthor implements java.io.Serializable/* * */private static final long serialVersionUID

42、= -6434694774033892935L;/作者名稱private String name;/作者簡述private String desc;public String getName() return name;public void setName(String name) = name;public String getDesc() return desc;public void setDesc(String desc) this.desc = desc;package com.kingdee.service;import java.util.ArrayList

43、;import java.util.List;import com.kingdee.model.Book;import com.kingdee.model.BookAuthor;/書本訂購public class BookOrder public static Book book=new Book();/設置要訂購的書名稱public String setBookName(String name)book.setName(name);BookAuthor authorList=new BookAuthor1;BookAuthor author=new BookAuthor();author.s

44、etName("bookAuthor");author.setDesc("authorDesc");authorList0=author;book.setBookAuthor(authorList);return "success"/根據名稱返回書本，一個書本有多個作者public Book getBookByName(String name)if(name!=null&&!"".equalsIgnoreCase(name)&&name.equalsIgnoreCase(book.g

45、etName()return book;elsereturn null;/返回所有（多個）書本public List getAllBooks()List bookList=new ArrayList();bookList.add(book);return bookList;4.2. 關鍵配置<！-定義的webservice名稱 -> <service name="BookService" provider="java:RPC"> <parameter name="className" value="com.kingdee.service.BookOrder" /> <parameter name="allowedMethods" value="*" /> <!- 這里定義了方法的參數(shù)以及返回值 可以不寫 ->