datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-05-004-02-api.md

API 文档

元数据

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

API 概述

本文档描述了 Tooling API 元数据操作功能的 REST API 接口，包括元数据的创建、查询、更新、删除操作，以及操作日志的查询功能。

核心功能

• 创建元数据：支持创建 CustomObject、CustomField、ApexClass、ApexTrigger、Flow
• 查询元数据：支持通用 SOQL 查询，使用 SoqlBuilder 动态构建查询语句
• 更新元数据：支持通用元数据更新操作
• 删除元数据：支持通用元数据删除操作
• 操作日志查询：支持查询元数据操作日志

技术架构

• Controller：ToolingMetadataController - 处理 HTTP 请求和响应
• Service：ToolingMetadataServiceImpl - 实现业务逻辑
• Factory：ToolingConnectionFactory - 管理 Tooling API 连接
• 异步日志：使用 Spring @Async 异步记录操作日志

基础信息

• 基础路径：/salesforce/tooling/metadata
• 认证方式：Bearer Token（JWT）
• 权限控制：@PreAuthorize("@ss.hasLogin()")
• 数据格式：JSON

接口列表

1. 创建自定义对象

接口信息

• 接口名称：创建自定义对象
• 请求方式：POST
• 请求路径：/salesforce/tooling/metadata/custom-object
• 功能描述：通过 Tooling API 创建 Salesforce 自定义对象

请求参数

请求体（Body）：

参数名	类型	必填	说明
customObject	Object	是	自定义对象定义
customObject.fullName	String	是	对象 API 名称（如 MyCustomObject__c）
customObject.label	String	是	对象标签
customObject.pluralLabel	String	是	对象复数标签
customObject.description	String	否	对象描述
customObject.sharingModel	String	否	共享模式（ReadWrite/Read/Private）

请求示例：

{
  "fullName": "MyCustomObject__c",
  "label": "My Custom Object",
  "pluralLabel": "My Custom Objects",
  "description": "Custom object for testing",
  "sharingModel": "ReadWrite"
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功
data.id	String	创建的对象 ID
data.metadataName	String	元数据名称
data.operationTime	String	操作时间（yyyy-MM-dd HH:mm:ss）
data.errorCode	String	错误码（失败时）
data.errorMessage	String	错误消息（失败时）

成功响应示例：

{
  "code": 200,
  "msg": "创建自定义对象成功",
  "data": {
    "success": true,
    "id": "a01xx0000000001AAA",
    "metadataName": "MyCustomObject__c",
    "operationTime": "2026-02-05 10:00:00"
  }
}

失败响应示例：

{
  "code": 500,
  "msg": "创建自定义对象失败",
  "data": {
    "success": false,
    "metadataName": "MyCustomObject__c",
    "operationTime": "2026-02-05 10:00:00",
    "errorCode": "TOOLING_META_003",
    "errorMessage": "元数据已存在"
  }
}

---

2. 创建自定义字段

接口信息

• 接口名称：创建自定义字段
• 请求方式：POST
• 请求路径：/salesforce/tooling/metadata/custom-field
• 功能描述：在指定对象上创建自定义字段

请求参数

请求体（Body）：

参数名	类型	必填	说明
customField	Object	是	自定义字段定义
customField.fullName	String	是	字段 API 名称（如 MyField__c）
customField.label	String	是	字段标签
customField.type	String	是	字段类型（Text/Number/Date/DateTime/Checkbox 等）
customField.length	Integer	否	字段长度（Text 类型时必填）
objectType	String	是	对象类型（如 MyCustomObject__c）

请求示例：

{
  "customField": {
    "fullName": "MyField__c",
    "label": "My Field",
    "type": "Text",
    "length": 255
  },
  "objectType": "MyCustomObject__c"
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	响应数据
data.success	Boolean	是否成功
data.id	String	创建的字段 ID
data.metadataName	String	元数据名称
data.operationTime	String	操作时间
data.errorCode	String	错误码（失败时）
data.errorMessage	String	错误消息（失败时）

成功响应示例：

{
  "code": 200,
  "msg": "创建自定义字段成功",
  "data": {
    "success": true,
    "id": "a02xx0000000001AAA",
    "metadataName": "MyCustomObject__c.MyField__c",
    "operationTime": "2026-02-05 10:00:00"
  }
}

---

3. 创建 Apex 类

接口信息

• 接口名称：创建 Apex 类
• 请求方式：POST
• 请求路径：/salesforce/tooling/metadata/apex-class
• 功能描述：创建新的 Apex 类定义

请求参数

请求体（Body）：

参数名	类型	必填	说明
apexClass	Object	是	Apex 类定义
apexClass.name	String	是	类名
apexClass.body	String	是	类代码内容
apexClass.apiVersion	Double	否	API 版本（默认 58.0）
apexClass.status	String	否	状态（Active/Inactive，默认 Active）

请求示例：

{
  "apexClass": {
    "name": "MyClass",
    "body": "public class MyClass {\n    public void hello() {\n        System.debug('Hello World');\n    }\n}",
    "apiVersion": 58.0,
    "status": "Active"
  }
}

响应参数

成功响应示例：

{
  "code": 200,
  "msg": "创建 Apex 类成功",
  "data": {
    "success": true,
    "id": "01pxx0000000001AAA",
    "metadataName": "MyClass",
    "operationTime": "2026-02-05 10:00:00"
  }
}

---

4. 创建 Apex 触发器

接口信息

• 接口名称：创建 Apex 触发器
• 请求方式：POST
• 请求路径：/salesforce/tooling/metadata/apex-trigger
• 功能描述：创建新的 Apex 触发器

请求参数

请求体（Body）：

参数名	类型	必填	说明
apexTrigger	Object	是	Apex 触发器定义
apexTrigger.name	String	是	触发器名称
apexTrigger.body	String	是	触发器代码内容
apexTrigger.tableEnumOrId	String	是	关联对象（如 Account）
apexTrigger.apiVersion	Double	否	API 版本（默认 58.0）

请求示例：

{
  "apexTrigger": {
    "name": "MyTrigger",
    "body": "trigger MyTrigger on Account (before insert) {\n    System.debug('Account created');\n}",
    "tableEnumOrId": "Account",
    "apiVersion": 58.0
  }
}

响应参数

成功响应示例：

{
  "code": 200,
  "msg": "创建 Apex 触发器成功",
  "data": {
    "success": true,
    "id": "01qxx0000000001AAA",
    "metadataName": "MyTrigger",
    "operationTime": "2026-02-05 10:00:00"
  }
}

---

5. 创建 Flow

接口信息

• 接口名称：创建 Flow
• 请求方式：POST
• 请求路径：/salesforce/tooling/metadata/flow
• 功能描述：创建新的 Flow 定义

请求参数

请求体（Body）：

参数名	类型	必填	说明
flow	Object	是	Flow 定义
flow.fullName	String	是	Flow API 名称
flow.label	String	是	Flow 标签
flow.description	String	否	Flow 描述
flow.apiVersion	Double	否	API 版本（默认 58.0）

请求示例：

{
  "flow": {
    "fullName": "MyFlow",
    "label": "My Flow",
    "description": "Flow for testing",
    "apiVersion": 58.0
  }
}

响应参数

成功响应示例：

{
  "code": 200,
  "msg": "创建 Flow 成功",
  "data": {
    "success": true,
    "id": "300xx0000000001AAA",
    "metadataName": "MyFlow",
    "operationTime": "2026-02-05 10:00:00"
  }
}

---

6. 查询元数据

接口信息

• 接口名称：查询元数据
• 请求方式：GET
• 请求路径：/salesforce/tooling/metadata/query
• 功能描述：使用 SOQL 查询元数据

请求参数

查询参数（Query）：

参数名	类型	必填	说明
objectType	String	是	对象类型（如 ApexClass、CustomObject 等）
fields	String	是	查询字段（逗号分隔，如 Id,Name,ApiVersion）
whereClause	String	否	WHERE 条件（如 Name='MyClass'）
limit	Integer	否	查询限制（默认 100，最大 2000）

请求示例：

GET /salesforce/tooling/metadata/query?objectType=ApexClass&fields=Id,Name,ApiVersion,Status&limit=10 HTTP/1.1
Host: localhost:8080
Authorization: Bearer {token}

响应参数

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Object	响应数据
data.total	Integer	总记录数
data.records	Array	记录列表
data.queryTime	String	查询时间
data.errorCode	String	错误码（失败时）
data.errorMessage	String	错误消息（失败时）

成功响应示例：

{
  "code": 200,
  "msg": "查询元数据成功",
  "data": {
    "total": 100,
    "records": [
      {
        "id": "01pxx0000000001AAA",
        "name": "MyClass",
        "apiVersion": 58.0,
        "status": "Active"
      }
    ],
    "queryTime": "2026-02-05 10:00:00"
  }
}

---

7. 更新元数据

接口信息

• 接口名称：更新元数据
• 请求方式：PUT
• 请求路径：/salesforce/tooling/metadata/update
• 功能描述：更新指定的元数据记录

请求参数

请求体（Body）：

参数名	类型	必填	说明
sObject	Object	是	元数据对象
sObject.id	String	是	记录 ID
sObject.attributes	Object	是	对象属性
sObject.attributes.type	String	是	对象类型（如 ApexClass）
...	...	...	其他字段根据对象类型而定

请求示例：

{
  "sObject": {
    "id": "01pxx0000000001AAA",
    "attributes": {
      "type": "ApexClass"
    },
    "name": "MyClassUpdated",
    "body": "public class MyClassUpdated {\n    public void hello() {\n        System.debug('Hello World Updated');\n    }\n}",
    "apiVersion": 58.0,
    "status": "Active"
  }
}

响应参数

成功响应示例：

{
  "code": 200,
  "msg": "更新元数据成功",
  "data": {
    "success": true,
    "id": "01pxx0000000001AAA",
    "operationTime": "2026-02-05 10:00:00"
  }
}

---

8. 删除元数据

接口信息

• 接口名称：删除元数据
• 请求方式：DELETE
• 请求路径：/salesforce/tooling/metadata/delete
• 功能描述：删除指定的元数据记录

请求参数

查询参数（Query）：

参数名	类型	必填	说明
id	String	是	记录 ID
objectType	String	是	对象类型（如 ApexClass）

请求示例：

DELETE /salesforce/tooling/metadata/delete?id=01pxx0000000001AAA&objectType=ApexClass HTTP/1.1
Host: localhost:8080
Authorization: Bearer {token}

响应参数

成功响应示例：

{
  "code": 200,
  "msg": "删除元数据成功",
  "data": {
    "success": true,
    "id": "01pxx0000000001AAA",
    "operationTime": "2026-02-05 10:00:00"
  }
}

---

9. 获取元数据操作日志

接口信息

• 接口名称：获取元数据操作日志
• 请求方式：GET
• 请求路径：/salesforce/tooling/metadata/logs
• 功能描述：查询元数据操作日志

请求参数

查询参数（Query）：

参数名	类型	必填	说明
operationType	String	否	操作类型（create/update/delete/query）
metadataType	String	否	元数据类型（如 ApexClass）
status	String	否	操作状态（success/failed）
startTime	String	否	开始时间（yyyy-MM-dd HH:mm:ss）
endTime	String	否	结束时间（yyyy-MM-dd HH:mm:ss）
pageNum	Integer	否	页码（默认 1）
pageSize	Integer	否	每页大小（默认 10，最大 100）

请求示例：

GET /salesforce/tooling/metadata/logs?operationType=create&startTime=2026-02-05%2000:00:00&endTime=2026-02-05%2023:59:59&pageNum=1&pageSize=10 HTTP/1.1
Host: localhost:8080
Authorization: Bearer {token}

响应参数

参数名	类型	说明
code	Integer	状态码
msg	String	提示信息
data	Object	响应数据
data.total	Integer	总记录数
data.pageNum	Integer	当前页码
data.pageSize	Integer	每页大小
data.list	Array	日志列表
data.list[].id	Long	日志 ID
data.list[].operationType	String	操作类型
data.list[].metadataType	String	元数据类型
data.list[].metadataId	String	元数据 ID
data.list[].metadataName	String	元数据名称
data.list[].status	String	操作状态
data.list[].operationTime	String	操作时间
data.list[].userId	String	用户 ID

成功响应示例：

{
  "code": 200,
  "msg": "查询元数据操作日志成功",
  "data": {
    "total": 100,
    "pageNum": 1,
    "pageSize": 10,
    "list": [
      {
        "id": 1,
        "operationType": "create",
        "metadataType": "ApexClass",
        "metadataId": "01pxx0000000001AAA",
        "metadataName": "MyClass",
        "status": "success",
        "operationTime": "2026-02-05 10:00:00",
        "userId": "user001"
      }
    ]
  }
}

---

错误码

错误码列表

错误码	错误消息	说明
TOOLING_META_001	Session 无效或已过期	Session ID 无效或已过期，需要重新登录
TOOLING_META_002	创建元数据失败	创建元数据失败
TOOLING_META_003	查询元数据失败	查询元数据失败
TOOLING_META_004	更新元数据失败	更新元数据失败
TOOLING_META_005	删除元数据失败	删除元数据失败
TOOLING_META_006	权限不足	当前用户没有访问该元数据的权限
TOOLING_META_007	元数据验证失败	元数据验证失败
TOOLING_META_008	用户未登录	用户未登录或 Session 已过期
TOOLING_META_009	元数据类型不支持	不支持的元数据类型
TOOLING_META_010	元数据已存在	元数据已存在
TOOLING_META_011	元数据不存在	元数据不存在

错误响应格式

{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "errorCode": "TOOLING_META_001",
    "errorMessage": "Session 无效或已过期"
  }
}

---

数据类型说明

元数据类型（MetadataType）

类型	说明
CustomObject	自定义对象
CustomField	自定义字段
CustomIndex	自定义索引
ApexClass	Apex 类
ApexTrigger	Apex 触发器
ApexPage	Visualforce 页面
ApexComponent	Visualforce 组件
Flow	Flow 定义
FlowDefinition	Flow 定义（新版）
FlowVersion	Flow 版本
FlowTestCoverage	Flow 测试覆盖率

操作类型（OperationType）

类型	说明
create	创建操作
update	更新操作
delete	删除操作
query	查询操作

操作状态（Status）

状态	说明
success	成功
failed	失败

---

相关文档

• 需求文档
• 设计文档
• 决策文档
• SQL 脚本
• 提示词文档
• 变更日志
• 复盘文档
• 会话记录