为自定义工具接入API

基于表单逐项手动录入接入API

1. 登录数据智能平台并选择目标工作空间。
2. 在左侧导航栏选择“工具 > 自定义工具”，进入自定义工具页面。
3. 在工具列表中找到目标工具，在其操作列单击“编辑”，进入工具详情页。
4. 单击“新建API”，右侧滑出“创建API”窗口。
5. 参考表1中的字段说明，完成API基础信息配置后，单击“下一步”。

   表1 API基础信息

   字段	描述
   名称	API的名称，在同一工具内须保持唯一，对应OpenAPI或Swagger规范中的operationId字段。 必填，只能包含英文、数字、中划线（-）及下划线（_），需以字母或下划线开头，且长度不能超过128个字符。
   描述	用于简要说明该API的核心功能、适用场景及调用约束。 必填，长度不能超过2048个字符。
   URL	API级URL，定义具体某个API接口的访问路径。 必填，长度不超过255个字符。 完整请求地址由工具级Server URL（基础服务地址）与API 级URL（接口的path）拼接而成。例如： Server URL：https://api.example.com URL：/v1/search 完整请求地址 = https://api.example.com/v1/search
   请求类型	HTTP请求方法，用于定义接口的操作语义。 必填，支持以下请求类型。 Get：获取或查询数据，参数通过URL传递。 Post：创建新数据，参数通过请求体传递。 Put：全量更新已有数据。 Patch：部分更新已有数据。 Delete：删除数据。

6. （可选）配置API请求参数。完成后，单击“下一步”。
   1. 选择API请求参数的传递位置。

      表2 参数位置说明

      参数位置	说明	示例	常见用途
      Header	放在请求头中，通常用于传递元数据（如鉴权信息、内容类型）。	Authorization: Bearer xxx、Content-Type: application/json	API认证、格式声明
      Path	作为URL路径的一部分，用于标识特定资源。	/users/{id} 中的 {id}	资源标识（如用户ID、订单号）
      Query	放在URL问号后的参数，用于过滤、排序或分页。	/search?q=keyword&page=1	搜索、过滤、分页
      Body	放在请求体中，用于传递结构化数据（如JSON）。	{"name":"张三","age":25}	创建或更新资源

   2. 单击“添加参数”，参考表3中的字段说明，设置对应的参数信息。

      表3 参数信息

      字段	描述
      参数名称	API请求中用于标识和传递数据的字段名，在同一请求中，Header、Path、Query、Body的参数名称须保持唯一。 只能包含英文、数字、中划线（-）及下划线（_），需以字母或下划线开头，且长度不能超过128个字符。
      描述	用于说明参数的核心功能、数据格式及填写约束。
      默认值	当请求中未显式传递该参数时，系统自动采用的预设值。 仅适用于非必填参数。
      参数类型	用于定义参数的数据格式。包括以下类型： String：字符串类型，支持文本内容。例如：张三、user_001 Integer：整型数字，不含小数位。例如：25、-100 Number：数字类型，可含小数位。例如：3.14、99.9 Boolean：布尔值，true或false。 Array：数组类型，包含多个值。例如：["a","b","c"] 说明： 当参数类型为Array时，需配置数组元素类型。 Object：对象类型，包含多个键值对。例如：{"name":"张三","age":25} 说明： 当参数类型为Object时，需配置其子字段信息，且支持嵌套结构的定义。
      是否必填	用于标识该参数是否为调用接口时的必需参数。必填参数缺失将导致请求失败。

   3. 完成API请求参数配置后，单击“下一步”。

7. （可选）配置API响应参数。

   单击“添加参数”，参考6中请求参数的配置操作，完成API响应参数配置后，单击“保存并下一步”。

8. 调试API。

   在输入参数区域中为各参数填写相应的测试值，单击“运行”，系统将返回调试结果并显示在调试输出区域。

   如果结果不符合预期，请检查参数配置与输入值后重新调试。

9. （可选）如需添加多个API接口，请重复4至8的操作。

基于已有Schema内容快速接入API

1. 登录数据智能平台并选择目标工作空间。
2. 在左侧导航栏选择“工具 > 自定义工具”，进入自定义工具页面。
3. 在工具列表中找到目标工具，在其操作列单击“编辑”，进入工具详情页。
4. 单击“导入schema”，弹出“导入schema”窗口。
5. 将符合OpenAPI/Swagger规范的Schema文档内容粘贴至输入框。

   表4 Schema内容约束说明

   约束	要求
   格式	支持YAML、JSON格式。
   版本	支持OpenAPI 3.x、Swagger 2.0。
   内容要求	必须包含paths字段，且至少定义一个API接口。
   引用支持	仅支持内部$ref引用（#/），不支持循环引用Schema。

6. 单击“确定”。

   系统将调用Schema解析接口，对已输入的API信息进行自动解析，解析逻辑如下。

   1. 读取Schema中的paths字段，提取各个API接口的访问路径与请求方法（GET、POST等）。
   2. 解析各接口下的parameters字段，提取请求参数的名称、参数位置（Header/Path/Query/Body）、数据类型、是否必填等属性定义。
   3. 针对通过$ref引用的数据结构，系统按引用路径（例如#/components/schemas）递归展开，解析嵌套参数。

   解析过程中，系统将自动同步校验工具名称、Server URL的合法性以及operationId的唯一性、保存工具及API数据、建立工具与API的关联关系。解析完成后，可在“可用工具”区域查看从YAML中解析出的API列表。如遇解析失败，请参考解析失败常见原因与处理方式进行排查处理。

解析失败常见原因与处理方式

解析失败通常与文档格式或内容不符合规范有关。以下是常见原因及对应的处理方式：