Files
aibridge/docs/datainterface/04-api-operation.md
T
2026-05-18 09:28:15 +08:00

5.7 KiB
Raw Blame History

API操作接口

基本配置

字段 值 说明
type 3 API操作
method 1=GET, 2=POST 请求方法
url API路径 完整或相对路径
hasPage 0/1 是否分页
isPostPosition 0/1 是否鉴权

请求配置 (apiData)

{
  "method": 1,
  "url": "/api/extend/CrmOrder/Goods",
  "header": [
    {"field": "Authorization", "defaultValue": "", "source": "1"}
  ],
  "query": [
    {"field": "keyword", "defaultValue": "", "source": "1"}
  ],
  "body": "",
  "bodyType": 0
}

header/query source类型

source 说明
1 字段:使用defaultValue
2 自定义:从变量获取
3 空值:固定空字符串

bodyType 类型

值 说明
0 none
1 form-data
2 x-www-form-urlencoded
3 json
4 xml

分页API配置

hasPage=1时,需要配置:

  1. 数据配置:获取分页数据
  2. 数量统计:返回总数

API分页结构

{
  "dataConfigJson": {
    "apiData": {
      "url": "/api/list?page={currentPage}&size={pageSize}",
      "method": 1
    }
  }
}

参考示例

ID 名称 特征
360711881444294853 获取订单商品接口 GET, 1个参数
395538362724780101 访问jnpf接口认证示例 内部API调用
398826053293854213 系统菜单接口(示例) 多参数
469125039078305029 API真分页 hasPage=1
469471490920740869 添加公告接口 POST

示例1:获取订单商品

{
  "apiData": {
    "method": 1,
    "url": "/api/extend/CrmOrder/Goods",
    "header": [],
    "query": [{"field": "keyword", "defaultValue": "", "source": "1"}],
    "body": "",
    "bodyType": 0
  }
}

示例2:POST添加公告

{
  "apiData": {
    "method": 2,
    "url": "/api/message/Notice",
    "header": [],
    "query": [],
    "body": "{\"text\": \"{text}\", \"body\": \"{body}\", \"excerpt\": \"{excerpt}\"}",
    "bodyType": 3
  }
}
  • bodyType=3 表示JSON格式
  • body中使用{参数名}占位符

AIBridge 调用 POST 接口

# POST 接口调用(必填参数需要有 defaultValue 或使用 sourceType=3)
result = di.preview('469471490920740869', {
    'paramList': [
        {'field': 'text', 'defaultValue': '标题', 'dataType': 'varchar', 'sourceType': 3},
        {'field': 'body', 'defaultValue': '内容', 'dataType': 'varchar', 'sourceType': 3},
        {'field': 'excerpt', 'defaultValue': '', 'dataType': 'varchar', 'sourceType': 3},
    ]
})

注意:如果 DI 中参数配置了 required=1 但 defaultValue=null,调用时会失败。建议在创建 DI 时给必填参数设置 defaultValue。

示例3:API真分页

{
  "apiData": {
    "method": 1,
    "url": "/api/system/DataInterface?sort=desc",
    "query": []
  }
}

内部API调用

当URL以/开头且不以http开头时,自动添加apiDomain前缀

// 后端处理逻辑
if (StringUtil.isNotEmpty(path.toString()) && path.toString().startsWith("/")) {
    path.insert(0, configValueUtil.getApiDomain());
    // 自动附加token
    token = UserProvider.getUser().getToken();
}

外部API调用

完整URL以http开头,直接调用

{
  "apiData": {
    "url": "https://api.example.com/data",
    "method": 1
  }
}

异常验证(dataExceptionJson)

仅 type=3(API操作)接口支持异常验证脚本。

字段 说明
dataExceptionJson JS脚本,返回 true 继续处理,false 重新调用API(重试机制)

错误码

错误码 含义
SYS121 HTTP调用失败(连接超时、响应错误等)
SYS122 API返回结果为空
SYS123 JS脚本执行异常

执行时机

HTTP调用完成 → dataExceptionJson验证 → dataJsJson处理 → 返回结果

当JS返回 false 时,后端会重新调用HTTP接口,最多重试3次。

示例:检查响应状态码

var result = responseObj;
if (result && result.code === 200) {
    return true;  // 状态正常,继续
}
return false;  // 状态异常,重试

示例:检查业务错误码

var result = responseObj;
if (result && result.data && result.data.success === true) {
    return true;
}
return false;  // 业务处理失败,重试

数据处理(dataJsJson)

所有类型接口(SQL/静态/API)都支持数据处理脚本,在最终返回前执行。

字段 说明
dataJsJson JS脚本,对结果进行二次处理后返回

示例:添加计算字段

var list = data;
for (var i = 0; i < list.length; i++) {
    list[i].fullName = list[i].f_real_name + ' (' + list[i].f_account + ')';
}
return list;

示例:过滤空数据

var list = data;
var filtered = [];
for (var i = 0; i < list.length; i++) {
    if (list[i].f_real_name && list[i].f_real_name.length > 0) {
        filtered.push(list[i]);
    }
}
return filtered;

AIBridge创建

# API操作
payload = {
    "fullName": "获取订单",
    "enCode": "get_order",
    "type": 3,
    "dataConfigJson": json.dumps({
        "staticData": "",
        "sqlData": {"dbLinkId": "", "sql": ""},
        "apiData": {
            "method": 1,
            "url": "/api/extend/CrmOrder/Goods",
            "header": [],
            "query": [{"field": "keyword", "defaultValue": "", "source": "1"}],
            "body": "",
            "bodyType": 0
        }
    }),
    "parameterJson": json.dumps([{
        "field": "keyword",
        "fieldName": "关键词",
        "dataType": "varchar",
        "required": 0,
        "sourceType": 1,
        "defaultValue": ""
    }])
}

di.create(payload)