U8API开发手册.docx

资源描述

U8API开发手册.docx

《U8API开发手册.docx》由会员分享，可在线阅读，更多相关《U8API开发手册.docx（28页珍藏版）》请在冰豆网上搜索。

U8API开发手册.docx

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采用传统的编程模型，更靠近底层，业务逻辑粒度更细，而且还需要或依赖一些特定的上下文环境，比如：

这些特性的差别决定了它们的应用领域不同，U8API更适合于U8内部的功能扩展和客户个性化开发，而U8EAI则适合外部系统与U8之间以业务数据交换为特征的应用集成开发。

应用

.1.API总体应用过程

2.1.1API浏览查找

在“开始”->“程序”->“用友ERP-U8”->“UAP”目录下找到“U8API资源管理器”，单击，登录，进入“U8API资源管理器”。

在左侧“U8API”树形节点下，找到某某模块，如“库存管理”模块（可以看到下面列有很多个单据，如盘点单、采购入库单等），展开要操作的单据，分两个子节点：

“事件”和“服务接口”，在“服务接口”下可以看到该单据提供的API接口，如“添加新单据”、“审核单据”等。

双击这些节点出现该API的详细描述，如下图所示。

在节点上右键单击弹出“上下文菜单”，在“代码示例”菜单项上弹出下一级子菜单，单击它们，如单击“VB代码示例”则可以看到调用该API的VB示例代码，如下图所示。

直接拷贝这些代码，然后在集成开发环境（IDE）中编辑和编译这些代码，即能实现调用U8标准API。

利用这些代码示例时，请按照其中每一步骤的提示说明正确操作，如添加必要的引用、按照自动生成的代码填入正确的参数等。

正确使用则可以调用成功，否则会返回详细的错误信息。

以下代码中均以VB为例，C#语言请具体查看对应的C#代码示例部分。

图2.1接口描述

图代码示例

2.1.2API调用过程

组件引用

针对两种语言，需要引用不同的组件。

（1）VB：

%U8SOFT%\UFMOM\U8APIFramework\tlb、%U8SOFT%\UFMOM\U8APIFramework\tlb、%U8SOFT%\UFMOM\U8APIFramework\tlb、

添加MicrosoftXML引用

如下图、所示。

（2）C#：

%U8SOFT%\Integererop\、

%U8SOFT%\Integererop\、%U8SOFT%\UFMOM\U8APIFramework\、%U8SOFT%\UFMOM\U8APIFramework\、%U8SOFT%\UFMOM\U8APIFramework\如下图、、所示。

其中，%U8SOFT%表示U8-872的安装目录。

图添加对U8API框架类库引用（.tlb）

图添加MicrosoftXML引用

图添加对引用

图添加对U8API框架类库引用（.dll）

API调用

添加必要的引用后，可以直接利用自动生成的代码示例（支持VB和C#两种语言），结合API接口详细描述，填入必要的参数值，就可以调用U8API。

总体上，对U8API的调用分成六个步骤：

1）构造u8login对象并登陆；

2）构造环境上下文对象，传入login，并按需设置其它上下文参数；

3）构造APIBroker，调用Connect,传入API地址标识（Url）和环境上下文；

4）API参数赋值；

5）调用API；

6）获取返回结果。

详细的API调用过程请看下文“API内容”中各个模块中介绍的“开发步骤”。

下面重点介绍几个关键要点和步骤：

环境上下文、API地址、APIBroker、普通参数赋值、BO参数赋值。

环境上下文

环境上下文指在调用U8API时需要初始化的调用环境，包括Login、事务、特殊的业务参数等。

环境上下文被初始化后，相关的环境参数会被业务API使用。

Dimu8EnvCtxAsNewU8EnvContext

需要将U8Login对象传递给环境上下文，U8Login对象必须已经登录过。

Set=ologin

事务

如果需要由外部发起事务，则可以发起事务的ADOConnection对象传递给环境上下文：

Set=new（）

同时需要设置一个外部事务标记：

=true

特殊业务参数

特殊业务参数指调用某些API需要设置的特定上下文参数，比如：

销售的API必须要设置如VoucherType上下文参数，设置方法为：

"VoucherType",23

API地址

API地址是指API在U8API系统中的唯一标识，也叫API的URI，通过该标识唯一确定一个U8API。

如，API地址"U8API/SaleOrder/Save"代表销售订单中的“新增或修改”这样一个API接口。

APIBroker

APIBroker是所有U8API的调用代理接口。

使用U8所有API都必须通过APIBroker间接调用。

APIBroker作为一个服务代理中间件，起到了隔离API的提供者与使用者的作用，降低了耦合依赖关系。

调用API的时候，需要首先创建一个APIBroker,然后调用其Connect,传入API地址和环境上下文：

Dimu8apiBrokerAsNewU8ApiComBroker

"U8API/SaleOrder/Save",u8EnvCtx

普通参数赋值

API参数分两种类型：

BO参数和普通参数。

普通参数是指非单据表头/表体类型的参数，包括基本类型参数（String、Integer等）、知名对象参数（Connection、DOMDocument等）。

普通参数的赋值采用如下方式：

"VoucherState",2

BO参数赋值

BO参数即单据表头或表体类型的参数。

对BO参数，支持两种方式传入，一种传BO对象，另一种传DOM对象。

以下分别介绍：

传BO对象

给BO表头参数或表体参数赋值，推荐使用BO对象（BussinessObject）。

例如：

DimdomHeadAsBusinessObject

SetdomHead=（"domHead"）

=1;'设置行数，不设置也可

'给BO对象的字段赋值，值可以是真实类型，也可以是无类型字符串

'以下代码示例只设置第一行值。

各字段定义详见API服务接口定义

'******************************以下是必输字段****************************'

domHead（0）.SetValue"poid","";'主关键字段，Integer类型

domHead（0）.SetValue"dpodate","";'日期，Date类型

domHead（0）.SetValue"cpoid","";'订单编号，String类型

……

'*****************************以下是非必输字段****************************'

domHead（0）.SetValue"ipresent","";'现存量，String类型

domHead（0）.SetValue"cmaketime","";'制单时间，Date类型

domHead（0）.SetValue"cmodifytime","";'修改时间，Date类型

……

在此种情况下U8API框架会对BO对象各字段进行参数校验。

对字段进行赋值时，值可以是真实类型，也可以是无类型的字符串。

传DOM对象

给BO表头参数或表体参数赋值，也支持直接传入DOM对象（DOMDocument）。

例如：

DimdomHeadAsNew

"domHead",domHead

但是，在此种情况下U8API框架不会对DOM对象进行参数验证。

请在使用该方法之前，确保DOM对象的正确性。

2.1.3API典型应用场景

执行单一操作

单一操作指一项任务只需要一个API完成，比如：

单据新增、审核/弃审、删除等单一操作。

这是API调用最常见的场景，只需按照API的接口规范构造参数直接调用即可。

执行复合操作

复合操作，即一项任务由多个API的协作来完成。

比如，自定义的单据维护界面的主要逻辑，一般由以下四个步骤构成：

7）加载单据；

8）在编辑界面上显示；

9）用户修改单据字段；

10）提交保存。

以上步骤需要进行两次API调用：

1）加载单据时候调用“加载API”，以获取单据BO对象（或原始DOM对象）并在界面上展现；

2）用户在修改单据时其实就是在修改BO对象，用户保存单据时调用“保存API”，此时要将此BO对象传给“保存API”（而不用构造新的BO对象）。

代码示例

（1）首先，登陆；

'构造u8login对象并登陆

DimologinAsObject

Setologin=CreateObject（""）

IfNot（"AS","（default）@001","2008","demo","","2008-7-7","localhost"）Then

MsgBox

（2）然后，通过LOAD接口获取BO对象；

'构造环境上下文对象，传入login，并按需设置其它上下文参数

Dimu8EnvCtxAsNewU8EnvContext

Set=ologin

'设置上下文参数

"VoucherType","上下文值"

……

'构造APIBroker,调用Connect,传入Api的地址标识（Url），传入上下文

Dimu8apiBrokerAsNewU8ApiComBroker

“装载单据的地址标识”,u8EnvCtx

'API参数赋值

"参数名","参数值"

……

'调用LOAD接口API

If（）=FalseThen

'错误处理

MsgBox（）

If=ExceptionType_BusinessThen

'处理API业务错误

ElseIf=ExceptionType_SystemThen

'处理系统错误

EndIf

Else

'获取返回结果

'获取表头或表体的BO对象，如果要取原始的XMLDOM对象结果，请使用GetResult（参数名）

DimdomHeadOrBodyRetAsBusinessObject

SetdomHeadOrBodyRet=（"表头或表体参数名"）

MsgBox'获取返回BO对象的行数

……

EndIf

（3）接着，BO对象经用户修改重新赋值,并传递给UPDATE接口提交保存；

'修改获取的BO对象，对需要更改的字段重新赋值

domHeadOrBodyRet（0）.SetValue"字段名","新的字段值"

……

'重传入新“新增或修改”API的地址标识和环境上下文

"新增或修改”API的地址标识",u8EnvCtx

'表头或表体参数赋值

"表头或表体参数名",domHeadOrBodyRet

'API参数赋值

"参数名","参数值"

……

'调用UPDATE接口API

If（）=FalseThen

……

EndIf

（4）最后，获取返回结果。

'获取普通返回值

DimresultAsString

result=CStr（））

'获取out/inout参数值

……

'结束本次调用，释放API资源

Setu8apiBroker=Nothing

.2.API内容

.2.1采购管理

功能介绍

为了支持U8二次开发对业务单据的开发，本功能提供了实现采购业务单据各种操作功能的编程接口。

使用采购管理的API开发接口，可以对库存管理中的采购到货单、采购普通发票、采购专用发票、采购订单、请购单、采购运费发票等单据进行审核、弃审、获取（或装载）、新增、修改、删除。

使用环境

必须安装.NETFrameWork；

必须安装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——单据主表ID

strLocateWhere——定位条件串

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——返回单据头ID

CurDom——返回DOM格式错误信息

UserMode——使用模式，0：

CS；1:

API上下文：

VoucherType——单据类型，具体类型参看API上下文描述

bPositive——红蓝标识：

True,蓝字；False,红字

sBillType——为空串

sBusType——业务类型：

普通采购,直运采购,受托代销

开发步骤

调用采购单据某一API，主要有以下六个步骤：

1．构造u8login对象并登陆

声明和创建u8login类对象前应该先引用U8API类库中的，代码示例如下：

DimologinAsObject

Setologin=CreateObject（""）'声明u8login对象

'登陆

IfNot（"AS","（default）@001","2008","demo","","2008-7-7","localhost"）Then

MsgBox

注意：

如果当前环境中有login对象则可以省去第一步。

2．构造环境上下文对象，传入login，并按需设置其它上下文参数

Dimu8EnvCtxAsNewU8EnvContext'构造环境上下文对象

Set=ologin'传入login

'设置上下文参数

"VoucherType","上下文值"'上下文数据类型：

int，含义：

单据类型，采购订单

"bPositive","上下文值"'上下文数据类型：

bool，含义：

红蓝标识：

True,蓝字

"sBillType","上下文值"'上下文数据类型：

string，含义：

为空串

"sBusType","上下文值"'上下文数据类型：

string，含义：

业务类型：

普通采购,直运采购,受托代销

注意：

如果是外部事务，则需要传递对象，并将IsIndependenceTransaction设置为true：

Set=new（）

=true

3．构造ApiBroker对象,调用Connect,传入API的地址标识（Url）和环境上下文

Dimu8apiBrokerAsNewU8ApiComBroker

"U8API/PurchaseOrder/VoucherSave",u8EnvCtx

4．API对象参数赋值

1）给BO表头参数DomHead或表体参数domBody赋值有两种方法，如下：

方法一是直接传入对象，代码如下：

DimdomHeadAsNew

"DomHead",domHead

方法二是构造BusinessObject对象，具体方法如下：

'首先通过GetBoParam方法获取表头或表体参数

DimDomHeadAsBusinessObject

SetDomHead=（"DomHead"）

=1'设置行数

'给BO对象的字段赋值，值可以是真实类型，也可以是无类型字符串

'以下代码示例只设置第一行值。

各字段定义详见API服务接口定义

注意：

表体的行数只能为一行，可以对表体设置多行。

当设置行数为某个值时，行数并不限定为该最大值，可以一直顺序添加至任意行，但有一个规则：

例如当设置为10时，可以对第0、1、……9行赋值，当对第10行赋值时候，则会顺序添加一个新行，但此时是不能对第11行赋值的，当添加一个新行（第10行）后，又可以对第11行进行赋值。

'******************************以下是必输字段*****************************'

DomHead（0）.SetValue"poid","字段值"'主关键字段，Integer类型

DomHead（0）.SetValue"cbustype","字段值"'业务类型，String类型

DomHead（0）.SetValue"dpodate","字段值"'日期，Date类型

DomHead（0）.SetValue"cpoid","字段值"'订单编号，String类型

……

'*****************************以下是非必输字段****************************'

DomHead（0）.SetValue"ipresent","字段值"'现存量，String类型

DomHead（0）.SetValue"cmaketime","字段值"'制单时间，Date类型

DomHead（0）.SetValue"cmodifytime","字段值"'修改时间，Date类型

……

2）给普通参数赋值

例如，

'给普通参数VoucherState（参数名）赋值。

此参数的数据类型为Integer，此参数按值传递，具体请参考服务接口定义

"VoucherState","参数值"'参数类型：

Integer

注意：

所有参数名不限大小写。

3）给“OUT型”参数赋值

为方便用户使用U8API，如果参数数据类型为一般值类型，如String、Integer、Long、Double、Boolean、Date等，则不必传入一个参数变量（传入也可）；否则，则必须一个参数变量。

如：

……

'该参数curID为OUT型参数，由于其数据类型为String，为一般值类型，因此不必传入一个参数变量。

在API调用返回时，可以通过GetResult（"curID"）获取

'该参数CurDom为OUT型参数，由于其数据类型为，非一般值类型，因此必须传入一个参数变量。

在API调用返回时，可以直接使用该参数

DimCurDomAsNew

"CurDom",CurDom'参数类型：

……

当不传入一个参数变量时，在API调用返回时，可以通过GetResult（参数名）获取其值；当不必传入一个参数变量时，在API调用返回时，可以直接引用该参数。

4）给“INOUT型”参数赋值

对“INOUT型”型参数，则不论是否是一般值类型，都需要传入参数变量。

其他与“OUT型”参数一样。

5．调用API

If（）=FalseThen

'错误处理

MsgBox（）

If=ExceptionType_BusinessThen

'处理API业务错误

ElseIf=ExceptionType_SystemThen

'处理系统错误

EndIf

注意：

对调用失败，可以获取出错信息，如果是API框架的原因，则报告MomSysException异常，如果是业务组件的原因，则报告MomBizException异常。

6．获取返回结果

1）获取BO对象

在“装载单据”时，通过GetBoParam方法获取表头或表体参数

DimDomHeadRetAsBusinessObject

SetDomHeadRe

展开阅读全文