自定义变量的变量值是固定的，如果需要获取到动态的取值，就需要使用到API接口。API接口可以定义一个取数据的接口，在用户使用时，卡片会向这个接口请求获取数据。

一、创建API接口

点击API接口分类后的“+”号，创建一个API接口数据源。
image.png
image.png

  1. API接口名称：此API接口数据源的名称。最大长度为20，只支持英文和数字，且不能以数字开头。
  2. URL地址：请求数据的地址，支持 http/https 接口。
  3. 描述：API接口的描述信息。
  4. 请求方式：GET/POST 请求。
  5. 请求参数：可以定义发送请求时携带的参数。
  6. 数据过滤脚本：勾选数据过滤脚本，可以在下面的脚本中定义接口响应数的据处理或过滤规则（JS脚本）。
  7. 返回结果：点击返回结果后的“刷新”按钮，用来获取新的返回结果。

当刷新返回结果获取最新的数据后，就可以点击“确认”保存数据源的配置。如果点击“取消”，则之前填写的信息不会保存，此 API接口数据源还处在未编辑状态（API接口数据源名称后面有红点提示）。

二、api接口的操作

在api接口列表中，每个 API接口数据源有三个操作按钮：编辑、复制、删除。
此功能与自定义变量一致，请参考文档：自定义变量。
83.png

三、添加请求参数

请求参数有两种配置方式：手动配置 或 自定义代码输入。

3.1 手动配置

手动配置的参数可以是直接定义的值，也可以是数据中变量的变量值（包括系统变量和自定义变量）。

点击“+添加参数”按钮，在出现的参数配置栏中填写参数名，设置参数值。

  • 如果使用静态参数。则直接在参数值输入框中输入参数值，不用使用后边的“动态参数”。

静态参数.gif

  • 使用变量的值作为参数值。点击“动态参数”，在下拉列表中选择“变量”，然后在弹出的变量列表中选择使用的变量作为参数值。
    • 如果选择的是系统变量，会根据选择的测试设备不同，有不同的取值。所以在调试的时候，还需要给系统变量选择一个绑定的测试设备。
    • 如果选择的是自定义变量，参数的取值就是自定义变量的值。
    • 如果选择的是 slot 变量，则变量的取值从用户所说的语料中抽取。调试的时候，还需要给 slot 变量设置一个调试值，用来在在编辑器预览的时候使用，真机运行的时候会忽略这个调试值。

手动配置参数.gif

3.2 自定义代码输入

当接口参数太多不方便手动录入时，可以选择自定义代码录入。还可以点击输入框右上角“全屏”按钮，放大代码输入框。
代码输入参数.gif

自定义代码录入中的数据结构为 Map 集合，集合中的每一条数据都对应手动配置的一条参数。数据的 key 对应参数的名称；数据的值为一个 JSONObject，JSONObject 中有一条 value ，用来定义参数的取值。

支持在 value 里引用变量：自定义变量（缩写为：custom）、slot变量（缩写为：slot）或系统变量（缩写为：sys），引用变量时，value 的值需要使用${}包裹。

其中 slot 变量跟系统变量需要在 JSONObject 中输入 mockValue，等同于手动录入时输入模拟值或者选择设备的操作，mockValue 仅在编辑器发挥作用，卡片在设备上的运行将忽略 mockValue。

  1. {
  2.     "param1": {
  3.         "value": "static" // 表示使用静态参数值
  4.         },
  5.     "param2": {
  6.           "value": "${custom.name}", // 表示自定义变量中名称叫 name 的变量值
  7.         "mockValue": "" // 自定义变量可以省略不写
  8.     },
  9.     "param3": {
  10.           "value": "${slot.city}", // 表示 slot 变量
  11.         "mockValue": "杭州" // slot 变量必须填写 mockValue
  12.     },
  13.     "param4": {
  14.           "value": "${sys.date}", // 表示系统变量
  15.         "mockValue": "5月18日" // 系统变量必须填写 mockValue
  16.     }
  17. }

以下是系统变量的 mockValue 参考值 (slot 变量无约束)：

  1. {
  2.     "system1": {
  3.         "value": "${sys.date}",
  4.         "mockValue": "5月18日"
  5.     },
  6.     "system2": {
  7.         "value": "${sys.datestamp}"
  8.           "mockValue": 1621331881902
  9.     },
  10.     "system3": {
  11.         "value": "${sys.week}",
  12.         "mockValue": "星期二"
  13.     },
  14.     "system4": {
  15.         "value": "${sys.userOpenId}",
  16.           "mockValue": "bsxb9eCtvjnIoS76SFK2AVhZ0yN4DpXUJSIkQtcU="
  17.     },
  18.     "system5": {
  19.         "value": "${sys.deviceOpenId}",
  20.         "mockValue": "BMgbqFr30kf5+j1sfgasg7sfSFG3y8micMj8zX9F7NSmyQMuLWM76A=="
  21.     },
  22.     "system6": {
  23.         "value": "${sys.userId}",
  24.         "mockValue": 50227734
  25.     },
  26.     "system7": {
  27.         "value": "${sys.uuid}",
  28.         "mockValue": "4D14C5C16CSN6374HCB0335EDFE35"
  29.     }
  30. }

使用 ${} 的方式表示引用的是变量列表里的数据，请注意匹配变量名称。如果匹配不到变量名称则会将代码块解析为普通文本。

屏幕快照 2021-05-18 17.26.06.png

如果使用的变量类型缩写不匹配也会将代码块解析为普通文本。

屏幕快照 2021-05-18 17.37.05.png

四、数据过滤脚本

首先勾选“数据过滤脚本”。如果api接口返回的是一个JSON格式的对象，则可以通过脚本过滤出这个对象的某个属性值，或者执行一段JS脚本。

例如api接口返回的JSON对象的数据是：

  1. { 
  2.     "name": "张三",
  3.     "age": 18, 
  4.     "hobby": [
  5.         "吃饭", 
  6.         "睡觉", 
  7.         "打豆豆"
  8.     ] 
  9. }

则可以将脚本中的return data修改成return data.name过滤出返回对象的 name 属性值张三；
可以通过 return data.hobby[0]过滤出 hobby 属性数组值中的第一个元素吃饭；
可以通过return data.hobby.length获取 hobby 属性数组元素的个数3；
可以通过 return data.name.split("三")分割 name 属性的字符串，获得结果["张", ""]。
86.gif

修改脚本后，可以点击“运行”按钮，运行过滤脚本，给出 过滤器输入数据 和 过滤器运行结果 的对比。
87.png

如果过滤脚本的代码比较多，还可以点击“放大”按钮，打开编辑脚本的放大窗口。
88.gif

五、刷新返回结果

当设置好数据过滤脚本后，需要刷新返回结果，获取到这个api接口数据源最终的输出结果，才可以点击“确认”保存数据源。

如果刷新返回结果后更改了过滤规则，还需要重新刷新返回结果。