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

269 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API操作接口
## 基本配置
| 字段 | 值 | 说明 |
|------|-----|------|
| type | 3 | API操作 |
| method | 1=GET, 2=POST | 请求方法 |
| url | API路径 | 完整或相对路径 |
| hasPage | 0/1 | 是否分页 |
| isPostPosition | 0/1 | 是否鉴权 |
## 请求配置 (apiData)
```json
{
"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分页结构
```json
{
"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:获取订单商品
```json
{
"apiData": {
"method": 1,
"url": "/api/extend/CrmOrder/Goods",
"header": [],
"query": [{"field": "keyword", "defaultValue": "", "source": "1"}],
"body": "",
"bodyType": 0
}
}
```
### 示例2:POST添加公告
```json
{
"apiData": {
"method": 2,
"url": "/api/message/Notice",
"header": [],
"query": [],
"body": "{\"text\": \"{text}\", \"body\": \"{body}\", \"excerpt\": \"{excerpt}\"}",
"bodyType": 3
}
}
```
- bodyType=3 表示JSON格式
- body中使用`{参数名}`占位符
### AIBridge 调用 POST 接口
```python
# 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真分页
```json
{
"apiData": {
"method": 1,
"url": "/api/system/DataInterface?sort=desc",
"query": []
}
}
```
## 内部API调用
当URL以`/`开头且不以`http`开头时,自动添加apiDomain前缀
```java
// 后端处理逻辑
if (StringUtil.isNotEmpty(path.toString()) && path.toString().startsWith("/")) {
path.insert(0, configValueUtil.getApiDomain());
// 自动附加token
token = UserProvider.getUser().getToken();
}
```
## 外部API调用
完整URL以`http`开头,直接调用
```json
{
"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次**。
### 示例:检查响应状态码
```javascript
var result = responseObj;
if (result && result.code === 200) {
return true; // 状态正常,继续
}
return false; // 状态异常,重试
```
### 示例:检查业务错误码
```javascript
var result = responseObj;
if (result && result.data && result.data.success === true) {
return true;
}
return false; // 业务处理失败,重试
```
## 数据处理(dataJsJson)
所有类型接口(SQL/静态/API)都支持数据处理脚本,在最终返回前执行。
| 字段 | 说明 |
|------|------|
| dataJsJson | JS脚本,对结果进行二次处理后返回 |
### 示例:添加计算字段
```javascript
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;
```
### 示例:过滤空数据
```javascript
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创建
```python
# 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)
```