连接器的操作等同于发起一次 HTTP 接口请求,这里我们将介绍如何开发一个自建连接器的操作。
新建一个操作
- 点击左侧资源列表的 “+” 加号,选择新建操作。
- 你需要填写操作的展示名称和选择操作的所属分组,若无分组需要先创建分组。
- 点击下一步后,需要填写 API 请求的样例,你可以对照 API 接口文档将请求样例粘贴进来,包含请求 URL,请求头,请求体,响应体。
- 点击保存后,操作就创建成功了。新建成功的操作会在左侧资源树中展示。
文档中与认证相关的参数可以忽略,官方提供的凭证模型会在请求中自动携带认证参数。
250px|700px|reset

调整操作的入参和出参表单展示
- 从左侧资源树进入新建的操作,在这里我们可以对该操作在工作流右侧表单中的展示做更精细的调整。
- 在基本信息 Tab 中,我们可以修改连接器操作的名称、描述,基本信息的修改在右侧模拟器中会实时联动展示效果。由于一些凭证模型支持了多种认证方式,也可以在这里指定这个操作是否只支持一种认证方式。
- 例如,飞书的一些接口只支持使用 tenent access token 访问,可以在这里指定这个操作支持的认证方式。
- 在入参 Tab 中,你可以修改表单参数的顺序,也可以针对每个参数修改参数在表单中的展示名、参数的输入控件与输入规则。
- 在出参 Tab 中,你可以配置出参的数据结构与展示名称,同样的,任何修改在右侧模拟器中都会实时联动展示。
250px|700px|reset

编辑基本信息
250px|700px|reset

调整表单顺序和名称
250px|700px|reset

调整表单控件的样式
配置 API 映射(可选)
连接器操作的背后实际是发起了一次 HTTP 请求,我们可以在 API 配置 Tab 中申明如何将操作入参里用户填写的值,映射到 HTTP API 的请求中。
由于创建操作时已填写了 Path、Query、Header、Body 参数,因此 API 配置 Tab 中会有一些初始化自动生成的映射配置。
250px|700px|reset

创建 API 后默认生成的配置
当我们对入参表单字段进行二次修改,或者新增表单字段时,我们需要手动将新增或修改的字段重新映射到 API 配置中。在 API 配置 Tab,我们支持了简单的模版语法,并支持了变量提示与错误提示的功能。同样的如果是 API 请求中固定的值,我们也可以在 API 配置中直接设置常量。
如果需要在请求中插入操作入参表单用户填写的值,你可以输入双花括号 {{ ,编辑器会自动唤起联想。你可以使用 {{input.name}} 表示取入参表单中的 name 字段放在此处,使用 {{input.objectName.fieldName}} 表示取入参表单中 objectName 对象中的 fieldName 字段放在此处。如果入参表单中不存在对应的字段,此处会有错误提示。
250px|700px|reset

配置 API 映射
API 的请求体支持多种格式,当你的系统请求体格式不为 JSON 时,可以在请求体 Tab 中进行切换,修改为其他的格式如 form-data。
请求的 URL,请求头,查询参数均支持配置参数映射;当你需要将整个请求体进行映射时,可以通过编辑器右上角的切换为表达式为整个请求体配置映射关系。
当请求中包含固定值时,我们也可以在 API 配置中设置固定值;这些信息不会暴露在表单中,而会在每次请求中携带。
250px|700px|reset

配置请求头的固定值
配置状态码(可选)
完成操作的开发后,我们可以能还需要配置状态码。通常我们可以通过 HTTP 状态码来判断成功与不同的失败原因,并且平台会内置一套标准的 HTTP 状态码的判断配置。
但是对于一些平台,可能将请求的状态判断内置在了请求体内部的字段里进行判断;这时就需要我们再配置应用状态码。以飞书开放平台的接口为例:
- 通过接口响应体中的 code 字段判断请求是否成功,当 code = 0 时表示成功;非 0 时,通过 body 中的 msg 字段反馈具体的错误信息描述。
- 此时我们需要配置应用状态码路径为 {{body.code}} ,错误描述路径为 {{body.msg}}。
- 然后再配置状态码表中表示为成功的状态码,我们需要编辑内置的判断条件,新增应用状态码等于 0。此时,一次请求必须既要满足 HTTP 状态码在 200-299 之间,并且应用状态码为 0,才判断为执行成功。
我们可以在连接器的全局维度统一配置所有操作的状态码;但是当某一个操作有特殊的成功 or 错误判断,我们可以在单个操作的维度进行状态码的配置。在连接器操作执行时,会优先判断是否匹配了操作维度的状态码,若未匹配,则会匹配连接器维度的全局状态码。在连接器维度的全局状态码上,你可以配置所有状态码均未命中情况下的默认策略。
250px|700px|reset

编辑连接器全局的状态码表,配置判断响应成功和失败的条件
250px|700px|reset

编辑连接器全局的默认策略,当所有匹配规则没有命中时,采用默认策略
250px|700px|reset

在操作维度也支持配置响应成功和失败的判断规则,运行时,优先使用操作维度的配置进行判断