# 一、 苍穹平台集成第三方平台系统用户数据
## 1.1. 需求背景
异构系统之间相互集成是一个很常见的场景，本文以用户数据的集成为案例，第三方平台系统作为源系统，苍穹平台作为目标系统，讲解如何利用集成服务云实现异构系统的数据集成。
## 1.2. 思路与方案
源系统以开源的Java Web项目ruoyi-cloud（https://gitee.com/y_project/RuoYi-Cloud）为案例进行演示。ruoyi-cloud是一个轻量级的权限管理系统，预置了用户、部门等基础模块，并具备最基本的增删改查业务功能。 在苍穹平台中使用集成服务云的WebAPI登记功能实现该需求。
## 1.3. 适用范围
本文使用的功能适用金蝶云·苍穹平台v5.0.20及以上版本。
## 1.4. 集成流程
### 1.4.1. 集成流程图
### 1.4.2 流程图说明
1. 连接类型是用于一类(种)系统和集成平台建立连接的技术实现。
2. 连接配置：启用连接类型，用于新增连接类型系统的连接配置；使用集成服务云配置集成的集成系统的连接信息，用户可以在连接配置界面选择连接类型并填写对应系统的相关信息。
3. WebAPI登记：用于快速登记外部系统的API到苍穹中，从而能够在苍穹中调用外部系统的接口；集成服务云把已有的集成对象、集成方案、消息服务、API接口等集成资源，通过服务流程编排成全新的集成服务，以支持更加复杂的业务场景。
## 1.5. 实现过程
### 1.5.1. 创建ruoyi-cloud的连接配置
#### 1.5.1.1. 新增连接类型
进入【集成服务云】->【集成管理】->【连接管理】->【连接类型】，点击【新增】按钮新增一个连接类型，如下图所示：
#### 1.5.1.2. 填写ruoyi-cloud连接类型基础信息
ruoyi-cloud是一个典型的Web系统，通过账号和密码鉴权（获取token），以访问内部资源。因此在鉴权参数中，我们添加user和password两个变量，以供后续调用登录接口获取token时使用。
此外，我们可以看到“连接器工厂类”、“保护等级”、“连接配置操作权限”等字段是默认填写好的，如果没有特殊需求，可以不改动。我们只需要填写“编码”、“名称”、“鉴权参数”即可（即下图用红色框出来的部分
#### 1.5.1.3. ruoyi-cloud连接类型的脚本配置
在连接类型页面我们还需要配置三个脚本：
**会话登录脚本**：在该脚本中我们调用Web系统的登录接口，获取会话（session）；
**会话刷新脚本**：在大多数Web系统中，会话是有失效时间的，当会话快失效的时候，系统会自动调用该脚本，以延长会话失效时间。（当然每个系统的实现可能是不一样的，以ruoyi-cloud为例，只要携带token请求/auth/refresh接口即可延长token的有效时间）；
**服务器状态测试脚本**：测试苍穹环境是否正常连通该Web系统。
##### 会话登录脚本的编写
ruoyi-cloud系统登录接口如下：
```
请求方式: post
请求路径: http://ip:1024/dev-api/auth/login
请求体:
{
"username" : "admin",
"password" : "Admin001."
}
返回示例：
{
"code":200,
"msg":null,
"data":{
"access_token":"eyJhbGciOiJIUzUxMiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX2tleSI6IjM1NmE1ZDg2LTQzN2UtNGMwOC05OTM5LTU4NmNhYmMzYmU0NCIsInVzZXJuYW1lIjoid2VuZ2VuZmVuZyJ9.NcpYEcb1Sd3gUUU71tH7xppMauQAWauLM7VAYmthCGkLI316dKepbLm6nXHsYj1jDSufj68xsLXq8Ny-9jzMOw",
"expires_in":720
}
}
```
登录脚本如下：
```js
// 登录地址
var url = $protocal + "://" + $ip + ":" + $port + "/dev-api/auth/login";
var param = {
"username": this.user,
"password": this.password
};
var response = HttpInvoke(url, param, {}, {}).result;
if (!response.code && response.code != 200) {
throw "调用登录接口失败，返回结果为：" + response;
}
var session = response.data;
// 会话刷新时间，当前时间 > session.$refreshtion时自动调用会话刷新时间脚本
// 建议在token过期前，自动调用会话刷新脚本，这里提前一个小时调用（60*60*1000）
session.$refreshTime = L(NOW) + session.expires_in*60*1000 - 60*60*1000
return session;
```
在该脚本中，我们调用Web系统的登录接口，获取会话（session）。在ruoyi-cloud中，我们可以调用/dev-api/auth/login接口获取token，接口信息如下（其中带有$符号的变量是系统的预置变量，this.xxx变量是1.5.1.2章节中定义的变量）：
$protocal: 访问协议，即http或https；
$ip: 访问的服务器，可以是域名也可以是ip地址，如：www.example.com或172.20.18.22；
$port: 服务器端口号；
this.user: 我们在1.5.1.2章节配置的鉴权参数user
this.password: 我们在1.5.1.2章节配置的鉴权参数password
refreshTime: 会话刷新时间（单位为毫秒），系统会根据refreshTime自动调用会话刷新时间脚本
return session: 将构造好的session返回给系统，系统后续会通过session里面的值访问ruoyi-cloud。
##### 会话刷新脚本的编写
当session快失效时，系统会自动调用该脚本以刷新session。在ruoyi-cloud中，通过调用/dev-api/auth/refresh延长token的有效时间，接口信息如下：
```
请求方式: post
请求路径: http://ip:1024/dev-api/auth/refresh
请求头：
{
Authorization: 当前的token
}
// 返回200代表token成功延长有效时间720分钟
返回示例：
{
"code": 200,
"msg": null,
"data": null
}
```
根据上述信息，我们可以写出如下调用脚本（其中 $session 是上面会话登录脚本中返回的变量return session）：
```js
// token刷新地址
var url = $protocal + "://" + $ip + ":" + $port + "/dev-api/auth/refresh";
header = {
Authorization: $session.access_token
};
HttpInvoke(url, {}, {}, header).result.data;// 在ruoyi-cloud系统中只要调用refresh接口即可延长token，不需要接收返回值
$session.$refreshTime = L(NOW) + 720*60*1000 - 60*60*1000; // 刷新了session后，重新设置session过期时间，距离token失效前一小时(60*60*1000)调用该脚本
return $session; // 将session变量重新返回给系统
```
##### 服务器状态测试脚本的编写
测试集成服务云是否可以正常访问该服务器，在ruoyi-cloud中，我们选择调用获取登录验证码的接口作为测试（/dev-api/code），如果成功返回code=200则代表可以连通，返回其他值则失败：
```js
var url = $protocal + "://" + $ip + ":" + $port + "/dev-api/code";
var response = HttpGet(url, {}, "UTF-8", {}, {});
var data = FastJsonParse(response.result);
if (!data.code || data.code != 200 ) {
throw "连接失败，服务器响应数据为：" + response;
}
```
#### 1.5.1.4. 创建数据源
有了连接类型，我们即可创建连接配置，如下图所示：
测试通过后，我们点击上方的“创建数据源”按钮，给ruoyi-cloud创建一个数据源，本文中将ruoyi-cloud的数据源命名为ruoyi。
### 1.5.2. ruoyi-cloud的WebAPI登记
把ruoyi-cloud获取人员列表的WebAPI登记到集成服务云，以供后续调用。
**入口**：【集成服务云】->【集成管理】->【API集成】->【WebAPI登记(推荐)】新增一个WebAPI。
在ruoyi-cloud中，获取人员列表接口示例如下：
```
请求方式: get
请求路径: http://ip:1024/dev-api/system/user/list?pageNum=&pageSize
请求头：{ Authorization: $session.access_token}
返回示例：
{
"rows":[
{
"nickName":"若依",
"phonenumber":"15888888888",
"admin":true,
"remark":"管理员",
"avatar":"",
"dept":{
"deptName":"研发部门",
"leader":"若依",
"deptId":103,
},
"status":"0"
}
]
}
```
#### 1.5.2.1. 方式一：通过curl快速登记WebAPI（推荐）
集成服务云可以将curl自动登记WebAPI，如果您的接口已在postman等WebAPI请求工具中调通，您可以在postman中将其转换成curl格式，通过集成服务云的能力将其快速登记成WebAPI，免去手动操作的步骤。详细操作可查看连接：https://vip.kingdee.com/link/s/lcDt7
如本文中获取ruoyi-cloud人员列表接口的curl为：
```curl
curl --location 'http://ip:1024/dev-api/system/user/list?pageNum=1&pageSize=10' \ --header 'Authorization: eyJhbGciOiJIUzUxMiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX2tleSI6IjYwMWRmOWY5LWYxZTgtNDBlOS04ZDI0LTgxMGU4YTc4NGUyYyIsInVzZXJuYW1lIjoid2VuZ2VuZmVuZyJ9.f-0bANPW-iteR8mCflPeOR8g4LJgOXqa85L1Ep4D16sjV89T1fcjC8y-ZFtrsTLUO3YoG0KvA91OcNstWhm7rw'
```
curl中的Header、QueryParam等参数都是具体的参数，在WebAPI登记中我们要改为动态获取，此外数据源需要手动选择1.5.2章节创建数据源中创建的ruoyi数据源，如下图所示：
#### 1.5.2.2. 方式二：手动登记WebAPI
除了用curl快速登记WebAPI，我们还可以手动登记。根据接口示例，我们可以在WebAPI登记表单中填写如下信息：
配置好后可以点击工具栏中的【测试】按钮，测试WebAPI是否配置正确。
### 1.5.3. 创建苍穹连接配置并同步bos_user集成对象
uoyi-cloud的连接配置我们已经完成了，接下来我们要做苍穹平台的连接配置。
苍穹平台的连接类型分两种，一种是【金蝶云·苍穹（远端）】，一种是【当前账套】。“账套”即数据中心的意思，当前账套代表当前数据中心。如果您目前正在使用的集成服务云所在的苍穹环境，与需要进行数据集成的苍穹环境是同一个，选择当前账套即可。选择当前账套的话不需要进行任何配置即可访问。由于绝大多数需求是第一种情况，所以本文选择当前账套。创建好后点击“创建数据源按钮”，本文将当前账套的数据源命名为ierp。
创建好苍穹连接配置后，我们要同步苍穹的集成对象。
集成服务云在处理苍穹的数据时是以实体为基础的（实体即单据、基础资料等），我们现在要做的是人员信息集成，苍穹人员实体标识是bos_user，我们把该实体的元数据同步到集成服务云。
**入口**：【集成服务云】->【集成管理】->【集成元数据】->【集成对象】。点击新增，并填写bos_user的编码、全名、元数据名称，然后点击“同步”按钮，即可同步bos_user的所有信息。
也可以直接同步所有元数据，以便后续操作。
### 1.5.4. 使用服务编排进行数据同步
### 1.5.4.1. 创建服务编排并填写基本信息
**入口**：【集成服务云】->【集成管理】->【服务编排】->【服务流程】。
新增一个服务流程，填写基本信息，必要的基本信息包括流程变量和依赖资源。
**流程变量**
流程变量和代码中的变量的概念是相同的。我们调用ruoyi-cloud接口获取人员后，需要一个变量接收结果，这里定义为var_ruoyi_user，因为返回结果值为json，所以变量类型设置为简单值即可（简单值用于接收list和map，可兼容json格式）。var_ruoyi_user的值示例如下：
```
{ "msg":"查询成功", "total":2, "code":200, "rows":[ { "nickName":"若依", "sex":"1", "roles":[], "deptId":103, "phonenumber":"15888888888", "admin":true, "remark":"管理员", "avatar":"", "dept":{ "deptName":"研发部门", "leader":"若依", "deptId":103, }, "userName":"wengenfeng", "delFlag":"0", "createBy":"admin", "createTime":"2023-03-03 13:18:09", "loginIp":"127.0.0.1", "email":"ry@163.com", "status":"0" }, { // 略，同上 } ] }
```
获取到ruoyi-cloud人员后，我们需要var_ruoyi_user里的信息转换成苍穹人员，因此也需要一个var_bos_user接收转换结果，最后还用根据var_bos_user里的信息调用保存接口。由于bos_user是集成对象，所以var_bos_user的类型设置为集成对象即可，并且由于是多个值批量保存，因此可以设置为多值。
**依赖资源**
依赖资源即该服务流程要依赖的外部资源，在这个流程中我们需要依赖bos_user集成对象和ruoyi-cloud的WebAPI，如上图所示引用即可。
**设计流程图**
配置好基本信息后，点击工具栏中的【流程图】，进入流程图设计界面。
流程设计为我们提供了丰富且强大的功能，不过本文的重点在于介绍数据同步的流程，如果需要详细了解这些功能可参考集成服务云官方文档：
https://vip.kingdee.com/knowledge/specialDetail/184698074009519872?category=225569254118893056&id=133891644754897664&productLineId=29
在本文的案例中，需要先调用ruoyi-cloud的WebAPI获取人员信息（用脚本节点实现），然后将人员信息映射成苍穹人员的数据对象（用脚本节点实现），最后对苍穹人员的数据对象进行保存（用数据加载节点实现），因此设计出以下流：
1) 脚本节点1：调用WebAPI获取ruoyi-cloud人员信息
双击点开脚本节点，输入如下代码，解释请看注释。
注意：大部分系统中获取人员信息接口都为分页查询，需要根据自身需要循环调用接口获取所有人员信息，在ruoyi-cloud也是如此。本文中使用的ruoyi-cloud只有两条数据，为了便于演示，故此省略了循环调用的代码，下面设置的pageNum=1和pageS
