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

API 文档 - Tooling 连接管理

元数据

• 需求编号: 004-01
• 子需求名称: 连接管理
• 版本号: v1.0.0
• 创建时间: 2026-02-05
• 创建人: AI Assistant
• 状态: 已完成

API 概述

Tooling 连接管理 API 提供对 Salesforce Tooling API 连接的管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部等。这些 API 是 Tooling API 模块的基础组件，为后续元数据操作、开发工具功能等提供连接管理能力。

基础信息

• 基础路径: /salesforce/tooling/connection
• 认证方式: JWT Token + 权限校验
• Content-Type: application/json
• API 版本: v1.0.0

权限要求

所有接口都需要以下权限：

• tooling:connection:get - 获取连接
• tooling:connection:clear - 清除缓存
• tooling:connection:test - 测试连接
• tooling:connection:callOptions - 设置调用选项
• tooling:connection:debuggingHeader - 设置调试头部

接口列表

1. 获取连接

接口说明

获取 Tooling API 连接。如果缓存中没有有效连接，则创建新连接并缓存。连接创建时会验证 Session 有效性。

请求信息

• 请求方式: GET
• 请求路径: /salesforce/tooling/connection/get
• 权限要求: tooling:connection:get

请求参数

无

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	连接结果对象
data.success	Boolean	是否成功
data.valid	Boolean	连接是否有效
data.testTime	String	测试时间（格式：yyyy-MM-dd HH:mm:ss）
data.responseTime	Long	响应时间（毫秒）
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误消息（失败时返回）

成功示例

{
  "code": 200,
  "msg": "获取连接成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-05 14:30:25",
    "responseTime": 156
  }
}

失败示例

{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "valid": false,
    "errorCode": "TOOLING_CONN_006",
    "errorMessage": "用户未登录或会话已过期"
  }
}

错误码

• TOOLING_CONN_001: Session 无效或已过期
• TOOLING_CONN_002: 连接创建失败
• TOOLING_CONN_006: 用户未登录或会话已过期

---

2. 清除连接缓存

接口说明

清除缓存的 Tooling API 连接。下次获取连接时将创建新连接。

请求信息

• 请求方式: DELETE
• 请求路径: /salesforce/tooling/connection/clear
• 权限要求: tooling:connection:clear

请求参数

无

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	无数据返回

成功示例

{
  "code": 200,
  "msg": "清除连接缓存成功",
  "data": null
}

失败示例

{
  "code": 500,
  "msg": "清除连接缓存失败: 清除缓存时发生错误",
  "data": null
}

错误码

• TOOLING_CONN_003: 网络超时
• TOOLING_CONN_008: 未知错误

---

3. 测试连接

接口说明

测试 Tooling API 连接是否有效。通过执行简单的 SOQL 查询来验证连接。

请求信息

• 请求方式: GET
• 请求路径: /salesforce/tooling/connection/test
• 权限要求: tooling:connection:test

请求参数

无

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	测试结果对象
data.success	Boolean	是否成功
data.valid	Boolean	连接是否有效
data.testTime	String	测试时间（格式：yyyy-MM-dd HH:mm:ss）
data.responseTime	Long	响应时间（毫秒）
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误消息（失败时返回）

成功示例

{
  "code": 200,
  "msg": "测试连接成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-05 14:30:25",
    "responseTime": 234
  }
}

失败示例

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

错误码

• TOOLING_CONN_001: Session 无效或已过期
• TOOLING_CONN_002: 连接创建失败
• TOOLING_CONN_003: 网络超时

---

4. 设置调用选项

接口说明

设置 Tooling API 连接的调用选项，如客户端名称等。

请求信息

• 请求方式: POST
• 请求路径: /salesforce/tooling/connection/call-options
• 权限要求: tooling:connection:callOptions
• Content-Type: application/json

请求参数

参数名	类型	必填	说明
client	String	否	客户端名称，用于标识调用来源
defaultNamespace	String	否	默认命名空间
clientId	String	否	客户端 ID

请求示例

{
  "client": "DataI-Tooling-Client",
  "defaultNamespace": "",
  "clientId": "datai-tooling-001"
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	设置结果对象
data.success	Boolean	是否成功
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误消息（失败时返回）

成功示例

{
  "code": 200,
  "msg": "设置调用选项成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "errorCode": "TOOLING_CONN_007",
    "errorMessage": "设置调用选项失败"
  }
}

错误码

• TOOLING_CONN_007: 设置调用选项失败

---

5. 设置调试头部

接口说明

设置 Tooling API 连接的调试头部，用于控制调试信息的输出级别。

请求信息

• 请求方式: POST
• 请求路径: /salesforce/tooling/connection/debugging-header
• 权限要求: tooling:connection:debuggingHeader
• Content-Type: application/json

请求参数

参数名	类型	必填	说明
debugLevel	String	是	调试级别，可选值：NONE、DEBUG_ONLY、DB、PROFILING、CALLOUT、DETAIL
categories	Array	否	调试类别列表

调试级别说明

级别	说明
NONE	不输出调试信息
DEBUG_ONLY	仅输出调试日志
DB	输出数据库操作信息
PROFILING	输出性能分析信息
CALLOUT	输出外部调用信息
DETAIL	输出详细信息

请求示例

{
  "debugLevel": "DEBUG_ONLY",
  "categories": ["Apex", "Visualforce"]
}

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	设置结果对象
data.success	Boolean	是否成功
data.errorCode	String	错误码（失败时返回）
data.errorMessage	String	错误消息（失败时返回）

成功示例

{
  "code": 200,
  "msg": "设置调试头部成功",
  "data": {
    "success": true
  }
}

失败示例

{
  "code": 500,
  "msg": "操作失败",
  "data": {
    "success": false,
    "errorCode": "TOOLING_CONN_008",
    "errorMessage": "设置调试头部失败"
  }
}

错误码

• TOOLING_CONN_008: 设置调试头部失败

---

错误码汇总

错误码	错误消息	说明
TOOLING_CONN_001	Session 无效或已过期	Session 已过期或无效，需要重新登录
TOOLING_CONN_002	连接创建失败	创建 ToolingConnection 时发生错误
TOOLING_CONN_003	网络超时	连接 Salesforce API 超时
TOOLING_CONN_004	权限不足	当前用户没有执行该操作的权限
TOOLING_CONN_005	API 版本不支持	当前 API 版本不支持该操作
TOOLING_CONN_006	用户未登录	用户未登录或会话已过期
TOOLING_CONN_007	设置调用选项失败	设置调用选项时发生错误
TOOLING_CONN_008	设置调试头部失败	设置调试头部时发生错误

接口调用场景

场景 1: 初始化连接

在需要使用 Tooling API 之前，先调用"获取连接"接口确保连接可用。

1. 调用 GET /salesforce/tooling/connection/get
2. 如果返回成功，连接已准备好
3. 如果返回失败（如 Session 过期），需要先登录

场景 2: 定期测试连接

可以定期调用"测试连接"接口检查连接状态，及时发现连接问题。

1. 定时调用 GET /salesforce/tooling/connection/test
2. 如果返回失败，调用 GET /salesforce/tooling/connection/get 重新获取连接

场景 3: 切换环境

在需要切换到不同的 Salesforce 环境时，先清除缓存再获取新连接。

1. 调用 DELETE /salesforce/tooling/connection/clear 清除缓存
2. 调用 GET /salesforce/tooling/connection/get 获取新连接

场景 4: 调试问题

在排查问题时，可以设置调试头部获取更多调试信息。

1. 调用 POST /salesforce/tooling/connection/debugging-header 设置调试级别为 DETAIL
2. 执行需要调试的操作
3. 查看调试日志
4. 调用 POST /salesforce/tooling/connection/debugging-header 恢复调试级别为 NONE

注意事项

1. 连接缓存: 连接会被缓存以提高性能，但在 Session 过期或需要切换环境时需要清除缓存。

2. Session 有效性: 获取连接时会自动验证 Session 有效性，如果 Session 过期会返回错误。

3. 线程安全: 连接缓存使用 ConcurrentHashMap 实现，线程安全。

4. 异常处理: 所有接口都遵循统一的异常处理规范，返回标准的 AjaxResult 格式。

5. 权限控制: 所有接口都需要相应的权限，确保安全性。

相关文档

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