接口资源

一、接口资源是什么

在搭建智能应用或工作流时，我们经常需要调用外部能力——例如查询业务数据库中的记录、把数据写回业务系统，或者触发一段业务流程。平台需要先知道接口地址、请求方法、参数和鉴权方式，才能正确发起调用。这就是「接口资源」的作用。

简单来说，接口资源用于把你自有业务系统的 REST 接口登记进平台。登记完成后，可以通过以下两条路径使用：

• 在工作流中添加「接口资源」节点，直接调用接口；
• 在技能中引用接口资源，再由智能体通过技能调用。

与三方服务、插件 / MCP 的区别

平台里有几个功能看起来都像"调用外部能力"，初次接触容易混淆，这里先划清边界：

• 三方服务是平台已经预置好服务和工具定义的通用能力（如 OCR、语音、搜索等）。你通常不需要手动描述接口结构，但部分服务仍需配置厂商凭证或服务地址。
• 插件 / MCP 是按标准协议（插件规范、MCP 协议）接入的外部工具。
• 接口资源 则是把你自己业务系统的 REST 接口登记进来，由你手动填写接口地址、参数和鉴权信息。

一句话区分：现成的通用服务用三方服务，标准协议的工具用插件 / MCP，自有业务后端的接口用接口资源。

关于"接口资源"与"数据资源"两个名称

需要特别说明的是：资源在「资源中心」登记时叫「接口资源」；在工作流或技能的资源选择窗口中，窗口标题可能显示为「选择数据资源」。这里的数据资源包含已经登记的接口资源，看到名称不一致时不必退出页面。

二、开始前准备

第一次登记接口前，先向接口提供方取得以下信息：

需要准备	示例	用途
接口 URL 前缀	https://api.example.com/v1	创建业务系统
接口相对路径	/todos/{id}	创建具体接口
请求方法	GET、POST	确定调用方式
鉴权要求	API Key、请求头名称	配置业务系统鉴权
输入参数	id、title	配置接口输入
成功响应示例	接口返回的 JSON	配置并核对输出
测试数据	测试用 ID、标题等	调试接口

还需确认：

• 接口可以被平台所在网络访问。本机浏览器能够访问，不代表平台服务端一定能够访问；
• 写入、更新或删除类接口应优先连接测试环境，并准备不会影响真实业务的测试数据；
• 涉及患者或医疗业务数据时，应使用测试数据或脱敏数据；
• 当前账号具有相应操作权限。查看、新增、编辑、调试和删除权限由管理员在「角色管理」中分配；页面缺少操作按钮时，先检查角色权限。

三、核心概念：厂商、业务系统、接口

接口资源采用三层结构来组织，从大到小依次是：

1. 厂商：接口的提供方或归属方，是最外层的分类。例如"华西数医"。
2. 业务系统：归属于某个厂商，是一组接口的来源。一个业务系统会统一配置接口 URL 前缀和鉴权方式，其下所有接口都共享这份配置。例如"待办事项管理系统"。
3. 接口：挂在业务系统之下的一个个具体接口，例如"创建待办""查询待办列表"。每个接口只需填写相对路径，最终访问地址由"业务系统的 URL 前缀 + 接口相对路径"拼接而成。

理解这个层级关系很重要：鉴权和地址前缀配置在业务系统上，具体接口只描述自己的那一段路径和参数。这也是为什么添加接口前，需要先有一个业务系统。

四、页面总览

进入「基础服务 → 资源中心 → 接口资源」，即可看到接口资源的管理页面。页面左侧是业务系统列表，右侧是当前所选业务系统下的接口列表。

业务系统的两种查看方式

左侧业务系统列表支持两种组织视角，通过「按系统」和「按厂商」切换：

• 按系统：以业务系统为单位展示，例如直接看到"待办事项管理系统"。
• 按厂商：以厂商为单位展示，例如看到"华西数医"，点开后是该厂商下的业务系统。

接口列表与筛选

右侧接口列表以表格形式展示每个接口的核心信息：接口标识、接口名称、接口路径、添加时间、接口状态，以及操作入口（编辑、调试、更多）。列表上方提供了若干工具，帮助你在接口较多时快速定位：

• 状态筛选：按接口状态过滤，默认为"全部状态"。
• 排序：默认按"最新添加"排序。
• 搜索：按接口名称或标识搜索。
• 分页：底部可切换页码和每页显示条数。

五、创建与管理业务系统

添加接口之前，需要先有一个业务系统。如果目标业务系统已经存在，直接向其中添加接口即可；如果还没有，则先新建一个。

新建业务系统

点击左侧「业务系统」标题右侧的加号按钮，打开「添加业务系统」弹窗，按要求填写以下字段：

• 系统名称（必填）：业务系统的名称，作为一组接口的来源标识。
• 所属厂商（必填）：选择该业务系统归属的厂商。如果列表中没有需要的厂商，可点击说明文字中的"这里"添加新厂商。
• 系统描述（必填）：简要描述该业务系统或其包含的接口，最多 200 字。
• 接口 URL（必填）：接口 URL 前缀，如 https://api.example.com/v1。该业务系统下所有接口都会以此作为访问前缀。
• 鉴权类型（必填）：选择接口被调用时的鉴权方式，分为"不需要鉴权"和"API Key 鉴权"两种（详见下文）。

鉴权类型

不需要鉴权：接口调用时不携带任何鉴权信息，适用于无需认证即可访问的接口。

API Key 鉴权：选择后会展开更多配置项，用于以 HTTP 头部的方式携带 API Key：

• 鉴权头部前缀（必填）：可选 Basic、Bearer 或 Custom。
• API Key 名称（必填）：HTTP 头部中 API Key 的名称，默认为 Authorization，也可自定义。
• API Key 内容（必填）：填写实际的 API Key 值。

Basic、Bearer 和 Custom 配置在业务系统层，不在添加接口页面中。选择哪一种、API Key 名称填写什么，应以接口提供方给出的鉴权要求为准。配置完成后，该业务系统下的接口会共享这套鉴权信息。

不要根据名称猜测鉴权格式。如果接口文档没有明确说明请求头名称、前缀和密钥内容，请先向接口提供方确认。

API Key 代表访问业务系统的权限，应作为敏感凭证管理：

• 不要在文档、聊天记录或公开截图中展示真实 Key；
• 测试环境与生产环境建议使用不同凭证；
• 为平台签发满足调用需求的最小权限凭证；
• 凭证泄露或不再使用时，应及时轮换或撤销。

编辑或删除业务系统

将鼠标移到左侧某个业务系统上，其右侧会出现 ... 菜单，点击可看到「编辑系统」和「删除系统」两个操作。「编辑系统」会打开与新建时相同的表单，可修改名称、描述、URL 前缀和鉴权配置。需要注意的是，所属厂商在编辑时不可更改

删除业务系统会连同其下的接口一并移除，请谨慎操作。

六、添加接口 —— 基本信息

选中一个业务系统后，点击右上角「添加接口」，进入接口的添加页面。页面分为「基本信息」和「参数配置」两大部分，本节先介绍基本信息。

• 接口名称（必填）：接口的名称，需含义简略且符合平台规范，如"获取…""添加…"等。
• 接口标识（必填）：接口的唯一标识，需尽可能表意，建议使用有意义的英文标识（如 createTodo）。
• 接口描述（必填）：描述接口的主要功能和使用场景，最多 200 字。描述会帮助用户和大模型更好地理解该接口的用途，因此应写得清晰、准确。
• 接口路径（必填）：填写接口的相对路径，以 / 开头（如 /v1/openapi/todos）。路径前缀已由业务系统的接口 URL 决定，此处只需填相对部分，页面会展示"前缀 + 相对路径"的完整地址供你确认。
• 请求方法（必填）：选择接口的 HTTP 请求方法，可选 GET、POST、PUT、DELETE、PATCH。
• 接口状态（必填）：设置接口的当前状态，可选"已发布""测试中""已下线"（详见"九、接口状态说明"）。

七、添加接口 —— 参数配置

参数配置分为「输入参数」和「输出参数」两部分，分别描述接口的入参和返回结果。点击「添加参数」可逐行添加。

输入参数

每一行输入参数包含以下配置：

• 参数名称（必填）：参数的名称，如 id、title。
• 参数描述（必填）：说明该参数的含义、取值范围等，便于用户和大模型理解。
• 参数类型（必填）：参数的数据类型，可选 String、Integer、Number、Boolean、File（File 下还可细分为 Image、Doc、Code、Ppt 等）。
• 传入方法（必填）：参数以何种方式传入，可选 Query、Body、Header、Path。
  • Path：路径参数，对应接口路径中形如 {id} 的占位。
  • Query：URL 查询参数。
  • Body：请求体参数。
  • Header：请求头参数。
• 是否必填：勾选表示该参数为必填。
• 默认值：为参数设置默认值，调用时未提供则使用该值。
• 开启：控制该参数是否启用。

举例：路径为 /v1/openapi/todos/{id} 的接口，会有一个名为 id、传入方法为 Path、必填的参数，与路径中的 {id} 占位对应。

输出参数

输出参数用于声明接口调用后可供工作流或技能使用的字段，配置项包括：

• 参数名称（必填）：返回字段的名称。
• 参数描述（必填）：字段含义说明。
• 参数类型（必填）：字段的数据类型。
• 开启：控制该字段是否启用。

输出参数应以接口实际成功响应为准，参数名称和类型需要与返回字段一致。例如接口返回 id 为整数，就不要把它声明为 String。如果响应包含对象、数组或嵌套字段，而当前页面中没有对应的配置方式，应先通过调试确认平台实际输出，再按界面支持的类型配置，不要自行猜测字段路径。

全部信息填写完成后，点击页面底部「保存」即可完成接口的添加。

八、导入接口

当你需要一次性登记多个接口，或已经有现成的 OpenAPI / Swagger 规范文档时，逐个手动添加会比较繁琐。此时可以使用「导入接口」功能，通过喂给平台一份 OpenAPI 规范文档来批量创建接口。

点击右上角「导入接口」，打开导入弹窗。平台支持三种导入方式：

1. 手动输入 Schema：将 OpenAPI 的 JSON / YAML 内容直接粘贴进文本框。
2. URL 中导入：填写一个能访问到 OpenAPI 文档的链接（如后端暴露的 /v3/api-docs、/swagger.json），由平台拉取并解析。
3. 本地上传：从本地上传一份 OpenAPI 文档文件。

三种方式最终都会解析规范文档，并在当前所选的业务系统下生成接口。

导入前请务必先在左侧选中目标业务系统，否则接口不知道应归属到哪个业务系统。

以手动输入 Schema 为例

下面以最常用的"手动输入 Schema"为例，演示一份最小可用的 OpenAPI 规范：

{
  "openapi": "3.0.0",
  "info": {
    "title": "示例接口",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/openapi/example/{id}": {
      "get": {
        "operationId": "getExample",
        "summary": "查询示例",
        "description": "根据 ID 查询示例的完整信息。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "示例 ID",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "成功"
          }
        }
      }
    }
  }
}

平台在解析时会把规范文档里的字段映射到接口的各项配置，主要对应关系为：operationId → 接口标识，summary → 接口名称，description → 接口描述，paths 的键 → 接口相对路径，in: path 的参数 → 传入方法为 Path 的输入参数。

导入时的两点注意

1. 每个操作必须包含 responses。 平台的解析器要求每个接口操作至少有一个 responses 对象（例如上例中的 "200": { "description": "成功" }），否则会报 SCHEMA_INVALID 校验错误，提示 value of responses must be an object。这是标准 OpenAPI 规范的要求。

2. 未声明 servers 时会提示 ServerUrl 不一致。 如果导入的 Schema 中没有声明 servers 字段，平台会弹出「ServerUrl 不一致提示」，告知将沿用业务系统里已保存的接口 URL 前缀。此时选择「继续同步」即可——导入不会覆盖业务系统的 URL 前缀，运行时接口调用仍以业务系统的地址为准。这也正是推荐做法：Schema 里只写相对路径，地址前缀交给业务系统统一管理。

新增还是更新

点击「确定」后，平台会弹出二次确认框，明确告知本次同步将新增 N 个或更新 N 个接口，并提示该操作不可恢复。其判断规则是：按 operationId 与接口路径匹配已有接口，命中则整条更新覆盖，未命中则新增。

请特别注意：如果导入的 operationId 与路径和某个已有接口相同，会直接覆盖该接口的全部配置（包括输入输出参数），且不可恢复。导入前请确认标识与路径是否与已有接口重复，避免误改。此外，更新类导入不会改变接口的"添加时间"，因此列表在默认"最新添加"排序下不会置顶，确认是否更新成功可进入接口编辑页核对。

九、调试接口

接口登记完成后，可以在列表中点击某个接口的「调试」，打开调试面板验证接口是否正常工作。面板左侧「输入参数」区列出该接口的入参，可逐项填写参数值；点击「运行」后，右侧「输出结果」区会展示接口实际返回的内容。

怎样判断调试结果

• 调用成功时，在右侧核对实际输出是否符合接口预期，重点检查字段名称、字段类型和业务数据；
• 页面提示「接口试运行失败」且右侧显示「暂无输出」时，表示本次调用没有得到可展示的结果；
• 调试失败时，依次检查业务系统 URL、接口相对路径、请求方法、鉴权配置、必填参数及测试数据；
• 如果页面未展示更详细的失败原因，需要结合接口提供方的服务日志继续排查。

重要提醒：调试会真实调用后端接口。 对于查询类接口（GET），调试只是读取数据，通常没有副作用；但对于创建、更新、删除类接口（POST / PUT / DELETE 等），调试会真实地在后端产生数据变更——例如调试"创建"接口会真的新增一条数据。请在充分了解接口副作用的前提下进行调试，避免在生产环境产生脏数据或误删数据。

十、接口状态说明

每个接口都有一个状态，用于标记其在生命周期中的阶段，可选三种：

• 已发布：接口正常对外提供。
• 测试中：接口处于测试阶段。
• 已下线：接口不再提供服务。

接口状态用于团队协作时标识接口所处阶段。当前选择资源窗口中可以看到接口状态，并支持按状态筛选；截图所示的「测试中」接口仍提供调试和添加入口。使用前应核对状态，避免把测试接口误用于正式流程；「已下线」接口能否继续调用，以当前页面的实际提示和运行结果为准。

十一、在工作流中调用接口资源

接口调试通过后，可以把它作为节点加入工作流。

11.1 添加接口资源节点

1. 打开目标工作流的编排画布，点击底部「添加节点」；
2. 在节点列表中选择「接口资源」；
3. 在「选择数据资源」窗口中，按系统或厂商找到目标接口；
4. 如需再次确认接口效果，可以点击「调试」；确认无误后点击「添加」，再点击「确定」。

这里的节点名称是「接口资源」，选择窗口标题是「选择数据资源」，二者不是两个不同的功能。

接口添加完成后，画布会显示接口资源节点，并自动带出登记接口时声明的输入参数和输出参数。

11.2 配置输入和使用输出

点击接口资源节点，在右侧配置面板中填写输入变量：

• 带 * 的变量为必填项，未填写时节点会显示橙色提示；
• 变量值可以直接填写，也可以引用开始节点或其他上游节点的输出；
• 登记接口时配置的默认值会自动显示，例如图中的 priority 和 status；
• 输出区域列出该接口可供下游节点引用的字段及类型。

配置完成后，将接口资源节点连接到下游节点。下游节点需要使用接口结果时，引用该节点对应的输出字段。最后点击节点右上角的运行按钮进行单节点验证，或点击画布顶部「试运行」验证完整工作流。

11.3 工作流调用检查

• [ ] 所有必填输入均已填写或引用；
• [ ] 引用的上游变量类型与接口输入类型一致；
• [ ] 默认值符合当前业务场景；
• [ ] 下游节点引用了正确的输出字段；
• [ ] 使用测试数据完成过单节点或整条工作流试运行；
• [ ] 写入、更新和删除操作没有误用生产数据。

十二、在技能中引用接口资源

除了在工作流中直接调用，接口资源还可以被技能引用，再由智能体在运行时调用。

在技能编辑器中编写 SKILL.md 时，工具栏提供了「选择数据资源」入口（前面提到，接口资源在技能里叫"数据资源"）。点击后会打开「选择数据资源」弹窗，其中列出当前业务系统下的接口，可对每个接口进行"调试"或"添加"。选择需要的接口并确定后，该接口就会作为数据资源被引用到技能中。

这样，技能调用链路就完整了：在接口资源中登记接口 → 在技能中以"数据资源"引用 → 智能体运行时实际调用。关于技能的编写与发布，可参阅技能管理章节。

十三、完成检查

完成接口登记后，按实际使用方式检查：

• [ ] 业务系统 URL、鉴权方式和凭证已经核对；
• [ ] 接口路径、请求方法、输入参数和输出参数与接口文档一致；
• [ ] 已使用测试数据完成接口调试；
• [ ] 接口状态符合当前使用阶段；
• [ ] 在工作流中使用时，已配置输入、连接下游并完成试运行；
• [ ] 在技能中使用时，已添加对应数据资源并验证智能体能够调用；
• [ ] 调试数据和输出中不包含不必要的患者敏感信息；
• [ ] 当前账号及实际使用者已获得所需角色权限。