Webapi作为系统切入点,有太多痛楚。往往典型的符合RestFul规范的系统都会有类似swagger的调测程序。对于星空整体抽象结构而言,也有webapi的表单作为切入向导。那么,要怎么写好一个对接系统,出现的问题能够快速解决。
星空是一个分布式的SOA框架结构,由于是抽象的领域模型设计思想,对外暴露的接口可以利用外观方法,完成操作对接。说白了,星空整体就是一个DynamicForm界面,其他界面都是动态构造的。
那我们拿到需求需要如何下手呢?
一、明确操作定义。
操作定义:在星空里面做简单的增删改查,基本操作可以满足
增:Save,这个时候FID,FEntryId,应当为0;
删:Delete,利用编码或者内码FID、FEntryId来删除;
改:Save,改是基于已经存在的源单进行变更保存,所以FID或者FEntryId必填
查:View/ExecuteBillQuery,基于编码或者过滤条件来查看
提交、审核、反审核、表头业务操作:与保存是一类逻辑操作,利用内码操作。
下推:下推逻辑分为两种,调用PUSH操作,进行整单/整行下推,在下推返回的内码里面更改单据行数据信息,或者自行利用Save操作,创建关联,构建下推关联。
除此之外,我们可以采用反向思路,异构系统中的JSON数据包,不做处理,在星空中写自定义的WebApi接口,系统中可以利用更多的服务操作,甚至可以动态构建View视图,完成复杂的业务逻辑。(后面会讲到)
(Administrator登录,在搜索框中输入 webapi,既可查看单据)
二、根据操作定义写WebApi
既然知道操作了,WebApi通用步骤是登录、传Model数据包。
1. 登录
// 使用webapi引用组件Kingdee.BOS.WebApi.Client.dll K3CloudApiClient client = new K3CloudApiClient("http://k3cloud/"); var loginResult = client.ValidateLogin("5e60ba7e8d9724","Administrator","888888",2052); var resultType = JObject.Parse(loginResult)["LoginResultType"].Value<int>(); if (resultType == 1) { //TODO 执行操作代码 }
2. 执行操作
client.@Operate(@FormId,@data); 这里有两个参数,参数如何写,需要怎么查找,下面提供思路。
@Operate,即操作,第一步确定的操作,具体每个不同操作可以查看图一提示搜索的webapi查看。
@FormId,即表单标识,无论采购订单、销售订单、生产订单,都有元数据对应唯一标识,BOSIDE是我们主要的辅助工具,在BOSIDE中,我们看到整单标识。
或者我们在Webapi测试界面也有唯一标识。
@data,WebApi测试界面中,无论是哪个操作定义,都有对应的data格式,每种操作格式提供的参数大同小异。
以保存为例,2.1~2.9为选用参数,全部为非必录,2.10是我们最主要的参数内容,必录模型包。下面对参数进行基本讲解,未讲解到的就是对应的字面意思,不需要其他解读。
增、改:
2.1,2.2中括号内容针对单据体操作的时候,我们要增加单据体标识确定所在的单据体。以采购订单明细信息的物料编码为例,我们应当写作 FPOOrderEntry.FMaterialId
2.3 如果目标数据大于传入数据行,表示目标数据有多余的行需要删除,其他数据覆盖,仅在编辑数据行的时候使用。
2.8 NumberSearch,我们在传入基础资料保存的时候,例如FMaterialId:{FNumber:”123”},我们通常是以FNumber去搜索基础资料的,使用FMaterialId的话,会需要先知道对应物料ID。默认开启编码搜索的话,我们所有的基础资料都应该使用FNumber。
删、查、提交、审核、反审核、表头业务操作:
这类操作表头都会有Numbers和Ids 两个参数,这两个是随机选其一的,不需要都填写。选择一个方便且唯一的操作即可。
3. 录单、顺序
WebAPI的工作原理通俗来说,就是模拟录单的过程,根据传入的Json数据包构造的每个字段值,按顺序逐一模拟录单填充(录入)对应字段的值,触发此字段的相关值更新事件、实体服务和插件逻辑。构造完成整个单据的数据包之后,调用Save保存接口(Submit提交、Audit接口),并对应触发保存(提交、审核)的操作校验、操作逻辑、操作单据插件逻辑等整个过程。
模拟录单
在业务员操作录单的时候,我们经常会存在值更新、实体服务规则、代码值更新等影响,导致一个值的变动,其他值也会随着变动。比如,我们在采购订单上录入物料的时候,录入供应商,会根据供应商的价目表等信息,清空已经填写分录行的价格等信息。
顺序
既然录单的顺序已经规定了,那么录入顺序也需要按照系统字段列表属性顺序,从前往后,否则就存在一定的相互覆盖值的情况。
大致就这么多,后续会在附件部分中,贴出可以正常对接系统的JSON数据包示例。
三、自定义的WebApi
熟悉MVC结构的研发应该都清楚,.Net框架的基础结构是通过基础管道中构建HttpApplication和HttpContext,对Http.Sys接收到的请求,进行管道处理。到达HttpModule进行拦截过后,通过路由节点转到正确的Controller进行业务处理。
整个管道过程处理认证、授权等一系列问题,最后在星空的KDsvcHandle的HttpHandle拦截处理业务请求。
那么,星空的自定义webapi利用的也是这个思路,继承KDBaseService,请求路径是xxx.common.kdsvc,到达KDSvcHandle后,通过反射执行我们的操作服务。
按照前面系统预置的webapi示例一样,我们应当先登录,然后在TODO里面执行如何Service示例是Kingdee.K3.SCM.WebApi.ServicesStub.PushSerivce,具体写法是,
这类操作方法,就比较容易发挥想象了,我们也可以通过POST的URL请求来达到目的,这样就可以做一个自定义的前端网页,从CLOUD中抓取服务数据。
总结:
上面的方法,仅仅是用作基本的Webapi书写方法,但实际中还会遇到不同单据不用的业务逻辑影响。
如果在做单结果不与实际表单结果一致的情况下,可以自己在PC端模拟录单,按照webapi的赋值顺序做出来的单是否一致,哪些受影响,即可直观感受!
友情链接
webapi字段格式 | WebApi返回定制结果 | WebApi 对接的疑难杂症 |
webapi单据查询接口 | ||
WebApi到底怎么写.docx(845.31KB)
推荐阅读