# 为自定义工具接入API 创建自定义工具后，需为其接入API接口，以完成工具能力的定义。系统提供两种接入方式，请结合实际情况选择合适的方式。 - **基于表单手动录入**：适用于无现成OpenAPI文档的场景。通过表单手动定义工具的API接口信息，逐项配置请求参数及响应体字段。配置完成后，系统会将表单录入的参数信息转换为OpenAPI文档格式存储，保证与YAML文件导入方式的数据结构完全一致。 - **基于Schema导入**：适用于已有符合OpenAPI规范的YAML文档场景。无需逐项填写参数，只需将已有Schema内容复制粘贴至指定输入框，系统会自动解析文档中的API信息，并生成完整的工具配置。 #### 基于表单逐项手动录入接入API 1. [登录数据智能平台](https://support.huaweicloud.com/usermanual-dataartsplatform/dataartsplatform_02_0003.html#ZH-CN_TOPIC_0000002749200638__li15819195745117)并选择目标工作空间。 2. 在左侧导航栏选择"工具 \> 自定义工具"，进入自定义工具页面。 3. 在工具列表中找到目标工具，在其操作列单击"编辑"，进入工具详情页。 4. 单击"新建API"，右侧滑出"创建API"窗口。 5. 参考[表1]中的字段说明，完成API基础信息配置后，单击"下一步"。 表1API基础信息 | 字段 | 描述 | |:---|:---| | 名称 | 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. [登录数据智能平台](https://support.huaweicloud.com/usermanual-dataartsplatform/dataartsplatform_02_0003.html#ZH-CN_TOPIC_0000002749200638__li15819195745117)并选择目标工作空间。 2. 在左侧导航栏选择"工具 \> 自定义工具"，进入自定义工具页面。 3. 在工具列表中找到目标工具，在其操作列单击"编辑"，进入工具详情页。 4. 单击"导入schema"，弹出"导入schema"窗口。 5. 将符合OpenAPI/Swagger规范的Schema文档内容粘贴至输入框。 表4Schema内容约束说明 | 约束 | 要求 | |:---|:---| | 格式 | 支持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列表。如遇解析失败，请参考[解析失败常见原因与处理方式]进行排查处理。 #### 解析失败常见原因与处理方式 解析失败通常与文档格式或内容不符合规范有关。以下是常见原因及对应的处理方式： 表5解析失败常见原因及处理方式 | 错误提示 | 可能原因 | 处理方式 | |:---|:---|:---| | Schema格式错误 | YAML文档不符合OpenAPI规范，例如YAML缩进错误、$ref循环引用等。 | 检查文档格式，确保符合OpenAPI 3.x或Swagger 2.0规范。 | | Server URL不合法 | 未提供合法的服务地址。 | 在YAML中补充servers字段，或手动填写Server URL。 | | operationId重复 | 同一工具下存在相同operationId的API。 | 修改YAML中重复的operationId，确保唯一性。 |