269 lines
5.7 KiB
Markdown
269 lines
5.7 KiB
Markdown
# 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)
|
||
```
|