API协议太多,如何高效集成?快速点进激活技能!
如同不同国家和地区之间存在不同的语言一样,在计算机的世界里也有不同的接口协议:基于SOAP的WebService,基于RESTful的WebAPI,以及像SAP和MQ一样特殊的接口协议等等。
面对如此众多的协议,有没有什么高效的方法架起不同系统间的“桥梁”?是通过预置大量不同类型的接口?还是从中抽象出一个共通的框架?
让我们从云之家集成这个真实案例来一探究竟吧。
1 场景介绍
云之家作为新一代智能协同云服务产品,可以连接企业现有业务(SaaS产品),帮助企业/团队打破部门与地域限制,提高沟通与协作效率。
因此,云之家在企业数字生态化建设过程中起到了至关重要的作用,与不同SaaS产品之间集成的需求也就应运而生。
那云之家与各业务系统(SaaS产品)的集成如何高效实现呢?
用户可以将云之家的接口(如:人员同步、组织同步等)登记到集成服务云,由集成服务云去完成复杂的身份鉴权、限流、监控等工作,简化开发者的工作,一次配置,多次可用。同理,企业微信,钉钉也可以。
所以,集成服务云作为一个中间媒介,为了满足客户复杂的业务需求,除了预置大量常用的接口外,还提供了通用框架让用户配置其他系统的连接方式。
通过该框架,用户可以根据云之家的开放API调用机制新建连接类型并配置前台表单。然后,即可把前台的连接配置作为外部系统的一次性鉴权机制,无需重复考虑外部系统的连接和API的调用问题。
登记外部系统API的完整步骤图
集成服务云的API集成框架具体如何使用呢,接下来一起看看详细的配置步骤吧~
2 配置步骤
Step1 新建连接器类型
首先我们需要根据云之家开放平台的登录文档和API调用文档来新建连接类型,其作用为建立云之家登录和调用的规则。下图展示了云之家登录鉴权的请求地址和参数。
在配置完成后,用户便可将该连接类型作为云之家的统一连接方式,然后通过第二步中新建的连接配置来登记连接信息,从而复用该连接类型。具体操作流程如下:
(1)打开“集成管理”,找到菜单“高级应用”,打开“连接类型”。选择一个以WebApiConnectionFactory为工厂类的连接类型点击复制。
输入恰当的编码和名称,“配置表单”项设置为“isc_database_link_webapi”。
注:如需定制配置表单,请在开发平台搜索“isc_database_link”,继承该表单增加新“布局”,并且打开表单连接配置的可见性都打开。
$params API调用参数,由该API集成对象参数转换脚本生成
$session 会话信息,来自会话登录脚本或会话刷新脚本的结果
$service 被调用的服务
$proxy_user 代理用户(期望在目标系统以该用户执行服务)
$protocal http协议,取值为:https 或 http
$ip 服务器IP或域名
$port 服务器端口
$user 登录用户名
$password 登录密码
$lang 登录语言,取值为:zh_CN、zh_TW、en_US
$data_center 登录帐套,对于非多账套系统该值为空
上述脚本中$表示可以访问的内置系统变量,其中蓝色字体部分表示配置表单isc_database_link_webapi上的配置信息。
(2)编辑会话登录脚本,云之家的脚本如下:
var url = $protocal + "://" + $ip + ":" + $port + "/gateway/oauth2/token/getAccessToken";
var param = {"eid": $user,"secret": $password,"timestamp": L NOW,
"scope": "resGroupSecret"};
var session = HttpInvoke(url, param).result.data;
session.$refreshTime = L(NOW) + session.expireIn * 1000 - 30000; // 设置会话刷新时间
return session;
(3)编辑会话刷新脚本,云之家的脚本如下:
var url = $protocal + "://" + $ip + ":" + $port + "/gateway/oauth2/token/refreshToken";
var param = {"eid": $user,"refreshToken": $session.refreshToken,"timestamp": L NOW,
"scope": "resGroupSecret"};
var session = HttpInvoke(url, param).result.data;
session.$refreshTime = L(NOW) + session.expireIn * 1000 - 30000; // 设置会话刷新时间
return session;
(4)编辑API调用脚本,云之家的脚本如下:
if($service contains "?"){
throw "云之家API(" + $service + ")中包含问号!";
}
if(!($service startsWith "/")){
$service = "/" + $service;
}
if(!($service startsWith "/gateway")){
$service = "/gateway" + $service;
}
// 以上为API的URL格式检查,原则上是可以取消的。
use String;
var url = $protocal + "://" + $ip + ":" + $port + $service +"?accessToken=" + $session.accessToken;
var param = "eid=" + $user + "&data="+URLEncode(FormatJson($params));
var result = ParseJson(HttpPost(url, param,"UTF-8").result);
if(!result.success){
throw (result.error+"\n错误号:"+result.errorCode);
}else{
return result.data;
}
(5)编辑服务器状态检测脚本,云之家的脚本如下:
var url = $protocal + "://" + $ip + ":" + $port + "/gateway/oauth2/token/getAccessToken";
return HttpPost(url, null, "UTF-8");
// 该脚本执行不抛出异常,则集成平台认为被调用的系统可用
(6)保存后,提交并启用。
注:
1.修改连接器类型的工作必须在开发环境进行,每次修改脚本后,必须点击刷新环境按钮才能生效。
2.以上脚本必须首先在“集成工具 - 脚本执行工具”测试通过,再替换其中的可变部分再形成前述脚本。
Step2 注册连接配置
新建连接类型后,用户可以在预置的配置表单中填写连接系统的相关信息。即使后期系统的连接信息发生变化,用户也可在前台进行修改而无需改后台代码。
具体操作流程如下:
(1)打开“集成管理”,通过菜单“连接管理–连接配置”打开连接列表,点击“新建”。输入“编码”、“名称”,并选择类型为:“云之家API”,其他输入项暂不输入,点击“保存”后退出。
(2)在连接配置列表中找到新增的“云之家测试”,点击“链接”继续编辑,补充完其他设置值后点击“保存”,再点击“测试”检查服务器是否可以连通。
Step3 创建数据源
在连接配置上再封装一层数据源,将集成资源在数据源这一层进行归集,这样做可以方便地切换数据源对应的连接配置。
比如用户集成的系统发生了改变而又想保留原本的连接信息,则将数据源对应的连接配置切到新的系统上即可。
具体操作方式:通过菜单“集成元数据–集成数据源”打开“数据源”列表,新增数据源,并选择“云之家测试”连接配置。
Step4 API登记
用户可以选择之前建立的数据源,填写API在连接系统中的调用路径就可以完成对该API的注册,最后完善API对应的输入输出参数即可。
具体操作流程如下:
(1)在“集成管理–API集成–外部系统API登记”列表界面点击“新增”,其中数据源选择刚才创建的“云之家数据源”,接口标识根据云之家开放平台的接口文档填写。
注:此处的接口标识就是API调用脚本中的$service。
点击“启用”后,即可点击“测试”查看调用结果。
3 微服务调用
在集成服务云登记了外部系统API后,用户即可在代码中通过苍穹的微服务直接调用该API。输入参数为Map类型的调用示例:
Map<String,Object> param = new HashMap<>();
param.put("eid","123456");
Object result = DispatchServiceHelper.invokeBizService(
"isc", //cloudId,此处填isc
"iscb", //appId,此处填iscb
"IscApicService", //serviceName,此处填IscApicService
"invokeExternalApi2", //methodName,此处填invokeExternalApi2
"query_person", //外部系统API的编码
param, //外部系统API的输入参数,格式为Map
null //调用者编码,不需要授权的API,此项可以不填
);
4 重点梳理
通过分析常见的接口协议,可发现就像不同语言也存在共通部分一样,如主语、谓语、宾语等,计算机沟通‘语言’也存在共通要素。
集成服务云从常见的接口协议中抽象出了以下要素:会话登录、会话刷新、API调用、服务器状态测试以及和它们相适配的工厂类kd.isc.iscb.platform.core.connector.webapi.WebApiConnectionFactory和配置相关信息的配置表单isc_database_link_webapi。
通过预置的工厂类,用户只需在脚本中维护对应连接系统的连接方式,即文章开头所说的连接类型。
当连接类型和对应的表单配置好以后,即可将该连接配置作为一次性鉴权机制。此时,用户便能够进行外部API的登记和使用,而无需再重复考虑鉴权和调用机制。
5 常见问题
问:已经在测试环境配置好了连接类型,当项目上线的时候是否还需要在正式环境再配置一遍呢?
答:已经配置好的连接类型支持导入导出,只需在正式环境导入即可。注意需要将连接类型中配置的测试环境信息替换为正式环境。
问:集成服务云有哪些已经预置的连接类型呢?后续还会持续扩充嘛?
答:目前集成服务云已经预置了各种金蝶系产品、数据库、数仓和IM系统等二十种连接类型,后续也将继续补充各种常见系统的连接类型,以满足客户开箱即用的需求。
6 相关链接
以上就是本期的内容啦~
#相关推荐#
更多精彩内容,“码”上了解!↓
API协议太多,如何高效集成?快速点进激活技能!
本文2024-09-23 00:52:47发表“云苍穹知识”栏目。
本文链接:https://wenku.my7c.com/article/kingdee-cangqiong-142330.html