U8API开发手册(VB版) 下载本文

图 2.5 添加对U8Login.dll引用

图 2.6 添加对Integererop.MSXML2.dll引用

图 2.7 添加对U8API框架类库引用(.dll)

? API调用

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

总体上,对U8 API的调用分成六个步骤: 1) 构造u8login对象并登陆;

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

3) 构造APIBroker,调用Connect,传入API地址标识(Url)和环境上下文; 4) API参数赋值; 5) 调用API;

6) 获取返回结果。

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

下面重点介绍几个关键要点和步骤:环境上下文、API地址、APIBroker、普通参数赋值、BO参数赋值。

? 环境上下文

环境上下文指在调用U8API时需要初始化的调用环境,包括Login、事务、特殊的业务参数等。环境上下文被初始化后,相关的环境参数会被业务API使用。

Dim u8EnvCtx As New U8EnvContext

? Login

需要将U8Login对象传递给环境上下文,U8Login对象必须已经登录过。 Set u8EnvCtx.U8Login = ologin ? 事务

如果需要由外部发起事务,则可以发起事务的ADO Connection对象传递给环境上下文:

Set u8EnvCtx.BizDbConnection = new ADO.Connection()

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

u8EnvCtx.IsIndependenceTransaction = true

? 特殊业务参数

特殊业务参数指调用某些API需要设置的特定上下文参数,比如:销售的API必须要设置如VoucherType上下文参数,设置方法为:

u8EnvCtx.SetApiContext \VoucherType\

? API地址

API地址是指API在U8API系统中的唯一标识,也叫API的URI,通过该标识唯一确定一个U8API。如,API地址\U8API/SaleOrder/Save\代表销售订单中的“新增或修改”这样一个API接口。

? APIBroker

APIBroker是所有U8API的调用代理接口。使用U8所有API都必须通过APIBroker间接调用。APIBroker作为一个服务代理中间件,起到了隔离API的提供者与使用者的作用,

降低了耦合依赖关系。调用API的时候,需要首先创建一个APIBroker, 然后调用其Connect,传入API地址和环境上下文:

Dim u8apiBroker As New U8ApiComBroker

u8apiBroker.Connect \U8API/SaleOrder/Save\

? 普通参数赋值

API参数分两种类型:BO参数和普通参数。普通参数是指非单据表头/表体类型的参数,包括基本类型参数(String、Integer等)、知名对象参数(Connection、DOMDocument等)。普通参数的赋值采用如下方式:

u8apiBroker.AssignNormalValue \VoucherState\2

? BO参数赋值

BO参数即单据表头或表体类型的参数。对BO参数,支持两种方式传入,一种传BO对象,另一种传DOM对象。以下分别介绍: ? 传BO对象

给BO表头参数或表体参数赋值,推荐使用BO对象(BussinessObject)。 例如:

Dim domHead As BusinessObject

Set domHead = u8apiBroker.GetBoParam(\domHead\

domHead.RowCount = 1; '设置行数,不设置也可

'给BO对象的字段赋值,值可以是真实类型,也可以是无类型字符串 '以下代码示例只设置第一行值。各字段定义详见API服务接口定义

'****************************** 以下是必输字段****************************' domHead(0).SetValue \; '主关键字段,Integer类型 domHead(0).SetValue \; '日期,Date类型 domHead(0).SetValue \; '订单编号,String类型

'***************************** 以下是非必输字段****************************' domHead(0).SetValue \; '现存量,String类型 domHead(0).SetValue \; '制单时间,Date类型 domHead(0).SetValue \; '修改时间,Date类型

??

??

在此种情况下U8 API框架会对BO对象各字段进行参数校验。对字段进行赋值时,值可以是真实类型,也可以是无类型的字符串。 ? 传DOM对象

给BO表头参数或表体参数赋值,也支持直接传入DOM对象(DOMDocument)。 例如:

Dim domHead As New MSXML2.DOMDocument domHead.load \

u8apiBroker.AssignNormalValue \domHead \

但是,在此种情况下U8 API框架不会对DOM对象进行参数验证。请在使用该方法之前,确保DOM对象的正确性。

2.1.3 API典型应用场景 ? 执行单一操作

单一操作指一项任务只需要一个API完成,比如:单据新增、审核/弃审、删除等单一操作。这是API调用最常见的场景,只需按照API的接口规范构造参数直接调用即可。

? 执行复合操作

复合操作,即一项任务由多个API的协作来完成。比如,自定义的单据维护界面的主要逻辑,一般由以下四个步骤构成:

1) 加载单据;

2) 在编辑界面上显示; 3) 用户修改单据字段; 4) 提交保存。

以上步骤需要进行两次API调用: 1) 加载单据时候调用“加载API”,以获取单据BO对象(或原始DOM对象)并在界面

上展现;

2) 用户在修改单据时其实就是在修改BO对象,用户保存单据时调用“保存API”,此

时要将此BO对象传给“保存API”(而不用构造新的BO对象)。 ? 代码示例

(1) 首先,登陆;

'构造u8login对象并登陆 Dim ologin As Object

Set ologin = CreateObject(\U8Login.clsLogin\

If Not ologin.login(\, \, \, \, \, \, \) Then

MsgBox ologin.ShareString

(2) 然后,通过LOAD接口获取BO对象;

'构造环境上下文对象,传入login,并按需设置其它上下文参数 Dim u8EnvCtx As New U8EnvContext Set u8EnvCtx.U8Login = ologin '设置上下文参数

u8EnvCtx.SetApiContext \\上下文值\

??

'构造APIBroker,调用Connect,传入Api的地址标识(Url),传入上下文 Dim u8apiBroker As New U8ApiComBroker

u8apiBroker.Connect “装载单据的地址标识”, u8EnvCtx 'API参数赋值

u8apiBroker.AssignNormalValue \参数名\, \参数值\ ??