API插件

新建API

1. 进入机器人空间，点击“知识库>API插件”，点击“新建API”，打开新建API弹窗，下面是新建API的配置方法：

• 服务名称：需要遵守变量名规范，包括单词+下划线和连续单词大写字母间隔两种方式，如 income_proof 或 incomeProof，注意只能使用英文；

• 服务描述：主要描述清楚API的功能，可以包含少量出入参的信息，如根据XX查询XX，查询天气等，如果对API有一些特殊要求也可以写到服务描述，如XX和XX参数两个均为非必选，但是必须要有一个；

• API调用时间较长时，用户对话窗提示：API调用时间可能比较长，可以定义一些提示信息，如正在为您查询中；

• API配置：API调用的接口配置、header配置、输入参数、输出参数、签名认证、服务模拟的配置：

  • 接口配置：选择请求方式，输入接口的URL；

  • header参数：输入请求头参数；

  • 输入参数：包括每个参数的参数名、类型、取值来源、是否必填和参数解释。

    • 参数：跟上述参数名规范一样，按照变量名规范来定义，仅支持英文。

    • 类型：包含String、Number、Boolean；

      说明

      String：表示文本类型，用于表示名称、描述、ID、状态码等。

      Number：表示数字，表示整数或浮点数，用于计数、金额、时间戳等

      Boolean：表示 true 或 false，用于表示开关、状态、是否成功等。

    • 取值来源：包括模型识别和随路参数，其中随路参数不会传输给模型去识别。

    • 是否必填：当前参数是否为必填参数，建议一个API至少包含一个必填参数，对于选填参数，机器人不会主动询问，但是有表达对应内容时也会识别。

    • 参数解释：类似于上述参数说明，包括中文名、格式化描述和示例三部分。

    说明

    对于一些其他的变量类型，如枚举，我们通过对应的参数描述来实现，入参定义实例如下：

    

  • 输出参数：整体规范同输入参数定义：

    • 首先需要确定输出参数的组织形式，包含Object、List、String、Number、Boolean；

      说明

      Object：由多个字段组成的结构化数据。

      List：有序的同类型元素集合，每个元素可以是基本类型或对象。

    • Mock值，在没有真实的URL请求时，可以通过该字段设置API的固定返回，并且需要打开服务模拟服务；

  • 签名认证：为保证 HTTP/HTTPS 服务的安全使用，在服务配置中可选择开启签名计算，在调用 API 时全局服务会对开启签名的服务进行签名计算，并将签名放到请求header中。

  • 可参考《签名计算使用指引》文档进行操作。

  • 服务模拟：当输出参数为Mock值时，需要打开服务模拟的开关。

    说明

    应用Mock值时需要在对话调试窗打开开关，一旦打开则优先级高于URL请求，如：

2. 配置好后点击“确定”即可新建成功，如下图为API配置完成的界面：

API调试

API 插件配置完成后，使用“调试”功能，验证对话机器人调用 API 插件链路是否正常。

1. 点击“调试”按钮，打开API调试窗口，

2. 输入“输入参数”信息，点击“开始调试”，接口显示调试成功并返回正确信息，说明接口配置没有问题。