kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop_20260203
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-06-003-05-api.md

13 KiB
Raw Permalink Blame History

API 文档 - 删除操作

元数据

  • 需求编号：003-05
  • 创建时间：2026-02-06
  • 创建人：AI Assistant
  • 状态：已完成
  • 版本：v1.0.0

API 概述

本文档描述了 Salesforce Metadata API 删除操作相关的 REST API 接口，包括元数据删除、批量删除和删除历史查询功能。

核心功能

  1. 元数据删除：根据元数据类型和完整名称删除单个或多个元数据
  2. 批量删除：支持批量删除不同类型的元数据，自动分批处理（每批 10 个）
  3. 删除历史查询：查询删除操作的历史记录

技术栈

  • Spring Boot 2.7.x
  • Spring Security（权限控制）
  • MyBatis Plus（数据持久化）
  • Salesforce Metadata API

基础路径

/salesforce/metadata/delete

接口列表

接口 1：删除元数据

功能描述

根据元数据类型和完整名称列表删除元数据。支持一次删除多个同类型的元数据（最多 10 个，超过会自动分批处理）。

请求方式

POST

请求路径

/salesforce/metadata/delete/{type}

权限要求

  • 权限标识：salesforce:metadata:delete
  • 使用 @PreAuthorize("@ss.hasPermi('salesforce:metadata:delete')") 控制

请求参数

路径参数
参数名 类型 必填 说明 示例
type String 是 元数据类型 CustomObject、ApexClass、ApexTrigger
请求体参数
参数名 类型 必填 说明 示例
fullNames String[] 是 元数据完整名称列表 ["MyCustomObject__c", "AnotherObject__c"]

请求示例

POST /salesforce/metadata/delete/CustomObject
Content-Type: application/json

["MyCustomObject__c", "AnotherObject__c"]

响应参数

成功响应（HTTP 200）
参数名 类型 说明 示例
code Integer 状态码，200 表示成功 200
msg String 提示信息 "操作成功"
data Array 删除结果列表 见下方示例
删除结果对象（DeleteResultVo）
参数名 类型 说明 示例
fullName String 元数据完整名称 "MyCustomObject__c"
success Boolean 是否删除成功 true
errors Array 错误消息数组（失败时） ["Entity is not found"]

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "fullName": "MyCustomObject__c",
      "success": true,
      "errors": null
    },
    {
      "fullName": "AnotherObject__c",
      "success": false,
      "errors": ["Entity is not found"]
    }
  ]
}

失败响应示例

{
  "code": 500,
  "msg": "Salesforce 连接失败: Connection refused"
}

接口 2：批量删除元数据

功能描述

批量删除不同类型的元数据。支持一次提交多个删除请求，每个请求包含元数据类型和完整名称列表。系统会自动对每个请求进行分批处理（每批 10 个）。

请求方式

POST

请求路径

/salesforce/metadata/delete/batch

权限要求

  • 权限标识：salesforce:metadata:delete
  • 使用 @PreAuthorize("@ss.hasPermi('salesforce:metadata:delete')") 控制

请求参数

请求体参数（DeleteRequest 数组）
参数名 类型 必填 说明 示例
type String 是 元数据类型 CustomObject、ApexClass
fullNames String[] 是 元数据完整名称列表 ["Object1__c", "Object2__c"]

请求示例

POST /salesforce/metadata/delete/batch
Content-Type: application/json

[
  {
    "type": "CustomObject",
    "fullNames": ["MyCustomObject__c", "AnotherObject__c"]
  },
  {
    "type": "ApexClass",
    "fullNames": ["MyApexClass", "AnotherClass"]
  }
]

响应参数

成功响应（HTTP 200）
参数名 类型 说明 示例
code Integer 状态码，200 表示成功 200
msg String 提示信息 "批量删除完成，成功 3 个，失败 1 个"
data Object 批量删除结果 见下方示例
批量删除结果对象
参数名 类型 说明 示例
totalCount Integer 总删除数量 4
successCount Integer 成功数量 3
failureCount Integer 失败数量 1
results Array 详细删除结果列表 DeleteResultVo 数组

成功响应示例

{
  "code": 200,
  "msg": "批量删除完成，成功 3 个，失败 1 个",
  "data": {
    "totalCount": 4,
    "successCount": 3,
    "failureCount": 1,
    "results": [
      {
        "fullName": "MyCustomObject__c",
        "success": true,
        "errors": null
      },
      {
        "fullName": "AnotherObject__c",
        "success": false,
        "errors": ["Entity is not found"]
      },
      {
        "fullName": "MyApexClass",
        "success": true,
        "errors": null
      },
      {
        "fullName": "AnotherClass",
        "success": true,
        "errors": null
      }
    ]
  }
}

失败响应示例

{
  "code": 500,
  "msg": "批量删除失败: 参数校验失败"
}

接口 3：获取删除历史

功能描述

查询元数据删除操作的历史记录，支持限制返回数量。

请求方式

GET

请求路径

/salesforce/metadata/delete/history

权限要求

  • 权限标识：salesforce:metadata:delete:query
  • 使用 @PreAuthorize("@ss.hasPermi('salesforce:metadata:delete:query')") 控制

请求参数

查询参数
参数名 类型 必填 说明 默认值 范围
limit Integer 否 返回记录数量限制 10 1-100

请求示例

GET /salesforce/metadata/delete/history?limit=20

响应参数

成功响应（HTTP 200）
参数名 类型 说明 示例
code Integer 状态码，200 表示成功 200
msg String 提示信息 "操作成功"
data Array 删除历史记录列表 见下方示例
删除历史记录对象（DataiMetadataDelete）
参数名 类型 说明 示例
id Long 记录 ID 1
metadataType String 元数据类型 CustomObject
fullName String 元数据完整名称 MyCustomObject__c
success Integer 是否成功（0-否，1-是） 1
errorMessage String 错误消息（失败时） null
deleteTime Date 删除时间 2026-02-06 10:30:00
userId Long 操作用户 ID 1
createBy String 创建者 admin
createTime Date 创建时间 2026-02-06 10:30:00

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "metadataType": "CustomObject",
      "fullName": "MyCustomObject__c",
      "success": 1,
      "errorMessage": null,
      "deleteTime": "2026-02-06 10:30:00",
      "userId": 1,
      "createBy": "admin",
      "createTime": "2026-02-06 10:30:00"
    },
    {
      "id": 2,
      "metadataType": "ApexClass",
      "fullName": "MyApexClass",
      "success": 0,
      "errorMessage": "Entity is not found",
      "deleteTime": "2026-02-06 10:35:00",
      "userId": 1,
      "createBy": "admin",
      "createTime": "2026-02-06 10:35:00"
    }
  ]
}

失败响应示例

{
  "code": 500,
  "msg": "获取删除历史失败"
}

错误码

系统错误码

错误码 说明 场景
200 操作成功 请求处理成功
500 操作失败 服务器内部错误
401 未授权 用户未登录或 Token 过期
403 禁止访问 用户没有权限
404 资源不存在 请求的资源不存在

业务错误码

错误码 说明 场景 解决方案
DELETE_001 Salesforce 连接失败 连接 Salesforce 时发生异常 检查网络连接和 Salesforce 配置
DELETE_002 删除元数据失败 调用 Salesforce API 删除失败 检查元数据是否存在，查看错误详情
DELETE_003 批量删除失败 批量删除过程中发生错误 检查请求参数，查看具体错误信息
DELETE_004 参数校验失败 请求参数不符合要求 检查参数是否为空，格式是否正确

数据模型

DeleteRequest（删除请求）

@Data
@Schema(description = "删除请求")
public class DeleteRequest implements Serializable {
    private static final long serialVersionUID = 1L;

    @NotBlank(message = "元数据类型不能为空")
    @Schema(description = "元数据类型", required = true, example = "CustomObject")
    private String type;

    @NotEmpty(message = "元数据名称列表不能为空")
    @Schema(description = "元数据完整名称列表", required = true, example = "[\"MyCustomObject__c\", \"AnotherObject__c\"]")
    private String[] fullNames;
}

DeleteResultVo（删除结果）

@Data
@Schema(description = "删除结果")
public class DeleteResultVo implements Serializable {
    private static final long serialVersionUID = 1L;

    @Schema(description = "元数据完整名称", example = "MyCustomObject__c")
    private String fullName;

    @Schema(description = "是否删除成功", example = "true")
    private boolean success;

    @Schema(description = "错误消息数组", example = "[\"Entity is not found\"]")
    private String[] errors;
}

DataiMetadataDelete（删除历史实体）

@Data
public class DataiMetadataDelete implements Serializable {
    private static final long serialVersionUID = 1L;

    private Long id;
    private String metadataType;
    private String fullName;
    private Integer success;
    private String errorMessage;
    private Date deleteTime;
    private Long userId;
    private String createBy;
    private Date createTime;
    private String updateBy;
    private Date updateTime;
    private Integer delFlag;
}

调用示例

JavaScript 调用示例

单个删除

const response = await fetch('/salesforce/metadata/delete/CustomObject', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify(['MyCustomObject__c'])
});

const result = await response.json();
console.log(result);

批量删除

const response = await fetch('/salesforce/metadata/delete/batch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify([
    { type: 'CustomObject', fullNames: ['Object1__c', 'Object2__c'] },
    { type: 'ApexClass', fullNames: ['Class1', 'Class2'] }
  ])
});

const result = await response.json();
console.log(result);

查询历史

const response = await fetch('/salesforce/metadata/delete/history?limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ' + token
  }
});

const result = await response.json();
console.log(result);

Java 调用示例

单个删除

@RestController
public class DeleteExample {
    
    @Autowired
    private RestTemplate restTemplate;
    
    public void deleteMetadata() {
        String url = "http://localhost:8080/salesforce/metadata/delete/CustomObject";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.setBearerAuth(token);
        
        String[] fullNames = {"MyCustomObject__c"};
        HttpEntity<String[]> entity = new HttpEntity<>(fullNames, headers);
        
        ResponseEntity<AjaxResult> response = restTemplate.exchange(
            url, HttpMethod.POST, entity, AjaxResult.class);
        
        System.out.println(response.getBody());
    }
}

注意事项

1. 权限控制

  • 所有接口都需要有效的 JWT Token
  • 删除操作需要 salesforce:metadata:delete 权限
  • 历史查询需要 salesforce:metadata:delete:query 权限

2. 分批处理

  • Salesforce Metadata API 每次最多删除 10 个元数据
  • 系统会自动对超过 10 个的请求进行分批处理
  • 分批处理是串行执行，单个失败不影响其他批次

3. 异步日志

  • 删除操作的历史记录是异步写入数据库的
  • 可能会有短暂的延迟（通常 < 1 秒）
  • 不影响主业务流程的响应时间

4. 错误处理

  • 建议客户端对所有可能的错误码进行处理
  • 对于批量删除，建议检查每个结果的 success 字段
  • 对于失败的删除，可以根据 errors 字段进行针对性处理

5. 性能考虑

  • 批量删除时，如果数量很大，可能需要较长时间
  • 建议客户端设置合理的超时时间（如 60 秒）
  • 对于超大量删除，建议分批调用接口

相关文档