1、U8API开发手册C#版U8API开发手册作者:商平锋版权所有:用友软件股份有限公司1.简介U8API是为U8客户化应用开发提供的一套标准化的U8ERP业务编程接口。是U8UAP二次开发体系的重要组成部分。它包括一整套涵盖U8ERP采购、销售、库存、制造(规划中)、财务(规划中)、基本档案(规划中)等业务模块的API接口资源。U8API的推出为U8标准产品更好的适应用户的个性化需求,更好的实现客户化交付提供了有力支持。U8API按照U8ERP业务产品模块进行分类,并以U8主要业务实体(单据、档案、凭证)作为操作对象,提供了常用的基本操作。比如:对于库存的收发单据,提供“新增”、“审核”、“弃审
2、”、“删除”、“装载”、“修改”六个API接口。目前,U8API提供了供应链采购、销售、库存三个产品的所有单据的增删改、审核/弃审等API接口,后续版本会逐步将制造、财务、基本档案等模块的API纳入进来。U8API通过“U8API资源管理器”对U8范围内所有API进行集中统一分类管理,形成了一套完整的U8API资源库。U8API的使用者可以使用“U8API资源管理器”浏览、查看API及其接口定义,并可辅助进行代码生成(目前支持C#和VB语言);API的开发者可以通过此工具发布、注册API,所有业务API都必须在“U8API资源管理器”中进行注册。U8API还提供了一套运行时调用框架U8APIB
3、roker。它是所有U8API的调用代理,用户要使用某个API只需调用U8APIBroker即可,无需直接访问真正的API。U8APIBroker作为一个服务代理中间件,起到了隔离API的提供者与使用者的作用,降低了耦合依赖关系。U8API与U8EAI接口从功能上看比较相识,但它们的特性有差别。U8API采用传统的编程模型,更靠近底层,业务逻辑粒度更细,而且还需要或依赖一些特定的上下文环境,比如:login、事务等;而U8EAI接口则是完全松耦合的,采用XML和请求/响应的消息传递模式,且业务粒度比较粗放。这些特性的差别决定了它们的应用领域不同,U8API更适合于U8内部的功能扩展和客户个性化
4、开发,而U8EAI则适合外部系统与U8之间以业务数据交换为特征的应用集成开发。2.API应用.1.API总体应用过程2.1.1API浏览查找在“开始”-“程序”-“用友ERP-U8”-“UAP”目录下找到“U8API资源管理器”,单击,登录,进入“U8API资源管理器”。在左侧 “U8API” 树形节点下,找到某某模块,如“库存管理”模块(可以看到下面列有很多个单据,如盘点单、采购入库单等),展开要操作的单据,分两个子节点:“事件”和“服务接口”,在“服务接口”下可以看到该单据提供的API接口,如“添加新单据”、“审核单据”等。双击这些节点出现该API的详细描述,如下图2.1所示。在节点上右键
5、单击弹出“上下文菜单”,在“代码示例”菜单项上弹出下一级子菜单,单击它们,如单击“C#代码示例”则可以看到调用该API的C#示例代码,如下图2.2所示。直接拷贝这些代码,然后在集成开发环境(IDE)中编辑和编译这些代码,即能实现调用U8标准API。利用这些代码示例时,请按照其中每一步骤的提示说明正确操作,如添加必要的引用、按照自动生成的代码填入正确的参数等。正确使用则可以调用成功,否则会返回详细的错误信息。以下代码中均以C#为例,VB语言请具体查看对应的VB代码示例部分。图2.1 接口描述图 2.2 代码示例2.1.2API调用过程组件引用针对两种语言,需要引用不同的组件。(1)C#:%U8S
6、OFT%InteropInterop.U8Login.dll、%U8SOFT%InteropInterop.MSXML2.dll、%U8SOFT%UFMOMU8APIFrameworkUFIDA.U8.U8APIFramework.dll、%U8SOFT%UFMOMU8APIFrameworkUFIDA.U8.MomServiceCommon.dll、%U8SOFT%UFMOMU8APIFrameworkUFIDA.U8.U8MOMAPIFramework.dll如下图2.3、2.4、2.5所示。(2)VB:%U8SOFT%UFMOMU8APIFrameworkUFIDA.U8.U8APIFr
7、amework. tlb、%U8SOFT%UFMOMU8APIFrameworkUFIDA.U8.MomServiceCommon. tlb、%U8SOFT%UFMOMU8APIFrameworkUFIDA.U8.U8MOMAPIFramework. tlb、添加Microsoft XML v3.0引用如下图2.6、2.7所示。其中,%U8SOFT%表示U8-872的安装目录。图 2.3 添加对U8Login.dll引用图 2.4 添加对Interop.MSXML2.dll引用图 2.5 添加对U8API框架类库引用(.dll)图2.6 添加对U8API框架类库引用(.tlb)图2.7 添加M
8、icrosoft XML v3.0引用API调用添加必要的引用后,可以直接利用自动生成的代码示例(支持C#和VB两种语言),结合API接口详细描述,填入必要的参数值,就可以调用U8 API。总体上,对U8 API的调用分成七个步骤:1)构造u8login对象并登陆;2)构造环境上下文对象,传入login,并按需设置其它上下文参数;3)设置API地址标识(Url)参数;4)构造APIBroker;5)API参数赋值;6)调用API;7)获取返回结果。详细的API调用过程请看下文“API内容”中各个模块中介绍的“开发步骤”。下面重点介绍几个关键要点和步骤:环境上下文、API地址、APIBroker
9、、普通参数赋值、BO参数赋值。环境上下文环境上下文指在调用U8API时需要初始化的调用环境,包括Login、事务、特殊的业务参数等。环境上下文被初始化后,相关的环境参数会被业务API使用。U8EnvContext envContext = new U8EnvContext();Login需要将U8Login对象传递给环境上下文,U8Login对象必须已经登录过。envContext.U8Login = u8Login;事务如果需要由外部发起事务,则可以发起事务的ADOConnection对象传递给环境上下文:ADODB.ConnectionClass conn = new Connection
10、Class();envContext.BizDbConnection = conn;同时需要设置一个外部事务标记:envContext.IsIndependenceTransaction = true;特殊业务参数特殊业务参数指调用某些API需要设置的特定上下文参数,比如:销售的API必须要设置如VoucherType上下文参数,设置方法为:envContext.SetApiContext(VoucherType, 23); API地址API地址是指API在U8API系统中的唯一标识,也叫API的URI,调用API时,需要通过API地址构建一个代表此API的Broker对象:U8ApiAddr
11、ess myApiAddress = new U8ApiAddress(U8API/PurchaseOrder/VoucherSave);APIBrokerAPIBroker是所有U8API的调用代理接口。使用U8所有API都必须通过APIBroker间接调用。APIBroker作为一个服务代理中间件,起到了隔离API的提供者与使用者的作用,降低了耦合依赖关系。创建APIBroker必须传入API地址和环境上下文:U8ApiBroker broker = new U8ApiBroker(myApiAddress, envContext);普通参数赋值API参数分两种类型:BO参数和普通参数。普
12、通参数是指非单据表头表体类型的参数,包括基本类型参数(String、Integer等)、知名对象参数(Connection、DOMDocument等)。普通参数的赋值采用如下方式:broker.AssignNormalValue(voucherState, 2);BO参数赋值BO参数即单据表头或表体类型的参数。对BO参数,支持两种方式传入,一种传BO对象,另一种传DOM对象。以下分别介绍:传BO对象给BO表头参数或表体参数赋值,推荐使用BO对象(BussinessObject)。例如: BusinessObject DomHead = broker.GetBoParam(DomHead); D
13、omHead.RowCount = 10; /设置行数,不设置也可 /给BO对象的字段赋值,值可以是真实类型,也可以是无类型字符串 /以下代码示例只设置第一行值。各字段定义详见API服务接口定义 /* 以下是必输字段*/ DomHead0poid = ; /主关键字段,int类型 DomHead0dpodate = ; /日期,DateTime类型 DomHead0cpoid = ; /订单编号,string类型 /* 以下是非必输字段*/ DomHead0ipresent = ; /现存量,string类型 DomHead0cmaketime = ; /制单时间,DateTime类型 Dom
14、Head0cmodifytime = ; /修改时间,DateTime类型在此种情况下U8 API框架会对BO对象各字段进行参数校验。对字段进行赋值时,值可以是真实类型,也可以是无类型字符串。传DOM对象给BO表头参数或表体参数赋值,也支持直接传入DOM对象(DOMDocument)。例如:MSXML2.DOMDocumentClass domHead = new MSXML2.DOMDocumentClass();domHead.load(domHead.xml);broker.AssignNormalValue(domHead, domHead);但是,在此种情况下U8 API框架不会对D
15、OM对象进行参数验证。请在使用该方法之前,确保DOM对象的正确性。2.1.3API典型应用场景执行单一操作单一操作指一项任务只需要一个API完成,比如:单据新增、审核/弃审、删除等单一操作。这是API调用最常见的场景,只需按照API的接口规范构造参数直接调用即可。执行复合操作复合操作,即一项任务由多个API的协作来完成。比如,自定义的单据维护界面的主要逻辑,一般由以下四个步骤构成:8)加载单据;9)在编辑界面上显示;10)用户修改单据字段;11)提交保存。以上步骤需要进行两次API调用:1)加载单据时候调用“加载API”,以获取单据BO对象(或原始DOM对象)并在界面上展现;2)用户在修改单据
16、时其实就是在修改BO对象,用户保存单据时调用“保存API”,此时要将此BO对象传给“保存API”(而不用构造新的BO对象)。代码示例:首先,登陆;/构造u8login对象并登陆U8Login.clsLogin u8Login = new U8Login.clsLogin();String sSubId = AS;String sAccID = (default)001;String sYear = 2008;String sUserID = demo;String sPassword = ;String sDate = 2008-09-30;String sServer = localhost
17、;String sSerial = ;if (!u8Login.Login(ref sSubId, ref sAccID, ref sYear, ref sUserID, ref sPassword, ref sDate, ref sServer, ref sSerial) Console.WriteLine(登陆失败,原因: + u8Login.ShareString); Marshal.FinalReleaseComObject(u8Login); return;然后,通过LOAD接口获取BO对象;/构造环境上下文对象,传入login,并按需设置其它上下文参数U8EnvContext en
18、vContext = new U8EnvContext();envContext.U8Login = u8Login;/设置上下文参数/设置API地址标识(Url)U8ApiAddress myApiAddress = new U8ApiAddress(“装载单据的地址标识”);/构造APIBrokerU8ApiBroker broker = new U8ApiBroker(myApiAddress, envContext);/API参数赋值broker.AssignNormalValue(参数名, 参数值);/调用LOAD接口APIif (!broker.Invoke() /错误处理 Exc
19、eption apiEx = broker.GetException(); if (apiEx != null) if (apiEx is MomSysException) MomSysException sysEx = apiEx as MomSysException; Console.WriteLine(系统异常: + sysEx.Message); /todo:异常处理 else if (apiEx is MomBizException) MomBizException bizEx = apiEx as MomBizException; Console.WriteLine(API异常:
20、+ bizEx.Message); /todo:异常处理 /结束本次调用,释放API资源 broker.Release(); return;/获取表头或表体的BO对象,如果要取原始的XMLDOM对象结果,请使用GetResult(参数名)BusinessObject DomRet = broker.GetBoParam(表头或表体参数名);接着,BO对象经用户修改重新赋值,并传递给UPDATE接口提交保存;/修改获取的BO对象,对需要更改的字段重新赋值DomRet0字段名 = 新的字段值;/重新构造“新增或修改”API的地址标识myApiAddress = new U8ApiAddress(新
21、增或修改”API的地址标识);/重新构造APIBrokerbroker = new U8ApiBroker(myApiAddress, envContext);/表头或表体参数赋值broker.SetBoParam(表头或表体参数名, DomRet);/API参数赋值broker.AssignNormalValue(参数名, 参数值);/调用UPDATE接口APIif (!broker.Invoke() 最后,获取返回结果。/获取普通返回值System.String result = broker.GetReturnValue() as System.String;/获取out/inout参数
22、值/结束本次调用,释放API资源broker.Release();.2.API内容.2.1采购管理 功能介绍为了支持U8二次开发对业务单据的开发,本功能提供了实现采购业务单据各种操作功能的编程接口。使用采购管理的API开发接口,可以对库存管理中的采购到货单、采购普通发票、采购专用发票、采购订单、请购单、采购运费发票等单据进行审核、弃审、获取(或装载)、新增、修改、删除。使用环境必须安装.NET FrameWork 2.0;必须安装U8-872版本的采购管理产品;必须安装API适配器组件PUAPIConcrete.dll接口说明采购管理二次开发接口说明:审核单据-ConfirmPO方法参数:do
23、mHead 单据表头,DOM对象,必输API上下文:VoucherType 单据类型,具体类型参看API上下文描述bPositive 红蓝标识:True,蓝字 ;False,红字sBillType 为空串 sBusType 业务类型:普通采购,直运采购,受托代销弃审单据- CancelconfirmPO方法参数:domHead 单据表头,DOM对象,必输API上下文:VoucherType 单据类型,具体类型参看API上下文描述bPositive 红蓝标识:True,蓝字 ;False,红字sBillType 为空串 sBusType 业务类型:普通采购,直运采购,受托代销装载单据-Load方
24、法参数:DomHead 表头DOM对象domBody 表体DOM对象strWhere 过滤条件串varVoucherID 单据主表IDstrLocateWhere 定位条件串API上下文:VoucherType 单据类型,具体类型参看API上下文描述bPositive 红蓝标识:True,蓝字 ;False,红字sBillType 为空串 sBusType 业务类型:普通采购,直运采购,受托代销删除单据-Delete方法参数:DomHead 表头DOM对象domBody 表体DOM对象CurDom 返回DOM格式错误信息API上下文:VoucherType 单据类型,具体类型参看API上下文描
25、述bPositive 红蓝标识:True,蓝字 ;False,红字sBillType 为空串 sBusType 业务类型:普通采购,直运采购,受托代销新增或修改新单据- VoucherSave方法参数:DomHead 单据表头,DOM对象,必输 domBody 单据表体,DOM对象,必输 VoucherState 保存状态,必输。2增加;1修改 ;0非编辑curID 返回单据头ID CurDom 返回DOM格式错误信息UserMode 使用模式,0:CS;1:BSAPI上下文:VoucherType 单据类型,具体类型参看API上下文描述bPositive 红蓝标识:True,蓝字 ;Fals
26、e,红字sBillType 为空串 sBusType 业务类型:普通采购,直运采购,受托代销开发步骤实现采购单据某一功能,主要有以下七个步骤:1构造u8login对象并登陆 声明和创建u8login类对象前应该先引用U8API类库中的Interop.U8Login.dll,代码示例如下:U8Login.clsLogin u8Login = new U8Login.clsLogin(); /声明u8login对象String sSubId = AS; /登陆String sAccID = (default)001;String sYear = 2008;String sUserID = demo
27、;String sPassword = ;String sDate = 2008-09-30;String sServer = localhost;String sSerial = ;if(!u8Login.Login(ref sSubId, ref sAccID, ref sYear, ref sUserID, ref sPassword, ref sDate, ref sServer, ref sSerial) Console.WriteLine(登陆失败,原因: + u8Login.ShareString); Marshal.FinalReleaseComObject(u8Login);
28、 return; 如果当前环境中有login对象则可以省去第一步。2构造环境上下文对象,传入login,并按需设置其它上下文参数 U8EnvContext envContext = new U8EnvContext(); /构造环境上下文对象envContext.U8Login = u8Login; /传入login/设置上下文参数envContext.SetApiContext(VoucherType, new int(); /上下文数据类型:int,含义:单据类型envContext.SetApiContext(bPositive, new bool(); /上下文数据类型:bool,含义
29、:红蓝标识:True,蓝字envContext.SetApiContext(sBillType, new string(); /上下文数据类型:string,含义:为空串envContext.SetApiContext(sBusType, new string(); /上下文数据类型:string,含义:业务类型:普通采购,直运采购,受托代销如果是外部事务,则需要传递ADO.Connection对象,并将IsIndependenceTransaction设置为true: envContext.BizDbConnection = new ADO.Connection(); envContext.IsIndependenceTransaction = true;3设置API地址标识(Url)参数/如当前API“新增或修改”的地址标识为:U8API/PurchaseOrder/VoucherSave U8ApiAddress myApiAddress = new U8ApiAddress(U8API
copyright@ 2008-2022 冰豆网网站版权所有
经营许可证编号:鄂ICP备2022015515号-1