如同不同国家和地区之间存在不同的语言一样，在计算机的世界里也有不同的接口协议：基于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。