kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
27ce31edd3
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-03-004-01-api.md

12 KiB
Raw Blame History

API 文档

元数据

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

API 概述

功能描述

Tooling API 连接管理模块提供 Salesforce Tooling API 的连接管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部等核心功能。

基础信息

  • 基础路径：/salesforce/tooling/connection
  • 协议：HTTPS
  • 数据格式：JSON
  • 字符编码：UTF-8

认证方式

  • 使用 JWT Token 进行身份认证
  • Token 通过登录接口获取
  • 需要在请求头中携带 Authorization: Bearer {token}

权限控制

  • 使用 Spring Security 进行权限控制
  • 每个接口都有对应的权限标识
  • 权限格式：tooling:connection:{操作}

接口列表

1. 获取连接

接口说明

获取 Tooling API 连接，如果缓存中没有有效连接，则创建新连接。

请求信息

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

请求参数

无

响应参数

成功响应（HTTP 200）
参数名 类型 说明
code Integer 状态码（200 表示成功）
msg String 提示信息
data Object 连接结果对象
data.success Boolean 是否成功
data.connectionId String 连接 ID
data.sessionId String Session ID（脱敏处理）
data.instanceUrl String Salesforce 实例 URL
data.connectionTime String 连接时间（格式：yyyy-MM-dd HH:mm:ss）
data.client String 客户端名称
data.debugLevel String 调试级别
失败响应（HTTP 200，业务错误）
参数名 类型 说明
code Integer 状态码（非 200 表示失败）
msg String 错误信息

成功示例

{
  "code": 200,
  "msg": "获取连接成功",
  "data": {
    "success": true,
    "connectionId": "conn_1234567890",
    "sessionId": "00D...",
    "instanceUrl": "https://xxxxx.my.salesforce.com",
    "connectionTime": "2026-02-03 10:30:00",
    "client": "DataiToolingClient",
    "debugLevel": "DEBUG"
  }
}

失败示例

{
  "code": 500,
  "msg": "获取连接失败: Session 无效或已过期"
}

错误码

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

2. 清除连接缓存

接口说明

清除缓存的 Tooling API 连接。

请求信息

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

请求参数

无

响应参数

成功响应（HTTP 200）
参数名 类型 说明
code Integer 状态码（200 表示成功）
msg String 提示信息
失败响应（HTTP 200，业务错误）
参数名 类型 说明
code Integer 状态码（非 200 表示失败）
msg String 错误信息

成功示例

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

失败示例

{
  "code": 500,
  "msg": "清除连接缓存失败: 无权限操作"
}

错误码

  • TOOLING_CONN_004：权限不足

3. 测试连接

接口说明

测试 Tooling API 连接是否有效。

请求信息

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

请求参数

无

响应参数

成功响应（HTTP 200）
参数名 类型 说明
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 错误消息（失败时返回）
失败响应（HTTP 200，业务错误）
参数名 类型 说明
code Integer 状态码（非 200 表示失败）
msg String 错误信息

成功示例

{
  "code": 200,
  "msg": "测试连接成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-03 10:35:00",
    "responseTime": 150
  }
}

失败示例

{
  "code": 200,
  "msg": "测试连接成功",
  "data": {
    "success": true,
    "valid": false,
    "testTime": "2026-02-03 10:35:00",
    "responseTime": 50,
    "errorCode": "TOOLING_CONN_001",
    "errorMessage": "Session 无效或已过期"
  }
}

错误码

  • TOOLING_CONN_001：Session 无效或已过期
  • TOOLING_CONN_003：网络超时

4. 设置调用选项

接口说明

设置 Tooling API 连接的调用选项。

请求信息

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

请求参数

Body 参数
参数名 类型 必填 说明
client String 否 客户端名称，用于标识调用来源

请求示例

{
  "client": "DataiToolingClient"
}

响应参数

成功响应（HTTP 200）
参数名 类型 说明
code Integer 状态码（200 表示成功）
msg String 提示信息
data Object 设置结果对象
data.success Boolean 是否成功
data.client String 设置的客户端名称
失败响应（HTTP 200，业务错误）
参数名 类型 说明
code Integer 状态码（非 200 表示失败）
msg String 错误信息

成功示例

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

失败示例

{
  "code": 500,
  "msg": "设置调用选项失败: 连接无效"
}

错误码

  • TOOLING_CONN_001：Session 无效或已过期
  • TOOLING_CONN_007：设置调用选项失败

5. 设置调试头部

接口说明

设置 Tooling API 连接的调试头部。

请求信息

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

请求参数

Body 参数
参数名 类型 必填 说明
debugLevel String 否 调试级别，可选值：NONE、DEBUG、DB、DETAIL、PROFILING

调试级别说明

级别 说明
NONE 不记录调试信息
DEBUG 记录基本调试信息
DB 记录数据库操作信息
DETAIL 记录详细信息
PROFILING 记录性能分析信息

请求示例

{
  "debugLevel": "DEBUG"
}

响应参数

成功响应（HTTP 200）
参数名 类型 说明
code Integer 状态码（200 表示成功）
msg String 提示信息
data Object 设置结果对象
data.success Boolean 是否成功
data.debugLevel String 设置的调试级别
失败响应（HTTP 200，业务错误）
参数名 类型 说明
code Integer 状态码（非 200 表示失败）
msg String 错误信息

成功示例

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

失败示例

{
  "code": 500,
  "msg": "设置调试头部失败: 无效的调试级别"
}

错误码

  • TOOLING_CONN_001：Session 无效或已过期
  • 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 设置调用选项失败 设置 CallOptions 时发生错误
TOOLING_CONN_008 设置调试头部失败 设置 DebuggingHeader 时发生错误

错误码使用场景

TOOLING_CONN_001 - Session 无效或已过期

  • 触发场景：
    • 用户 Session 已过期
    • Session ID 被篡改
    • Salesforce 端 Session 被注销
  • 处理建议：
    • 提示用户重新登录
    • 自动刷新 Session（如果支持）

TOOLING_CONN_002 - 连接创建失败

  • 触发场景：
    • Instance URL 无效
    • Session ID 无效
    • 网络异常
  • 处理建议：
    • 检查 Salesforce 配置
    • 检查网络连接
    • 查看详细错误日志

TOOLING_CONN_003 - 网络超时

  • 触发场景：
    • 网络延迟过高
    • Salesforce 服务响应慢
    • 请求数据量过大
  • 处理建议：
    • 检查网络连接
    • 增加超时时间配置
    • 分批处理大数据量请求

TOOLING_CONN_004 - 权限不足

  • 触发场景：
    • 用户没有对应接口的权限
    • 权限配置未同步到数据库
  • 处理建议：
    • 联系管理员分配权限
    • 检查权限配置是否正确

TOOLING_CONN_005 - API 版本不支持

  • 触发场景：
    • 请求的 API 版本过低或过高
  • 处理建议：
    • 使用支持的 API 版本
    • 查看 Salesforce API 版本文档

TOOLING_CONN_006 - 用户未登录

  • 触发场景：
    • 用户未登录
    • Token 已过期
    • Token 被篡改
  • 处理建议：
    • 提示用户登录
    • 刷新 Token

TOOLING_CONN_007 - 设置调用选项失败

  • 触发场景：
    • 连接无效
    • 参数格式错误
  • 处理建议：
    • 先获取有效连接
    • 检查参数格式

TOOLING_CONN_008 - 设置调试头部失败

  • 触发场景：
    • 连接无效
    • 调试级别无效
  • 处理建议：
    • 先获取有效连接
    • 使用有效的调试级别

使用示例

场景 1：获取连接并测试

// 步骤 1：获取连接
GET /salesforce/tooling/connection/get

// 步骤 2：测试连接
GET /salesforce/tooling/connection/test

场景 2：设置调试选项后执行操作

// 步骤 1：设置调试级别
POST /salesforce/tooling/connection/debugging-header
{
  "debugLevel": "DEBUG"
}

// 步骤 2：设置客户端名称
POST /salesforce/tooling/connection/call-options
{
  "client": "MyApplication"
}

// 步骤 3：执行 Tooling API 操作
// ... 其他 Tooling API 调用

// 步骤 4：清除调试设置（可选）
POST /salesforce/tooling/connection/debugging-header
{
  "debugLevel": "NONE"
}

场景 3：连接异常时重新获取

// 步骤 1：测试连接
GET /salesforce/tooling/connection/test

// 如果返回 valid=false
// 步骤 2：清除缓存
DELETE /salesforce/tooling/connection/clear

// 步骤 3：重新获取连接
GET /salesforce/tooling/connection/get

注意事项

1. 连接缓存

  • 连接会缓存在内存中，避免重复创建
  • 应用重启后缓存会丢失
  • Session 过期时会自动重新创建连接

2. 线程安全

  • 连接缓存使用 ConcurrentHashMap，线程安全
  • 多个线程可以同时获取连接
  • 但每个线程应该使用自己的连接实例

3. 性能建议

  • 在应用启动时预获取连接
  • 定期测试连接有效性
  • 避免频繁清除缓存

4. 安全建议

  • Session ID 在日志中会被脱敏处理
  • 不要在客户端暴露 Session ID
  • 使用 HTTPS 协议传输数据

相关文档