集成流

魔笔平台提供了强大的集成流编排功能,允许用户通过简单的配置,快速构建一个可以执行多种复杂操作的集成流。本文将指导您如何使用集成流功能。

什么是集成流

集成流可以将多个集成操作有序的组合起来,从而处理高复杂度的逻辑。魔笔提供了丰富的集成流节点,包括自定义代码、大模型、资源连接、逻辑判断等。用户可以根据自己的需要组合编排节点,快速搭建一个集成流。

集成流设计器界面说明

集成流界面.png

集成流设计器界面说明:

标注

功能名称

使用说明

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 节点集合【非必须】。集合中可以包含任意节点。

名称

说明

类型

条件

判断的条件,需要返回true或者 false

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 对象包含codemessage属性。

  • 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 各自创建出了独立的内部作用域。

构建集成流

新建集成流

首先需要创建一个集成流。在控制台中依次选择资源 > 集成流,选择创建集成流

创建集成流.jpg

编排集成流

集成流的编排可能包含以下动作:

  • 创建一个节点。

  • 更改节点的标识符 id(仅为更具可读性,非必须)。

  • 设置节点的配置项。

  • 观察错误检查面板是否存在错误。

  • 克隆节点进行小范围修改。

  • 删除错建错配的节点。

  • 节点调试(集成节点)。

  • 调整节点的关系(依据实际需要)。

您可以通过以下动作操作集成流节点:

  • 添加节点 :当鼠标放置在节点间的边上时,会出现添加节点的按钮。点击并选择节点类型即可添加一个节点。节点生成之后带有一个默认的节点 id,它是节点的唯一标识,也是节点作用域下的节点变量。节点 id允许被修改,像定义变量名一样,赋予一个可读的名称。如需修改节点的标识符 id,可选中节点,点击 id一栏进行修改。id 作为节点的唯一标识符,不可重复。

  • 删除节点:选中节点,在配置面板下方选择删除节点。或者,点击节点卡片上更多按钮,选择“删除节点”。

  • 克隆节点:点击节点卡片上更多按钮,选择“克隆节点”。

  • 移动节点:可通过拖拽将节点调整到预想的位置。位置改变也意味着节点关系发生了变化。例如 if 节点集合下的节点被拖到 else 节点集合下,它将在 else 逻辑被触发时执行。

在完成节点添加操作后,您还需要为每个节点配置必要的属性信息。选中节点后,编辑器右侧的配置面板中会出现该节点的配置项。

调试集成流

当配置完一个集成节点,或者整个流已经编排完成,验证它们是否能按预期工作是必不可少的一步。魔笔集成流编辑器也提供了调试功能。

触发器配置面板中的调试器可以用来模拟整个流的运行,集成节点对应的配置面板中的调试器可以用来测试当前的集成操作。

调试面板.png

上图为集成流中的调试面板,它主要由以下几个部分组成:

模拟参数

模拟参数中显示的是集成节点(action 节点)脚本或者配置中依赖的节点数据。

模拟参数以 JavaScript 对象的形式显示。对象的属性是在配置项中引用到的节点 id,值是节点对象值,一般默认为空值null

下面三种情况例外:

  • 在触发器面板设置的trigger模拟数据在全局可用。

  • 引用的节点是变量节点。魔笔将从该变量节点的配置中读取值(变量表达式中无外部节点引用,可通过eval直接得出结果)。

  • 若引用的节点是集成节点并且已有测试结果,则测试结果将作为默认值。

用户可对模拟参数进行添加、编辑、删除等操作。用户可根据自己的需要设置值。它将作为测试节点使用的参数。

说明

以下几点需要注意:

  • 保持节点对象结构完整,data属性不可删除。

  • 如需在输入框中输入对象,须使用()包裹内容,例如:({key:val})

测试结果

图中所示为测试的状态指示,不同颜色代表不同的状态,它有以下三种状态:

  • 灰色:待测试;

  • 绿色:测试成功,执行成功并得到结果;

  • 红色:测试失败,返回结果成功标识符为false,可根据错误提示,对配置或代码进行调整。

内容区将显示测试的结果,未再次进行测试或者模拟参数没有发生变更,测试结果将保持显示。

测试/运行

根据配置信息和模拟参数,运行流或者执行集成操作。

提交与发布

提交

提交后的集成流,将会产生提交记录,可在左侧功能面板 > 历史记录中查看。可对记录进行发布和回滚操作。

发布

默认发布最新一次的提交记录。如果当前工作区内容还未进行提交,选择环境并点击确定发布后会创建提交并发布此次提交。用户也可选择其他记录进行发布。发布后的集成流可在应用设计器中使用。

重要

集成流可以发布至开发环境或生产环境。如果您需要在应用编辑器内使用集成流集成操作,请先将目标集成流发布至开发环境。

为确保集成流在生产环境也能正确使用,发布应用前请确保相关集成流已发布至生产环境。

错误检查

和页面编辑器一样,集成流编辑器也提供了相应的错误检查功能,方便用户及时的发现问题。

集成流的错误检查主要包含以下内容:

  • 节点 id引用有效性检查;

  • JavaScript 脚本及表达式错误检查;

  • 节点配置必填项检查;

  • 节点引用的集成资源有效性检查。

错误面板.jpg

标注

功能名称

使用说明

1

错误搜索框

可搜索流中存在的错误

2

错误数及警告数

红色为错误,橙色为警告

3

错误信息

错误信息

4

错误路径

产生错误的节点位置,点击路径可选中该节点,并显示配置信息

使用集成流

通用配置

  • 参数:根据集成流内定义设置参数作为实际入参。

  • 触发方式:选择手动触发或自动运行。手动触发仅在触发集成操作事件或通过 API 调用action.trigger方法时执行。自动运行则在初次加载和依赖项变更时自动执行,例如当{{input1.value}}改变时。

  • 描述:为集成流操作提供详细描述。

回调配置

  • 数据转化:对接口返回的数据进行处理,默认为return data,即不进行处理。

  • 成功回调:配置接口调用成功时触发的事件。

  • 失败回调:配置接口调用失败时触发的事件。

高级配置

  • 防抖:设置防抖表达式,避免接口的频繁调用。

  • 禁止执行条件:根据条件表达式确定是否执行此集成操作。

手动触发集成

事件触发

  1. 在需要触发集成操作的组件中,配置事件处理器。

  2. 将动作类型设置为集成操作,并选择相应的集成。

  3. 以对象形式填写已配置的参数。

API 触发

若此集成操作的名称为action1,则在任何可以执行脚本的地方,可以使用action1.trigger()方法触发集成操作,若集成操作配置了参数,则需要以对象形式填写已配置的参数。