目录

 

学习目标

 
  1. 掌握在 HAP 中使用「发送 API 请求」节点调用接口的基本配置方法。
  2. 能够根据应用 API 接口文档，熟练实现通过工作流自动拉取应用角色列表，自动为角色增减人员等操作。
  3. 能够组合运用 JSON 解析、子流程、PBP 等节点，灵活处理接口返回的多层数组结构数据。
 
 

场景案例

 
为了实现更加精细化的权限管理，活动管理应用将工作人员细分为邀约组、签到组、后勤、财务等多个角色，不同角色对应不同的应用权限。在原有做法中，MEGA 公司由管理员手动将人员加入或移出相应角色。随着活动数量增加、人员调整频率提高，这种方式不仅费时费力、容易出错，而且缺乏完整的操作留痕。
 
因此，他们希望应用可以支持：
  1. 一键拉取当前所有角色及各角色下的人员信息，并自动写入到表单记录中。
  2. 未来通过填写表单记录的方式，自动完成角色成员的新增、移除，并同步保留人员角色变更的操作记录，便于追溯与审计。
 
 

操作指南

 

需求一：拉取当前角色和用户

 

需求分析：

 
要实现拉取当前应用后台的角色和角色下成员，我们需要调用应用中的「获取角色列表」 API 接口。
 

接口文档分析

 
首先，点击应用名称旁的下拉按钮，打开应用的API开发文档，查看「获取角色列表」接口要求，重点关注两点：
 
 
 
 
 
  1. 需要传入哪些参数
根据API接口文档显示，需要传入应用鉴权参数（AppKey、Sign）
 
 
 
 
  1. 接口返回哪些数据
 
根据接口文档显示，接口返回的是一个两层数组结构：
  • 第一层是角色数组（包含多个角色，每个角色包含角色 ID、角色名称等信息）
  • 每个角色对象中还嵌套一层角色下人员数组（包含用户 ID、姓名等信息）
 
 
 
 

实现思路（流程设计）

 
结合接口返回的数据结构，整体实现路径可以拆解为两层处理：
 
1. 第一层：批量处理角色（子流程）
  • 工作流中先通过「发送 API 请求」节点，获取到包含 多个角色 的对象数组。
  • 然后使用 「子流程」，对每一个角色对象单独处理：
    • 写入或更新「角色表」中的角色记录。
    • 在子流程内部，再继续处理该角色下的人员数组。
 
2. 第二层：批量处理角色下的人员（PBP）
 
  • 在子流程中，使用「JSON解析」节点，将用户数组（accounts）和数组中的账号ID（accountId）、用户名（fullname）等参数取出，再使用「获取多条数据」节点获取JSON解析后的人员数组。
  • 使用封装业务流程 PBP，对人员数组中的每一个人员逐条写入到「人员表」：
    • 新建或更新人员记录
    • 同时将人员与当前角色做关联（例如写入角色 ID 或角色关联字段）
 
通过「子流程 +JSON解析+ PBP」的组合，我们就可以分层、清晰地处理这个“角色数组 + 角色下人员数组”的复杂返回结构，实现角色与人员的自动同步和关联。
 
 

应用配置

 

角色表单配置：

 
  1. 设置【角色表】，用于存储从 API 接口同步过来的角色信息，其中包括【角色名称】、【角色 ID】字段。
  2. 根据实际需求，可新增【是否启用】字段，用于标识当前角色是否有效。当最新同步的角色列表中不再包含角色表中的某个历史角色时，可视为该角色已被删除，需要在系统中自动将其【是否启用】状态更新为“关闭”。
 
 
 
 

用户表单配置：

 
设置【用户表】，用于存储从 API 接口同步过来的用户信息，其中包括【账号 ID】、成员字段、以及关联的多个角色。
 
 
 
 

刷新角色——封装业务流程

 
新建一个业务流程，命名为「刷新角色」，配置封装业务流程的输入参数，这个封装业务流程是为了方便在自定义页面随时调用，所以输入参数可以任意设置，实际调用时也不需要传入参数。
 
 
 
 
查询用户表并批量更新：
 
添加【获取多条数据-查询并批量更新】节点，先将现有用户表的关联角色清空，为刷新用户所属角色信息做准备。
 
 
 
 
添加【发送API请求】节点：
 
添加发送API请求节点，选择发送自定义请求，目的是获取角色列表API接口获取应用的最新用户角色信息。
 
 
 
 
对【发送自定义请求】动作节点进行配置：
 
  1. API URL（请求地址）配置：
根据应用的API开发文档，选择接口调用方式GET，并填入API请求地址。
 
 
 
 
  1. Header配置
同时，请求头参数Header Parameter需要传入应用的授权参数AppKey和Sign，这个可以在API 说明的应用授权标签页找到。
 
 
 
 
另外，后续在调用其他应用API时，会多次使用到授权参数AppKey和Sign，为了方便管理和后续直接使用，可以将其设置为全局变量，在接口调用时，直接填入全局变量即可。
 
 
 
 
配置好后，点击【测试API】进行测试
 
 
 
 
获取角色数组
 
选择【获取多条数据-获取数组对象】节点，获取上一个动作节点【发送API请求】返回的数组
 
 
 
 
查询并批量更新角色表
 
查询不在最新角色中的历史角色表单记录，更新其「是否启用」开关项为删除（即不启用）。
 
 
 
 

刷新角色——子流程【角色写入列表，无则新增】

 
添加子流程节点，将【发送API请求】节点获取到的角色数组作为数据对象，配置子流程，执行方式为逐条执行。
 
 
 
 
子流程整体动作节点配置如下：
  1. 根据返回的角色ID，查询角色表中是否已存在此角色，未查询到数据则说明此角色为新创建的角色，需要新增到角色表。
  2. 使用JSON解析节点将子流程中的人员数组（accounts）和人员数组中的用户ID（accountId）解析出来。
  3. 当角色下人员不为空时，使用「获取多条数据-获取数组对象」节点，从JSON解析节点获取人员数组。
  4. 调用封装业务流程PBP【写入人员表】，将人员数组中的多个人员信息，写入人员表
 
 
 
 
选择【发送API请求】的获取角色数组后，传入子流程的数组对象元素如下，其中：
  • accounts是角色下的人员数组。
  • id是角色id。
 
 
 
 
查询角色表
 
将筛选条件设置为角色ID，查询角色表中是否已有的与子流程id相同的数据记录
 
 
 
若未查询到，则新增记录
 
 
 
JSON解析
 
配置JSON解析节点，对象为子流程的数据对象【发送API请求】，点击「查看JSON解析结果」，再点击「生成参数」，填入输出参数中。
 
 
 
 
 
 
设置分支，查询accounts情况
 
对于accounts不为空的分支，获取上个动作节点【JSON解析】后的数组对象
进入封装业务流程--【写入人员表】
 
配置封装业务流程
执行的数据对象为上一个【获取数组对象】节点中的JSON解析数组结果
执行次数为多次，方式为并行，并配置输入参数：
  • 必须的参数：用户ID（accountId）、角色ID
  • 可选参数：用户姓名（fullname）等，（只要用户在当前应用的组织中，即使不传入用户姓名，也可以通过用户ID从组织中获取到用户的账号填入用户表的成员字段）
 
 
 
 

刷新角色——PBP（写入人员表）

 
整体流程配置如下：
  • 根据角色ID从角色表查询对应的角色记录。
  • 根据用户ID从组织中查询对应的账号信息。
  • 根据用户ID查询用户表是否有对应记录，如无则新增用户记录。
  • 最后更新用户表中的角色关联字段，为该用户新增当前角色记录
 
 
 
 
查询角色表记录
 
根据封装业务流程输入参数角色ID，从角色表中查询对应的角色记录。
 
 
 
根据用户ID从组织中查询人员信息
 
使用「获取单条人员」节点，根据封装业务流程输入参数用户ID，从组织中查询对应的人员信息，用于后续新增人员表记录时，填入成员字段。
 
 
 
查询用户表记录，无则新增
 
根据用户ID查询用户表是否有此用户，如未查询到则新增用户，填入成员和账号ID。
 
 
 
 
更新用户表关联的角色增加当前角色
 
使用更新记录节点，将用户表关联的角色，增加当前获取的角色记录。
 
 
 
 

发布流程

 
所有配置完成后，分别发布「刷新角色」、「角色写入列表」、「写入人员表」这三层工作流。
 
 

自定义页面按钮调用「刷新角色」PBP

 
在「刷新角色」这个自定义页面中，添加一个「拉取应用角色」的按钮，并设置点击按钮后调用「刷新角色」这个封装业务流程。
 
 
 
 

实现效果

 
在「刷新角色」自定义页面，点击「拉取应用角色」按钮后，工作流将会自动拉取应用的角色和角色下人员，实现：
 
  1. 将角色数据写入到「角色表」
 
 
 
 
  1. 将人员数据写入到「人员表」，同时在人员记录中写入其所属角色的关联信息
 
 
 
 

需求二：角色下人员增减的自动化

 

需求分析：

 
  1. 当要把人员加入某个角色时，需要调用添加角色成员接口；当要将人员移出某个角色时，则需要调用移除角色成员接口。
  2. 同时，为了保证前后台数据一致性，在调用接口将某个成员添加或移除某个应用角色后，前台的角色表和用户表也需要做出相应的自动变更。
 
 

接口文档分析

 
在这个需求中，我们只关心“人员增减”的执行结果，并不需要处理接口返回的数据，因此重点是弄清楚 接口需要传入哪些参数。核心参数包括：
  1. 应用鉴权参数：AppKey、Sign
  2. 业务参数：角色ID、用户ID合集（可一次传多个用户）
 
 
 
 

实现思路：

 
  1. 建立一张「角色成员变更表」，用于登记角色下人员的加入和退出操作。
  • 出于交互友好性，如果是“退出角色”，可以在变更表中通过选择现有用户，再选择其所属角色，来发起“退出”操作。
 
  1. 当变更记录生效后，根据变更类型（加入 / 退出），在工作流中分别：
  • 调用「添加角色成员」或「移除角色成员」接口，完成后台角色成员的调整；
  • 同时自动更新前台的「用户表」中用户所属角色字段，增加或移除对应角色，确保数据一致，并形成清晰的变更留痕。
 

应用搭建：

 

角色变更表单配置

 
需要实现的填写效果
  1. 当申请类型为加入角色时，直接选择成员和变更角色，变更角色可以选择当前应用下的任意角色。
 
 
  1. 当申请类型为退出角色时，先从用户表中选择要退出的用户，随后“变更角色”的可选范围将被限定为该用户当前已归属的角色之一。
 
 
配置业务规则
设置业务规则：当「申请类型」是退出角色时，显示用户（关联记录）和当前角色（关联记录）
 
 
 
设置默认值
设置「当前角色」字段默认值，根据当前用户所属角色自动带出。
 
 
设置关联记录选择范围
设置变更角色关联记录的选择范围，设置条件为【记录ID=当前角色】，设置“当条件使用的动态值为空时，忽略此条件（当全部忽略时，返回所有记录）”。
 
通过这个配置实现：当用户退出角色时，只能从当前角色中选择；当用户加入角色时，可以选择所有角色。
 
 
 

设置「生效」按钮的工作流

 
 

整体流程逻辑

 
「生效」按钮工作流的整体逻辑如下：
  1. 获取变更单关联的变更角色，即需要加入/退出的角色。
  2. 从变更单的成员字段获取人员信息。
  3. 判断变更单申请类型
    1. 如果申请类型为加入角色
      1. 调用「添加角色人员」接口
      2. 更新角色变更单的状态为已生效
      3. 查询用户表是否存在变更的成员，如不存在则新增用户记录
      4. 将用户的所属角色这个关联字段，加上当前变更角色。
    2. 如果申请类型为退出角色
      1. 调用「移除角色人员」接口。
      2. 更新角色变更单的状态为已生效。
      3. 获取变更单关联的用户表（退出角色时，用户关联字段需必填）。
      4. 将用户的所属角色这个关联字段，减去当前变更角色。
 
 
 
 

获取变更单关联的角色

 
 

从变更单的成员字段获取人员信息

通过「获取单条人员」节点，从成员字段获取人员信息，可以取到这个人员的用户ID信息，在后续新增用户表记录时使用。
 
 
 
 

加入角色的逻辑

 
调用「添加角色成员」接口
当申请类型=加入角色时，通过「发送API请求」节点，调用「添加角色成员」API接口，传入接口对应参数
 
 
 
 
更新变更单的生效状态=已生效
 
 
 
 
查询变更用户，无则新增
通过成员字段查询用户表是否存在当前变更的用户，查询无数据则新增一条用户记录，填入成员和用户ID。
 
 
 
 
更新用户表关联角色 增加 当前变更用户
 
 
 
 

退出角色的逻辑

 
调用「移除角色成员」接口
当申请类型=退出角色时，通过「发送API请求」节点，调用「移除角色成员」API接口，传入接口对应参数。
 
 
 
 
更新变更单的生效状态=已生效
 
 
 
 
查询变更单关联的用户
当申请类型为退出角色时，变更单的用户关联记录是必填的，所以可以直接通过获取关联记录的方式，获取到变更人员记录。
 
 
 
 
更新用户表关联角色增加当前变更用户
 
 
 
 

实现效果

如图，此成员后台加入了后勤组、管理员、运营者三种角色。
 
 
 
 
创建变更单，选择退出后勤组角色。
 
 
 
 
点击「生效」按钮后，将自动从后台后勤组角色中移除该成员，同时在用户表中清除此用户与后勤组角色的关联关系。
 
 

动手练习

 
现在，请点击页面上方“打开教学应用”按钮，进入本课程专属的实操应用，开始动手操作吧！