跳到主要内容
版本：Next

3.7、API对接助手

API对接助手通过自然语言、cURL 报文、JSON 参数或接口文档，自动识别 HTTP API 对接信息，生成请求参数、Header、Body、响应映射等配置方案，核心用于快速完成 MES、ERP、云平台等第三方系统对接。

3.7.1、功能说明​

  • 支持直接输入接口对接需求、cURL 报文、JSON Request Body、接口请求参数说明，或上传接口文档附件
  • 支持上传多个附件，单个文件不超过 10MB，支持 doc、docx、pdf、TXT、png、jpeg、webp 等格式
  • 可自动判断输入内容是单接口还是多接口，并提取接口地址、请求方法、Base URL、全局 Header、Params、Body 等配置项
  • 可根据响应示例生成 Response -> CMS 变量解析映射表，减少手动配置字段映射的重复操作
  • 当发现认证方式、Header、必填参数、响应映射等关键缺失项时，AI 会在对话中主动追问，帮助用户补齐信息
  • 可通过标准 Markdown 展示接口配置方案，用户确认方案无误后，可调用 CMS 的“新增 API 互联项”接口完成配置写入，并刷新页面展示新增配置

3.7.2、核心优势​

1. 降低接口对接门槛​

OT 工程师无需逐项研究 HTTP 请求结构、鉴权方式和响应解析规则，只需要提供接口资料或描述对接目标，AI 即可生成可确认、可调试、可写入的 API 配置方案。

传统方式 vs AI方式：

传统方式：
阅读接口文档 -> 手动拆解 URL、Header、参数 -> 配置请求体 -> 配置响应映射 -> 手动调试 -> 反复排错
需要：接口经验 + 文档理解能力 + 多轮手动配置

AI方式：
输入需求或上传文档 -> AI解析配置 -> 补充缺失项 -> 查看配置方案 -> 确认写入
需要：明确说明业务目标和数据映射关系

2. 减少配置错误和排错时间​

  • 接口识别：自动识别单接口、多接口、Base URL 和请求方法
  • 参数提取：自动整理 Header、Params、Body、认证信息等配置
  • 响应映射：根据返回示例生成字段到 CMS 变量的映射建议
  • 缺失项追问：发现关键配置缺失时主动提示用户补充

3. 加速第三方系统集成​

在 MES、ERP、WMS、云平台、告警平台等对接场景中，接口配置通常包含大量重复字段和格式规则。API对接助手可把“解析接口文档、配置参数、调试请求、映射字段”的过程集中到一次对话中完成，显著缩短项目实施周期。

3.7.3、典型使用场景​

场景一：MES 工单信息查询接口对接​

背景：设备扫码后，需要通过 MES 接口查询工单信息，并将产品型号、目标数量等字段写入 CMS 变量。

需求描述：

请帮我配置一个 MES 工单查询接口。

接口信息：
- Base URL：http://mes.company.com
- Path：/api/workorder/query
- 请求方式：POST
- Header：Content-Type=application/json，Authorization=Bearer {{MESToken}}
- Request Body：
  {
    "workOrderId": "{{WorkOrderID}}"
  }

响应示例：
{
  "code": 0,
  "data": {
    "productModel": "A100",
    "targetQty": 500,
    "planStartTime": "2026-06-01 08:00:00"
  }
}

映射关系：
- data.productModel -> CMS变量 ProductModel
- data.targetQty -> CMS变量 TargetQuantity
- data.planStartTime -> CMS变量 PlanStartTime

AI生成配置方案：

接口名称：MES工单查询
请求方法：POST
Base URL：http://mes.company.com
Path：/api/workorder/query

Header：
- Content-Type：application/json
- Authorization：Bearer {{MESToken}}

Body：
- workOrderId：绑定 CMS 变量 WorkOrderID

响应映射：
- $.data.productModel -> ProductModel
- $.data.targetQty -> TargetQuantity
- $.data.planStartTime -> PlanStartTime

预检结果：
- 请求结构校验通过
- Header 配置完整
- 响应字段解析通过

价值：

  • 无需手工拆解接口文档
  • 自动生成请求体和响应字段映射
  • 写入前可先调试，降低现场排错成本

场景二：ERP 多接口订单同步​

背景：生产线需要从 ERP 获取待生产订单，并在完工后回写生产结果。

接口资料：

ERP接口统一地址：http://erp.company.com/openapi

接口1：获取待生产订单
- Path：/orders/pending
- Method：GET
- Header：X-App-Key={{ERPAppKey}}，X-Sign={{ERPSign}}
- Query：lineCode={{LineCode}}

接口2：回写完工结果
- Path：/orders/complete
- Method：POST
- Header：X-App-Key={{ERPAppKey}}，X-Sign={{ERPSign}}
- Body：
  {
    "orderNo": "{{CurrentOrderNo}}",
    "completeQty": "{{CompleteQty}}",
    "finishTime": "{{FinishTime}}"
  }

AI解析结果：

检测到多接口配置。

公共配置：
- Base URL：http://erp.company.com/openapi
- 全局 Header：
  - X-App-Key：{{ERPAppKey}}
  - X-Sign：{{ERPSign}}

接口1：获取待生产订单
- Method：GET
- Path：/orders/pending
- Params：lineCode={{LineCode}}
- 建议映射：订单号、产品编码、计划数量、交期

接口2：回写完工结果
- Method：POST
- Path：/orders/complete
- Body：orderNo、completeQty、finishTime
- 建议校验：completeQty 必须为数字，finishTime 使用日期时间格式

价值：

  • 自动提取多接口共用 Base URL 和全局 Header
  • 避免重复配置认证信息
  • 统一管理订单获取与结果回写接口

场景三：接口调试失败排查​

背景：用户已配置接口，但调用失败，返回 401 或字段解析为空。

提问AI：

这个接口预检失败，请帮我排查。

失败信息：
- HTTP状态码：401
- 返回：{"message":"Unauthorized"}

当前配置：
- URL：http://cloud.company.com/api/device/status
- Method：GET
- Header：Content-Type=application/json
- Params：deviceId={{DeviceID}}

AI排查建议：

问题判断：
当前失败原因大概率是缺少认证 Header。

建议补充：
1. 确认接口是否需要 Authorization、X-Token、AppKey 或签名字段
2. 如果使用 Bearer Token，请补充：
   Authorization：Bearer {{CloudToken}}
3. 如果 Token 有有效期，请确认 CloudToken 变量是否已更新
4. 补充后重新执行预检调试

待确认问题：
- 该云平台接口的认证方式是什么？
- Token 是固定值，还是需要从其他接口动态获取？

价值：

  • 快速定位 Header 缺失、认证失败、字段路径错误等常见问题
  • 通过对话补齐缺失项
  • 减少现场反复试错

3.7.4、5分钟快速上手​

步骤1：打开API对接助手​

在 API 互联项或接口配置页面，点击 AI 助手入口，打开“API对接助手”。

image-20260601152036360

步骤2：输入或上传接口信息​

可以使用以下任一种方式：

  • 直接描述对接需求

  • 粘贴 cURL 报文

  • 粘贴 JSON Request Body 或响应示例

  • 输入接口请求参数说明

  • 上传接口文档附件

    image-20260601152127007

步骤3：等待AI解析​

AI 会识别接口数量、接口地址、请求方法、Header、Params、Body、响应字段等信息，并生成结构化配置方案。

步骤4：补充缺失项​

如果 AI 发现认证方式、必填参数、变量映射、响应示例等关键内容缺失，会在对话中主动提问。用户补充后，AI 会继续完善方案。

步骤5：一键写入配置​

确认方案无误后，AI 调用 CMS 的“新增 API 互联项”接口完成持久化。写入成功后，页面刷新并展示新增的 API 配置。

3.7.5、提问技巧（精准生成API对接配置）​

技巧一：优先提供完整 cURL​

cURL 通常包含 URL、请求方法、Header 和 Body，AI 可以直接解析出大部分配置。

示例：

curl -X POST "http://mes.company.com/api/workorder/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{MESToken}}" \
  -d '{"workOrderId":"{{WorkOrderID}}"}'

技巧二：明确接口输入和 CMS 变量来源​

说明哪些参数来自固定值，哪些参数来自 CMS 变量。

示例：

接口参数说明：
- lineCode 固定为 L2
- workOrderId 来自 CMS 变量 WorkOrderID
- token 来自 CMS 变量 MESToken
- requestTime 使用当前时间，格式 yyyy-MM-dd HH:mm:ss

技巧三：提供响应示例和映射目标​

没有响应示例时，AI 很难准确生成 Response -> CMS 变量映射。建议至少提供一份成功返回示例。

示例：

响应示例：
{
  "success": true,
  "data": {
    "temperature": 78.5,
    "pressure": 1.6,
    "status": "RUNNING"
  }
}

映射目标：
- data.temperature -> DeviceTemperature
- data.pressure -> DevicePressure
- data.status -> DeviceStatus

技巧四：多接口要说明公共配置​

多个接口属于同一个系统时，建议一次性说明公共 Base URL、全局 Header 和认证方式。

示例：

以下接口都属于 ERP 系统：
- Base URL：http://erp.company.com/openapi
- 全局 Header：X-App-Key={{ERPAppKey}}，X-Sign={{ERPSign}}
- 请求超时时间：10秒

接口包括：
1. GET /orders/pending：获取待生产订单
2. POST /orders/complete：回写完工结果
3. POST /orders/alarm：上报告警信息

3.7.6、提示词模板库​

模板1：单接口配置​

请帮我生成 API 对接配置。

接口信息：
- 接口名称：[接口名称]
- Base URL：[系统地址]
- Path：[接口路径]
- 请求方式：[GET/POST/PUT/DELETE]
- 认证方式：[Bearer Token/AppKey/签名/无]
- Header：[Header列表]
- Params：[Query参数列表]
- Body：[请求体JSON]

变量来源：
- [参数名] 来自 CMS 变量 [变量名]

响应示例：
[粘贴JSON响应]

响应映射：
- [响应字段路径] -> [CMS变量名]

请先生成配置方案并进行预检调试，确认后再写入配置。

模板2：接口文档解析​

我上传了一份接口文档，请帮我解析其中的接口配置。

重点解析：
1. 接口地址、请求方法、Base URL
2. Header、Params、Body
3. 鉴权方式
4. 成功响应示例
5. 可映射到 CMS 变量的字段

要求：
- 如果文档中缺少必填参数，请先向我提问
- 如果有多个接口，请按接口分组展示
- 先展示 Markdown 配置方案，不要直接写入

模板3：多接口配置​

请帮我配置一组第三方系统接口。

公共信息：
- 系统名称：[MES/ERP/WMS/云平台]
- Base URL：[公共地址]
- 全局 Header：[公共Header]
- 认证方式：[认证说明]

接口列表：
1. [接口1名称]
   - Method：[GET/POST/PUT/DELETE]
   - Path：[路径]
   - 参数：[参数说明]
   - 响应映射：[字段路径 -> CMS变量]

2. [接口2名称]
   - Method：[GET/POST/PUT/DELETE]
   - Path：[路径]
   - 参数：[参数说明]
   - 响应映射：[字段路径 -> CMS变量]

请自动提取复用配置，并分别生成每个接口的配置方案。

模板4：响应映射生成​

请根据以下响应示例生成 Response -> CMS 变量映射表。

响应示例：
[粘贴JSON]

业务含义：
- [字段说明]

目标变量：
- [CMS变量列表]

要求：
- 只映射业务需要的字段
- 数值字段保持数值类型
- 时间字段按 yyyy-MM-dd HH:mm:ss 处理
- 无法确定的映射请列为待确认项

3.7.7、常见问题​

Q1: AI生成的 API 配置可以直接用于生产环境吗？​

A: 不建议直接用于生产环境。正确流程：

  1. AI 生成初始配置方案
  2. 核对 URL、认证方式、Header、参数和响应映射
  3. 确认无误后再写入生产配置

Q2: 支持哪些输入方式和附件格式？​

A: 支持自然语言描述、cURL 报文、JSON 参数、接口请求参数说明和接口文档附件。

Q3: 接口信息不完整时怎么办？​

A: AI 会识别关键缺失项并主动追问。常见缺失项包括：

  • 认证方式或 Token 来源
  • 必填 Header
  • Query 参数或 Body 参数来源
  • 成功响应示例
  • 响应字段到 CMS 变量的映射关系

对于暂时无法确定的非关键映射，可以先留空，后续再补充。

Q4: 是否支持多个接口一起配置？​

A: 支持。AI 可以识别多接口配置，并自动提取复用的 Base URL 和全局 Header。建议同一系统的一组接口一起提供，例如“获取订单、回写结果、上报告警”。

Q5: API对接助手和AI脚本助手有什么区别？​

A: API对接助手主要用于生成和写入 API 互联项配置，适合标准 HTTP API 的请求参数、Header、Body、响应映射和预检调试。AI脚本助手主要用于生成 C# 脚本，适合复杂业务逻辑、条件判断、数据加工、批处理和自定义流程控制。

简单判断：

  • 标准接口配置、响应映射、预检调试：优先使用 API对接助手
  • 接口调用后还需要复杂计算、循环处理、异常分支或多系统编排：使用 AI脚本助手

3.7.8、最佳实践​

1. 优先提供真实响应示例​

响应示例越真实，字段映射越准确。建议提供成功响应和典型失败响应，方便 AI 同时生成正常解析和异常判断建议。

2. 认证信息要说明来源​

不要只写“需要 token”，要说明 Token 来自固定值、CMS 变量，还是需要通过另一个接口获取。涉及敏感信息时，建议使用变量占位，不要直接粘贴真实密钥。

推荐写法：
Authorization：Bearer {{MESToken}}
MESToken 来自 CMS 变量，由运维人员定期维护。

3. 先配置核心接口，再扩展接口组​

对新系统初次接入时，建议先选择一个最关键、最简单的接口完成配置和预检。确认认证方式、网络连通性和字段映射都稳定后，再扩展到多接口配置。

4. 映射字段要少而准​

不要把响应中的所有字段都映射到 CMS 变量。只映射页面展示、业务判断、报警或归档真正需要的字段，降低后期维护成本。

5. 写入前认真核对预检结果​

确认以下内容后再写入配置：

  • 请求方法是否正确
  • Base URL 和 Path 是否拼接正确
  • Header 和认证方式是否完整
  • Body 参数是否来自正确变量
  • 响应字段路径是否能解析到值
  • 调试结果是否符合预期

6. 建立接口配置模板​

将常用系统的 Base URL、认证方式、全局 Header、响应格式和字段映射规则沉淀为团队模板，后续项目可以复用，减少重复描述和试错。

3.7.9、下一步​

  • AI变量助手 - 接口响应需要写入 CMS 变量时，先学习变量创建与点表导入，准备清晰的变量基础。
  • AI脚本助手 - 当接口配置之外还需要复杂业务逻辑、数据加工或多系统编排时，继续学习脚本开发。
  • AI智能绑定 - 接口数据进入 CMS 后，学习如何把变量或数据表绑定到页面组件。
  • 使用技巧与最佳实践 - 系统学习接口提示词写法、跨助手协作流程和团队复用规范。