# 一、 苍穹平台集成第三方平台系统用户数据 ## 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和pageSize=10就足以获取所有数据了。 ```js var queryString = { pageNum: 1, pageSize: 10 }; // 调用ruoyi_webapi（1.5.4.1章节设置的依赖资源），获取返回结果 // ruoyi_webapi接收三个参数，第一个是请求体，第二个是请求头，第三个是查询参数（即 ?pageNum=1&pageSize=10） var_ruoyi_user = ruoyi_webapi({},{}, queryString); // 由于返回的json是字符串，将json字符串转换成map结果 var_ruoyi_user = String.ParseJson(var_ruoyi_user); ``` 2) 脚本节点2：将ruoyi的人员变量映射到苍穹人员变量 将4.2.1获取到的数据var_ruoyi_user逐个字段映射到var_bos_user中，解释请看注释。 ```js var_bos_user = []; // ruoyi人员列表（ruoyi人员的数据结构请看1.5.4.1章节） var ruoyi_user_list = var_ruoyi_user.rows; // 遍历ruoyi_user_list，逐个映射到var_bos_user数组中 for(var user : ruoyi_user_list){ // 定义一个临时变量用来接收映射结果 temp_obj = {}; //字段映射 // 工号为必填字段，ruoyi人员没有工号，用手机号代替 temp_obj.number = user.phonenumber; // 名称为必填字段，映射若依中的nickName temp_obj.name = user.nickName; // 手机字段，映射若依中的phonenumber temp_obj.phone = user.phonenumber; // 数据状态，C代表可用 temp_obj.status = 'C'; // 创建人，可指定创建人的id，1代表administrator temp_obj.creator = 1; // 修改人，同上 temp_obj.modifier = 1; // 创建时间，设置为现在 temp_obj.creatime = Date.now(); // 修改时间，同上 temp_obj.modifytime; // 是否禁用，0代表false 1代表true temp_obj.isforbidden = 0; // 使用状态，同上 temp_obj.enable = 1; // 是否锁定该人员，同上 temp_obj.islocked = 0; // 是否激活该人员，同上 temp_obj.isactived = 1; // 是否已注册，同上 temp_obj.isregisted = 1; // 邮箱字段，映射若依中的email temp_obj.email = user.email; // username字段，映射若依中的userName temp_obj.username = user.userName; // 用户类型字段，1代表职员，更多选择可查看该基础资料 temp_obj.userstypes = 1; // 部门分录，必填，这里给所有同步过来的人员设置一个固定的部门，可根据自身需要写代码进行动态映射 temp_obj.entryentity = [ { seq: 1, // 分录的序列号，用于标识每条数据的顺序 dpt: 100000, // 这个人员表关联是部门表的外键，100000代表最顶级组织的主键id isinchangrge: 0， //是否部门负责人，0代表false，1代表true ispartjob:0, //是否兼职，0代表false，1代表true position:'测试工程师' // 职位，字符串类型 } ]; // 将映射结果放入var_bos_user var_bos_user += temp_obj; } ``` 3) 数据加载节点：保存人员 我们要操作的集成对象为bos_user，所以目标集成对象选择r_bos_user（第1.5.4.1章节引入的依赖资源），要操作的数据是4.2.2脚本节点中构造的变量var_bos_user。 系统会根据“候选键”判断每一条数据应该插入(insert)还是更新(update)，单据头和单据体都需要设置“候选键”，这里单据头设置为工号，单据体（部门分录）设置为分录行号。  然后选择数据的操作方法，这里选择save操作（即insert或update）。   ## 1.6 效果图 经过上述操作，我们已经完成了所有配置，最后在服务流程列表点击“立即执行”即可执行我们第1.5.4章节配置的流程节点。  回到系统服务云的人员列表，可以看到ruoyi-cloud中的两条人员数据已经同步过来了。  修改初始密码后，成功登录系统。  # 二、第三方平台系统集成苍穹平台用户数据 ## 2.1. 需求背景 异构系统之间相互集成是一个很常见的场景，本文以用户数据的集成为案例，第三方平台系统作为源系统，苍穹平台作为目标系统，讲解如何利用集成服务云实现异构系统的数据集成。 ## 2.2. 思路与方案 通过苍穹开放平台openAPI2.0的能力，将苍穹人员查询接口（WebAPI）开放，供第三方系统调用。 ## 2.3. 适用范围 本文使用的功能适用金蝶云·苍穹平台v5.0及以上版本。 ## 2.4. 集成流程 ### 2.4.1 集成流程图  ### 2.4.2 流程图说明 1. 操作API是将金蝶云苍穹业务对象如单据、基础资料的操作（查询，保存，提交等），通过零代码配置的模式，一键发布成为OpenAPI，系统自动生成服务接口及服务契约。 2. 安全策略：外部系统在调用金蝶云苍穹OpenAPI时，金蝶云苍穹会对每个API请求进行身份认证的校验，判断其请求的合法性，最后响应该API请求。截至苍穹v5.0.20版本，开放平台提供了多种安全认证方式，安全性：签名认证 > 摘要认证 > JWT > AccessToken认证 > 基本认证。便捷性：基本认证 >JWT > AccessToken认证 > 摘要认证 > 签名认证。 ## 2.5. 进入【开放平台】->【API管理】->【API开发】选择左树中【系统服务云】节点，新增一个零代码配置的操作API，如下图所示：  ### 2.5.1. 配置操作API **请求方式**：GET； **业务对象**：选择苍穹人员实体（bos_user）； **请求参数**：即外部系统调用该API时传入的参数，GET请求可以配置请求头参数和query参数，这里可以根据自己的业务需要进行配置，由于本案例是全量查询，所以不进行配置； **参数控制**：即根据常量或请求参数的值，配置过滤条件或排序条件。比如只查询可用状态的人员，可以配置isforbidden=0，或者根据请求参数动态过滤；由于本案例是全量查询，所以不进行配置； **返回参数**：即调用该WebAPI时返回的人员字段，理论上可以返回bos_user实体里所拥有的字段，为了方便展示，本文仅配置四个字段：id、number（工号）、fullpinyin（真实姓名的拼音）、phone（手机号）。  ### 2.5.2. 测试API 保存操作API后，点击按钮栏中的“测试API”即可打开测试页面，如下图所示：  可以发现系统已经自动帮我们生成了url，并且拼接上了pageSize和pageNo两个分页查询参数，要注意零代码配置的查询WebAPI必须有分页参数，否则会调用失败。 点击“Send”即可调用该WebAPI进行调试，如下图所示：  ### 2.5.3. 配置安全策略 截至目前，获取人员的WebAPI已经配置好了，接下来我们需要配置一个安全策略，对外部系统进行鉴权，以确保数据安全。 进入【开放平台】->【安全策略】->【第三方应用】，新增一个安全策略，如下图所示：  截至苍穹v5.0.11版本，开放平台提供了5种安全认证策略，详细可查看文档： https://vip.kingdee.com/knowledge/specialDetail/226337046514476288?category=239331354741842688&id=218694224487485696&productLineId=29 本文使用AccessToken认证作为演示（请务必注意，AccessToken认证密钥只会在新增时展示，若丢失则无法找回，请妥善保管密钥），读者可根据自身业务需要自行选择，如下图所示：  然后给该第三方应用配置API授权，将2.5.1配置的WebAPI授权给该第三方应用，如下图所示：  第三方应用还有许多有用的配置项，可查看官网文档进行了解：https://vip.kingdee.com/knowledge/specialDetail/226337046514476288?category=226337544983020032&id=225286231527892224&productLineId=29 ## 2.6. 用postman模拟外部系统调用获取数据 要在外部系统调用人员WebAPI，需要遵循以下步骤（2.5章节中配置了AccessToken认证，所以下述步骤为AccessToken的步骤，其他认证方式请查看3.5章节中提供的文档） ### 2.6.1. 获取app_token 调用苍穹服务器，获取app_token，路径为：/api/getAppToken.do 如：http://127.0.0.1:8888/test/api/getAppToken.do 请求参数和返回数据如下图所示：  ### 2.6.2. 获取access_token 获取到app_token后，调用接口获取access_token，接口路径为：/api/login.do 如http://127.0.0.1:8888/test/api/login.do 请求参数和返回数据如下图所示：  ### 2.6.3. 调用人员接口 在2.5.1中配置的人员WebAPI请求地址为：/v2/kdec/base/bos_user/bos_user 如下图所示：  完整的请求地址需要拼接上苍穹服务器域名、端口、urlContext、/kapi前缀，如： http://127.0.0.1:8888/test/kapi/v2/kdec/base/bos_user/bos_user postman中调用结果如下：  拿到数据后，我们即可按业务逻辑将数据保存到第三方平台系统中。