魔笔平台提供了强大的集成流编排功能,允许用户通过简单的配置,快速构建一个可以执行多种复杂操作的集成流。本文将指导您如何使用集成流功能。
什么是集成流
集成流可以将多个集成操作有序的组合起来,从而处理高复杂度的逻辑。魔笔提供了丰富的集成流节点,包括自定义代码、大模型、资源连接、逻辑判断等。用户可以根据自己的需要组合编排节点,快速搭建一个集成流。
集成流设计器界面说明
集成流设计器界面说明:
标注 | 功能名称 | 使用说明 |
1 | 魔笔LOGO及集成流名称 | 点击LOGO可返回集成流列表 |
2 | 版本历史记录 | 可发布、回退所提交版本 |
3 | 左侧功能面板 | 集成流功能选项 |
4 | 错误检查 | 提示错误及警告数,点击出现错误信息面板 |
5 | 集成流画布工作区 | 编排集成流的工作区 |
7 | 模拟测试面板 | 对集成节点和流进行测试 |
8 | 提交与发布 | 提交和发布集成流 |
集成流节点
节点类型
触发器节点
触发器节点是流的起始节点,承载流的全局配置,包括参数,超时,策略等。触发节点属于有值节点,可通过trigger.data
来引用用户使用集成流时配置的实际参数。
有值节点是指某类在初始后或者执行后携带有数据,能以{节点id.data}
的形式访问其数据的节点。触发器节点、集成操作节点以及变量节点都属于有值节点。
配置项说明:
名称 | 说明 | 类型 |
必填参数 | 定义调用集成流时必须设置的参数 | |
可选参数 | 定义调用集成流时必须设置的参数 | |
超时 | 集成流运行超过设置时间则返回超时错误 | 数字,单位:毫秒数 |
集成操作节点
集成操作节点有多重操作类型,包括脚本、SQL、百炼应用等。
脚本
支持使用 JavaScript 编写逻辑脚本。脚本将在后台被封装为一个异步函数并被执行调用。输入的脚本内容将作为函数的函数体。函数返回的结果将作为节点对象data
属性的值。结构大致如下:
async () => {
// your code here
}
配置项说明:
名称 | 说明 | 类型 |
代码 | 代码将作为异步函数的函数体 | JavaScript |
其他类型
集成节点属于有值节点,可通过{节点id.data}
引用数据。
if 节点
if 节点的作用类似编程语言中if...else
,如下所示:
if (condition) {
// statement 1
} else {
// statement 2
}
条件节点包括以下三个部分:
条件【必须】。JavaScript 表达式,值为布尔类型。
if 节点集合【必须】。集合中可以包含任意节点。
else 节点集合【非必须】。集合中可以包含任意节点。
名称 | 说明 | 类型 |
条件 | 判断的条件,需要返回 | JavaScript 表达式 |
if 节点不属于有值节点,无法被引用。
while 节点
while 节点的作用类似编程语言中while
,如下所示:
while (condition) {
// statement
}
循环节点包括以下两个部分:
条件【必须】。JavaScript 表达式,值为布尔类型。
节点集合【必须】。集合中可以包含任意节点。
while节点不属于有值节点,无法被引用。
try 节点
try 节点的作用类似编程语言中try...catch
,如下所示:
try {
// tryStatements
} catch (exception) {
// catchStatements
} finally {
// finallyStatements
}
try节点包括以下三个部分:
try 节点集合【必须】。
catch 节点集合【非必须】。catch 集合下的节点可以通过
error
关键字获取捕获到的异常错误,error 对象包含code
和message
属性。finally 节点集合【非必须】。
try 节点不属于有值节点,无法被引用。
throw 节点
throw 节点作用类似编程语言中的throw
,如下所示:
throw expression;
通常定义在 try 节点集合内,捕获的错误在 catch 节点集合中进行处理。
配置项说明:
名称 | 说明 | 类型 |
异常编码 | 异常编码 | 字符串 |
异常信息 | 异常信息 | JavaScript 表达式 |
throw 节点不属于有值节点,无法被引用。
变量节点
变量节点的作用类似 JavaScript 中的let
,声明用于声明可重新赋值的块级节点作用域局部变量,并且可以选择将其初始化为一个值。
集成流有两种赋值方式:
显式赋值。使用赋值节点进行赋值。
隐式赋值。在脚本或者表达式中设置其节点对象的
data
属性的值,例如:variableId.data = xxx
。
名称 | 说明 | 类型 |
默认值 | 变量默认值 | JavaScript表达式 |
变量节点属于有值节点,可通过{节点id.data}
引用数据。
赋值节点
赋值节点的作用是对变量节点进行显式赋值。
赋值节点包含两部分:
赋值对象:所要赋值的变量。
值:JavaScript 表达式。
名称 | 说明 | 类型 |
默认值 | 变量默认值 | JavaScript 表达式 |
赋值节点不属于有值节点,无法被引用。
返回节点
返回节点的作用类似编程语言中return
。返回节点返回的值将作为整个集成流的执行结果值。
名称 | 说明 | 类型 |
值 | 返回值 | JavaScript 表达式 |
节点作用域
在代码编写过程中,我们经常会考虑作用域的影响:
作用域是当前的执行上下文,在其中的值和表达式“可见”(可被访问)。如果一个变量或表达式不在当前的作用域中,那么它是不可用的。作用域也可以堆叠成层次结构,子作用域可以访问父作用域,反过来则不行。
在集成流的编排中也有相似的概念。节点作用域的概念与编程中变量作用域的概念非常相似,在集成流中,作用域决定了节点对象能否被访问或引用。
节点作用域分以下两种:
全局作用域:与触发器节点同一级的节点所在的作用域;
块级作用域:集合类节点创建出的内部作用域,外部节点无法访问内部节点的节点对象。集合类节点包括 if 节点、while 节点、try 节点。
关于块级作用域,这里使用 if 节点举例:if 节点集合下的节点无法访问 else 节点集合下的节点,反之亦然,因为 if 和 else 各自创建出了独立的内部作用域。
构建集成流
新建集成流
首先需要创建一个集成流。在控制台中依次选择资源 > 集成流,选择创建集成流。
编排集成流
集成流的编排可能包含以下动作:
创建一个节点。
更改节点的标识符 id(仅为更具可读性,非必须)。
设置节点的配置项。
观察错误检查面板是否存在错误。
克隆节点进行小范围修改。
删除错建错配的节点。
节点调试(集成节点)。
调整节点的关系(依据实际需要)。
您可以通过以下动作操作集成流节点:
添加节点 :当鼠标放置在节点间的边上时,会出现添加节点的按钮。点击并选择节点类型即可添加一个节点。节点生成之后带有一个默认的节点 id,它是节点的唯一标识,也是节点作用域下的节点变量。节点 id允许被修改,像定义变量名一样,赋予一个可读的名称。如需修改节点的标识符 id,可选中节点,点击 id一栏进行修改。id 作为节点的唯一标识符,不可重复。
删除节点:选中节点,在配置面板下方选择删除节点。或者,点击节点卡片上更多按钮,选择“删除节点”。
克隆节点:点击节点卡片上更多按钮,选择“克隆节点”。
移动节点:可通过拖拽将节点调整到预想的位置。位置改变也意味着节点关系发生了变化。例如 if 节点集合下的节点被拖到 else 节点集合下,它将在 else 逻辑被触发时执行。
在完成节点添加操作后,您还需要为每个节点配置必要的属性信息。选中节点后,编辑器右侧的配置面板中会出现该节点的配置项。
调试集成流
当配置完一个集成节点,或者整个流已经编排完成,验证它们是否能按预期工作是必不可少的一步。魔笔集成流编辑器也提供了调试功能。
触发器配置面板中的调试器可以用来模拟整个流的运行,集成节点对应的配置面板中的调试器可以用来测试当前的集成操作。
上图为集成流中的调试面板,它主要由以下几个部分组成:
模拟参数
模拟参数中显示的是集成节点(action 节点)脚本或者配置中依赖的节点数据。
模拟参数以 JavaScript 对象的形式显示。对象的属性是在配置项中引用到的节点 id,值是节点对象值,一般默认为空值null
。
下面三种情况例外:
在触发器面板设置的trigger模拟数据在全局可用。
引用的节点是变量节点。魔笔将从该变量节点的配置中读取值(变量表达式中无外部节点引用,可通过eval直接得出结果)。
若引用的节点是集成节点并且已有测试结果,则测试结果将作为默认值。
用户可对模拟参数进行添加、编辑、删除等操作。用户可根据自己的需要设置值。它将作为测试节点使用的参数。
以下几点需要注意:
保持节点对象结构完整,data属性不可删除。
如需在输入框中输入对象,须使用
()
包裹内容,例如:({key:val})
。
测试结果
图中所示为测试的状态指示,不同颜色代表不同的状态,它有以下三种状态:
灰色:待测试;
绿色:测试成功,执行成功并得到结果;
红色:测试失败,返回结果成功标识符为false,可根据错误提示,对配置或代码进行调整。
内容区将显示测试的结果,未再次进行测试或者模拟参数没有发生变更,测试结果将保持显示。
测试/运行
根据配置信息和模拟参数,运行流或者执行集成操作。
提交与发布
提交
提交后的集成流,将会产生提交记录,可在左侧功能面板 > 历史记录中查看。可对记录进行发布和回滚操作。
发布
默认发布最新一次的提交记录。如果当前工作区内容还未进行提交,选择环境并点击确定发布后会创建提交并发布此次提交。用户也可选择其他记录进行发布。发布后的集成流可在应用设计器中使用。
集成流可以发布至开发环境或生产环境。如果您需要在应用编辑器内使用集成流集成操作,请先将目标集成流发布至开发环境。
为确保集成流在生产环境也能正确使用,发布应用前请确保相关集成流已发布至生产环境。
错误检查
和页面编辑器一样,集成流编辑器也提供了相应的错误检查功能,方便用户及时的发现问题。
集成流的错误检查主要包含以下内容:
节点 id引用有效性检查;
JavaScript 脚本及表达式错误检查;
节点配置必填项检查;
节点引用的集成资源有效性检查。
标注 | 功能名称 | 使用说明 |
1 | 错误搜索框 | 可搜索流中存在的错误 |
2 | 错误数及警告数 | 红色为错误,橙色为警告 |
3 | 错误信息 | 错误信息 |
4 | 错误路径 | 产生错误的节点位置,点击路径可选中该节点,并显示配置信息 |
使用集成流
通用配置
参数:根据集成流内定义设置参数作为实际入参。
触发方式:选择手动触发或自动运行。手动触发仅在触发集成操作事件或通过 API 调用
action.trigger
方法时执行。自动运行则在初次加载和依赖项变更时自动执行,例如当{{input1.value}}
改变时。描述:为集成流操作提供详细描述。
回调配置
数据转化:对接口返回的数据进行处理,默认为
return data
,即不进行处理。成功回调:配置接口调用成功时触发的事件。
失败回调:配置接口调用失败时触发的事件。
高级配置
防抖:设置防抖表达式,避免接口的频繁调用。
禁止执行条件:根据条件表达式确定是否执行此集成操作。
手动触发集成
事件触发
在需要触发集成操作的组件中,配置事件处理器。
将动作类型设置为集成操作,并选择相应的集成。
以对象形式填写已配置的参数。
API 触发
若此集成操作的名称为action1
,则在任何可以执行脚本的地方,可以使用action1.trigger()
方法触发集成操作,若集成操作配置了参数,则需要以对象形式填写已配置的参数。