U8API开发手册(C#版)文档

U8API开发手册作者：商平锋版权所有：用友软件股份有限公司1.简介U8API是为U8客户化应用开发提供的一套标准化的U8ERP业务编程接口。是U8UAP二次开发体系的重要组成部分。它包括一整套涵盖U8ERP采购、销售、库存、制造（规划中）、财务（规划中）、基本档案（规划中）等业务模块的API接口资源。U8API的推出为U8标准产品更好的适应用户的个性化需求，更好的实现客户化交付提供了有力支持。U8API按照U8ERP业务产品模块进行分类，并以U8主要业务实体（单据、档案、凭证）作为操作对象，提供了常用的基本操作。比如：对于库存的收发单据，提供“新增”、“审核”、“弃审”、“删除”、“装载”、“修改”六个API接口。目前，U8API提供了供应链采购、销售、库存三个产品的所有单据的增删改、审核/弃审等API接口，后续版本会逐步将制造、财务、基本档案等模块的API纳入进来。U8API通过“U8API资源管理器”对U8范围内所有API进行集中统一分类管理，形成了一套完整的U8API资源库。U8API的使用者可以使用“U8API资源管理器”浏览、查看API及其接口定义，并可辅助进行代码生成（目前支持C#和VB语言）；API的开发者可以通过此工具发布、注册API，所有业务API都必须在“U8API资源管理器”中进行注册。U8API还提供了一套运行时调用框架——U8APIBroker。它是所有U8API的调用代理，用户要使用某个API只需调用U8APIBroker即可，无需直接访问真正的API。U8APIBroker作为一个服务代理中间件，起到了隔离API的提供者与使用者的作用，降低了耦合依赖关系。U8API与U8EAI接口从功能上看比较相识，但它们的特性有差别。U8API采用传统的编程模型，更靠近底层，业务逻辑粒度更细，而且还需要或依赖一些特定的上下文环境，比如：login、事务等；而U8EAI接口则是完全松耦合的，采用XML和请求/响应的消息传递模式，且业务粒度比较粗放。这些特性的差别决定了它们的应用领域不同，U8API更适合于U8内部的功能扩展和客户个性化开发，而U8EAI则适合外部系统与U8之间以业务数据交换为特征的应用集成开发。应用API总体应用过程API浏览查找在“开始”->“程序”->“用友ERP-U8”->“UAP”目录下找到“U8API资源管理器”，单击，登录，进入“U8API资源管理器”。在左侧“U8API”树形节点下，找到某某模块，如“库存管理”模块（可以看到下面列有很多个单据，如盘点单、采购入库单等），展开要操作的单据，分两个子节点：“事件”和“服务接口”，在“服务接口”下可以看到该单据提供的API接口，如“添加新单据”、“审核单据”等。双击这些节点出现该API的详细描述，如下图所示。在节点上右键单击弹出“上下文菜单”，在“代码示例”菜单项上弹出下一级子菜单，单击它们，如单击“C#代码示例”则可以看到调用该API的C#示例代码，如下图所示。直接拷贝这些代码，然后在集成开发环境（IDE）中编辑和编译这些代码，即能实现调用U8标准API。利用这些代码示例时，请按照其中每一步骤的提示说明正确操作，如添加必要的引用、按照自动生成的代码填入正确的参数等。正确使用则可以调用成功，否则会返回详细的以下代码中均以C#为例，VB语言请具体查看对应的VB代码示例部分。图2.SEQ图表\*ARABIC1接口描述图代码示例API调用过程组件引用针对两种语言，需要引用不同的组件。C#：%U8SOFT%\Interop\、%U8SOFT%\Interop\、%U8SOFT%\UFMOM\U8APIFramework\、%U8SOFT%\UFMOM\U8APIFramework\、%U8SOFT%\UFMOM\U8APIFramework\如下图、、所示。（2）VB：%U8SOFT%\UFMOM\U8APIFramework\tlb、%U8SOFT%\UFMOM\U8APIFramework\tlb、%U8SOFT%\UFMOM\U8APIFramework\tlb、添加MicrosoftXML引用如下图、所示。其中，%U8SOFT%表示U8-872的安装目录。图SEQ图表\*ARABIC添加对引用图添加对引用图添加对U8API框架类库引用（.dll）图添加对U8API框架类库引用(.tlb)图添加MicrosoftXML引用API调用添加必要的引用后，可以直接利用自动生成的代码示例（支持C#和VB两种语言），结合API接口详细描述，填入必要的参数值，就可以调用U8API。总体上，对U8API的调用分成七个步骤：构造u8login对象并登陆；构造环境上下文对象，传入login，并按需设置其它上下文参数；设置API地址标识(Url)参数；构造APIBroker；API参数赋值；调用API；获取返回结果。详细的API调用过程请看下文“API内容”中各个模块中介绍的“开发步骤”。下面重点介绍几个关键要点和步骤：环境上下文、API地址、APIBroker、普通参数赋值、BO参数赋值。环境上下文环境上下文指在调用U8API时需要初始化的调用环境，包括Login、事务、特殊的业务参数等。环境上下文被初始化后，相关的环境参数会被业务API使用。U8EnvContextenvContext=newU8EnvContext();Login需要将U8Login对象传递给环境上下文，U8Login对象必须已经登录过。=u8Login;事务如果需要由外部发起事务，则可以发起事务的ADOConnection对象传递给环境上下文：conn=newConnectionClass();=conn;同时需要设置一个外部事务标记：=true;特殊业务参数特殊业务参数指调用某些API需要设置的特定上下文参数，比如：销售的API必须要设置如VoucherType上下文参数，设置方法为：("VoucherType",23);API地址API地址是指API在U8API系统中的唯一标识，也叫API的URI，调用API时，需要通过API地址构建一个代表此API的Broker对象：U8ApiAddressmyApiAddress=newU8ApiAddress("U8API/PurchaseOrder/VoucherSave");APIBrokerAPIBroker是所有U8API的调用代理接口。使用U8所有API都必须通过APIBroker间接调用。APIBroker作为一个服务代理中间件，起到了隔离API的提供者与使用者的作用，降低了耦合依赖关系。创建APIBroker必须传入API地址和环境上下文：U8ApiBrokerbroker=newU8ApiBroker(myApiAddress,envContext);普通参数赋值API参数分两种类型：BO参数和普通参数。普通参数是指非单据表头表体类型的参数，包括基本类型参数（String、Integer等）、知名对象参数（Connection、DOMDocument等）。普通参数的赋值采用如下方式：("voucherState",2);BO参数赋值BO参数即单据表头或表体类型的参数。对BO参数，支持两种方式传入，一种传BO对象，另一种传DOM对象。以下分别介绍：传BO对象给BO表头参数或表体参数赋值，推荐使用BO对象（BussinessObject）。例如：BusinessObjectDomHead=("DomHead"); =10;2008-09-30ETFrameWork；必须安装U8-872版本的采购管理产品；必须安装API适配器组件接口说明采购管理二次开发接口说明：审核单据-ConfirmPO方法参数：domHead ——单据表头，DOM对象，必输API上下文：VoucherType——单据类型，具体类型参看API上下文描述bPositive——红蓝标识：True,蓝字；False,红字sBillType——为空串sBusType——业务类型：普通采购,直运采购,受托代销弃审单据-CancelconfirmPO方法参数：domHead ——单据表头，DOM对象，必输API上下文：VoucherType——单据类型，具体类型参看API上下文描述bPositive——红蓝标识：True,蓝字；False,红字sBillType——为空串sBusType——业务类型：普通采购,直运采购,受托代销装载单据-Load方法参数：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上下文描述bPositive——红蓝标识：True,蓝字；False,红字sBillType——为空串sBusType——业务类型：普通采购,直运采购,受托代销新增或修改新单据-VoucherSave方法参数：DomHead ——单据表头，DOM对象，必输domBody ——单据表体，DOM对象，必输VoucherState ——保存状态，必输。2增加；1修改；0非编辑curID ——返回单据头IDCurDom ——返回DOM格式错误信息UserMode ——使用模式，0：CS；1:BSAPI上下文：VoucherType——单据类型，具体类型参看API上下文描述bPositive——红蓝标识：True,蓝字；False,红字sBillType——为空串sBusType——业务类型：普通采购,直运采购,受托代销开发步骤实现采购单据某一功能，主要有以下七个步骤：构造u8login对象并登陆声明和创建u8login类对象前应该先引用U8API类库中的，代码示例如下：u8Login=new();2008-09以上获取的行数是BO对象的实际行数。ETFrameWork；必须安装U8-872版本的销售管理产品；必须安装API适配器组件；接口说明销售管理二次开发接口及参数说明：审核或弃审单据-Audit方法参数：domHead ——单据表头，DOM对象，必输bVerify ——审核/弃审标志，必输。true表审核；false表弃审API上下文：VoucherType ——单据类型，必输。具体类型参看API上下文描述删除单据-Delete方法参数：domHead ——单据表头，DOM对象，必输API上下文：VoucherType ——单据类型，必输。具体类型参看API上下文描述装载单据-Load方法参数：domHead ——单据表头，DOM对象，必输domBody ——单据表体，DOM对象，必输VouchID ——需要装载的单据号，可选blnAuth ——是否控制权限：trueAPI上下文：VoucherType ——单据类型，必输。具体类型参看API上下文描述新增或修改单据-Save方法参数：domHead ——单据表头，DOM对象，必输domBody ——单据表体，DOM对象，必输VoucherState ——保存状态，必输。0增加；1修改VNewID ——单据的id，可选DomConfig ——ATO,PTO选配配置，必输，可设置为nothingAPI上下文：VoucherType ——单据类型，必输。具体类型参看API上下文描述开发步骤实现销售单据某一功能，主要有以下七个步骤：构造u8login对象并登陆声明和创建u8login类对象前应该先引用U8API类库中的，代码示例如下：u8Login=new();2008-09以上获取的行数是BO对象的实际行数。ETFrameWork；必须安装U8-872版本的库存管理产品；必须安装API适配器组件接口说明库存管理二次开发接口说明：审核单据-Audit方法参数：sVoucherType ——单据类型：01VoucherId ——单据IDerrMsg ——错误信息cnnFrom ——连接对象(调用方控制事务时需要传入连接对象)TimeStamp ——单据时间戳(用于检查单据是否修改，空串时不检查)domMsg ——返回DOM格式的信息:主要是可用量信息bCheck ——是否进行业务检查(是否控制可用量)bBeforCheckStock——是否检查可用量bList——传入falseMakeWheres——传空sWebXml——传入空串oGenVouchIds——获取单据ID列表(返回审核时自动生成的单据的id列表,传空)弃审单据-CancelAudit方法参数：sVoucherType ——单据类型：01VoucherId ——单据IDerrMsg ——错误信息cnnFrom ——连接对象(由调用方控制事务时必须传入)TimeStamp ——单据时间戳(用于检查单据是否修改，空串时不检查)domMsg ——超可用量提示信息DOM对象(返回DOM格式的信息)bCheck ——是否进行业务检查bBeforCheckStock——是否检查可用量bList——传入false装载单据-Load方法参数：sVoucherType ——单据类型：01sWhere ——条件串DomHead ——表头DOM对象domBody ——表体DOM对象domPos ——货位DOM对象errMsg ——错误信息bGetBlank ——是否获取空白单据sBodyWhere_Order——表体排序方式字段注意：其中sWhere设计为:如果按单据号加载，则语法为ccode=N'要加载的单据号'，例如("sWhere","ccode=N加上N代表存入数据库时以Unicode格式存储。N'string'表示string是个Unicode字符串Unicode字符串的格式与普通字符串相似，但它前面有一个N标识符（N代表SQL-92标准中的国际语言(NationalLanguage)）。N前缀必须是大写字母。例如，'Michél'是字符串常量而N'Michél'则是Unicode常量。Unicode常量被解释为Unicode数据，并且不使用代码页进行计算。Unicode常量确实有排序规则，主要用于控制比较和区分大小写。为Unicode常量指派当前数据库的默认排序规则，除非使用COLLATE子句为其指定了排序规则。Unicode数据中的每个字符都使用两个字节进行存储，而字符数据中的每个字符则都使用一个字节进行存储。有关更多信息，请参见使用Unicode数据。Unicode字符串常量支持增强的排序规则。'0000000001加上N代表存入数据库时以Unicode格式存储。N'string'表示string是个Unicode字符串Unicode字符串的格式与普通字符串相似，但它前面有一个N标识符（N代表SQL-92标准中的国际语言(NationalLanguage)）。N前缀必须是大写字母。例如，'Michél'是字符串常量而N'Michél'则是Unicode常量。Unicode常量被解释为Unicode数据，并且不使用代码页进行计算。Unicode常量确实有排序规则，主要用于控制比较和区分大小写。为Unicode常量指派当前数据库的默认排序规则，除非使用COLLATE子句为其指定了排序规则。Unicode数据中的每个字符都使用两个字节进行存储，而字符数据中的每个字符则都使用一个字节进行存储。有关更多信息，请参见使用Unicode数据。Unicode字符串常量支持增强的排序规则。如果按单据ID加载，则语法为id=XXX，例如("sWhere","id=1")。删除单据-Delete方法参数：sVoucherType ——单据类型：01VoucherId ——单据IDerrMsg ——错误信息cnnFrom ——连接对象（由调用方控制事务时需要传入连接对象）TimeStamp ——单据时间戳domMsg——返回DOM格式的信息：主要是检查可用量和控制可用量信息bCheck ——是否进行业务检查BeforCheckStock ——是否检查可用量bList ——传入false添加新单据-Add方法参数：sVoucherType ——单据类型：01DomHead ——表头DOM对象domBody ——表体DOM对象domPosition ——货位DOM对象：传空errMsg ——返回错误信息cnnFrom——连接对象，如果由调用方控制事务，则需要设置此连接对象，否则传空VoucherId ——返回单据IDdomMsg——返回DOM格式的信息：主要返回可用量和现存量的错误信息bCheck ——是否进行业务检查(是否控制可用量)bBeforCheckStock ——是否检查可用量(检查可用量)bIsRedVouch ——是否红字单据sAddedState——传空字符串bReMote ——是否远程修改单据-Update方法参数：sVoucherType——单据类型：01DomHead ——表头DOM对象domBody ——表体DOM对象domPosition ——货位DOM对象errMsg ——错误信息cnnFrom ——连接对象domMsg ——超可用量提示信息DOM对象（返回DOM格式的信息）bCheck ——是否进行业务检查bBeforCheckStock——是否检查可用量bIsRedVouch ——是否红字单据sAddedState ——修改状态bUpdateNeedEas ——传true开发步骤实现库存单据某一功能，主要有以下七个步骤：构造u8login对象并登陆声明和创建u8login类对象前应该先引用U8API类库中的，代码示例如下：u8Login=new();2008-09以上获取的行数是BO对象的实际行数。//获取BO对象各字段的值。以下代码示例只取第一行。字段定义详见API服务接口定义/******************************以下是必输字段****************************/intid=(DomHeadRet[0]["id"]);//主关键字段，int类型stringc