自定义服务介绍
1 简介
1.1 功能介绍
自定义服务可以将任何功能开发出来,这类服务不依附任何业务对象,出入参数可以完全自定义。通过自定义服务,可以拓展平台的API,满足一些个性化的需求。
1.2 应用场景
1)当标准操作服务无法满足接口需求时,用户可通过注册插件的方式发布自定义接口,自定义接口逻辑和返回参数;
2)预置自定义接口,提供给苍穹其他模块调用。
3)标准接口功能不满足时,我们会进行自定义接口的开发,并自定义返回格式(操作见附件)。
1.3 操作路径
路径:【开发服务云】→【开放平台】→【其他】→【API1.0】→【API服务管理1.0】
1.4 字段/按钮说明
字段说明:
字段名称 | 详细解释 |
API基本信息 | |
API编码 | API服务编码 |
API名称 | API服务名称 |
请求方式 | API请求方法,支持GET/POST |
所属应用 | 业务对象所属应用 |
授权用户 | 若仅指定用户可调用该API,可选择授权用户;若为空,则不限制 |
请求地址 | 请求url地址/app/ {appId}/{servicename},自动生成 appId:应用id,Servicename:API编码 |
内容格式 | 请求参数的内容格式,默认为application/json |
自定义方法 | 预先注册的自定义插件的方法名称 |
匿名访问 | 设置API匿名,API不需要通过认证即可调用,但存在数据泄露风险,谨慎使用 |
详细描述 | API详细描述及功能用途 |
请求头部 | |
参数名称 | 请求头参数名称 |
参数值 | 请求头参数值 |
说明 | 请求头参数说明 |
Query参数 | |
参数名称 | Query参数名称 |
参数类型 | Query参数类型 |
必填 | 默认为是 |
示例 | Query参数示例 |
说明 | Query参数说明 |
请求体/返回参数 | |
参数名称 | 请求体/返回参数名称 |
参数类型 | 请求体/返回参数类型 |
必填 | 默认为是 |
示例 | 请求体/返回参数示例 |
说明 | 请求体/返回参数说明 |
插件 | |
是否启用 | 插件开关,选择是否启用插件 |
插件名称 | 预先注册的插件名称 |
本单插件 | 默认为是 |
插件路径 | 预先注册的插件路径 |
描述说明 | 预先注册的插件说明 |
按钮说明:
按钮名称 | 详细解释 |
单据头 | |
保存 | 保存当前API服务信息 |
保存并新增 | 保存当前API服务信息,并打开新建API服务的弹窗 |
退出 | 退出当前界面 |
请求头 | |
增行 | 列表新增空白行 |
删行 | 删除勾选行数据,支持多条数据批量删除 |
上移 | 勾选请求头数据,点击按钮,行数据会上移一行 |
下移 | 勾选请求头数据,点击按钮,行数据会下移一行 |
请求结构示例 | 弹出请求结构体示例弹窗 |
Query参数 | |
增行 | 列表新增空白行 |
删行 | 点除勾选行数据,支持多条数据批量删除 |
从对象中添加 | 弹出对象选择弹窗,支持批量勾选,点击确定后会自动填充数据到query参数列表中 |
上移 | 勾选query参数数据,点击按钮,行数据会上移一行 |
下移 | 勾选query参数数据,点击按钮,行数据会下移一行 |
请求结构示例 | 弹出请求结构体示例弹窗 |
请求体/返回参数 | |
增行 | 列表新增空白行 |
增子行 | 勾选某行数据,点击按钮,会在该行参数下增加子行。当选择多行数据时,只会在勾选的第一条数据下增加子行 |
从对象中添加 | 点击按钮,弹出对象选择弹窗,支持批量勾选,点击确定后会自动填充数据到请求体/返回参数列表中 |
请求/返回结构示例 | 点击按钮,弹出请求结构体/返回结构体示例弹窗 |
删行 | 点击按钮,删除勾选行数据,支持多条数据批量删除 |
上移 | 勾选请求体数据,点击按钮,行数据会上移一行 |
下移 | 勾选请求体数据,点击按钮,行数据会下移一行 |
2 主要操作
2.1 注册自定义插件
自定义服务与操作服务的使用方式不同,自定义服务需要先开发插件,然后发布API,插件可以使用自定义的java插件或脚本插件,下面介绍自定义服务的调用流程。
首先需要开发人员创建一个类,实现IBillWebApiPlugin接口,并重写doCustomService()方法,在方法内实现自定义的相关逻辑。
自定义服务插件代码示例:
import kd.bos.bill.IBillWebApiPlugin; import kd.bos.entity.api.ApiResult; import java.util.Map; public class HelloWorldPlugin implements IBillWebApiPlugin { @Override public ApiResult doCustomService(Map<String, Object> params) { //实现业务逻辑。。。 ApiResult apiResult = new ApiResult(); apiResult.setSuccess(true); apiResult.setErrorCode("success"); apiResult.setMessage("HelloWorld Success"); apiResult.setData(null); return apiResult; } } |
2.2 维护API基本信息
打开【API服务管理】菜单,点击“新增”按钮,选择操作服务,进入到操作服务新增界面,录入API基本信息等字段,API请求地址自动生成。
2.3 维护请求/返回参数(非必填)
在页面上维护请求参数,请求头部默认包含参数 Content-type和 assesstoken。若为get类请求,可维护Query参数及示例,若为POST类请求,可维护请求体参数及示例。
同样的方式在页面上维护接口返回参数,上一步维护的请求参数和返回参数示例仅作为参考,实际返回的数据会自定义插件代码逻辑返回。
2.4 注册插件
在最下方插件栏,注册上一步开发的插件等信息,点击保存即可。
3 自定义插件方法
当开发注册自定义插件时,系统预置了两个版本的 ApiResult doCustomService 方法,分别为1.0和2.0版本,如果用户不去重写方法,会默认使用1.0版本的方法。
版本差异:
1.0 :当为get请求时,客户端只传querystring给服务端;当为post请求时,客户端只传请求体中的data给服务端。
2.0 :不论请求方式为get或post,客户端传给服务端的参数比1.0版本增加了requestURL、appId和Cookie。当为post请求时,客户端会同时传querystring和请求体中的data给服务端。
代码示例:
版本控制方法: @Override public String getVersion() { // TODO Auto-generated method stub return "abc"; // 当return值为空或”1.0”时 ,使用1.0版本;当Return值为其他非”1.0”文本字段,使用2.0版本 } 方法一(1.0版本): @Override public ApiResult doCustomService(Map<String, Object> params) { // TODO Auto-generated method stub String iobj = "这是返回"; return IBillWebApiPlugin.super.doCustomService(params); } 方法二(2.0版本): @Override public ApiResult doCustomService(WebApiContext ctx) { // TODO Auto-generated method stub return IBillWebApiPlugin.super.doCustomService(ctx); } |
在标准接口功能不满足时,我们会进行自定义接口的开发,如何自定义接口返回格式见附件。
更多
自定义服务介绍
本文2024-09-23 00:31:30发表“云苍穹知识”栏目。
本文链接:https://wenku.my7c.com/article/kingdee-cangqiong-140019.html