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-05-003-01-api.md

13 KiB
Raw Permalink Blame History

API 文档

元数据

  • 需求编号：003
  • 子需求编号：003-01
  • 子需求名称：连接管理
  • 创建时间：2026-02-05
  • 创建人：AI Assistant
  • 版本号：v1.0.0
  • 接口基地址：/api/metadata/connection

API 概述

Metadata API 连接管理接口提供对 Salesforce Metadata API 连接的管理能力，包括连接状态的获取、连接测试、连接刷新、连接关闭、调用选项设置、连接历史记录查询和连接缓存清除等功能。

核心功能

  1. 连接状态管理：获取当前 Metadata API 连接的状态信息
  2. 连接测试：测试 Metadata API 连接是否可用
  3. 连接刷新：刷新 Metadata API 连接，重新创建连接实例
  4. 连接关闭：关闭 Metadata API 连接，释放资源
  5. 调用选项设置：设置 Metadata API 的调用选项（如客户端名称）
  6. 连接历史记录：查询 Metadata API 连接的历史记录
  7. 连接缓存管理：清除 Metadata API 连接缓存

认证方式

所有接口都需要通过认证，使用 Spring Security 进行权限控制。请求头中需要包含有效的 JWT Token。

权限要求

每个接口都有特定的权限要求，使用 @PreAuthorize 注解进行控制。

接口列表

1. 获取连接状态

功能描述：获取当前 Metadata API 连接的状态信息，包括连接是否有效、最后测试时间、响应时间等。

请求方式：GET

请求路径：/api/metadata/connection/status

权限要求：metadata:connection:status

请求参数：无

响应参数：

参数名 类型 说明
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.errorMessage String 错误信息（如果有）

成功示例：

{
  "code": 200,
  "msg": "获取连接状态成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-05 14:30:00",
    "responseTime": 150,
    "errorMessage": null
  }
}

失败示例：

{
  "code": 500,
  "msg": "获取连接状态失败: 用户未登录或会话已过期",
  "data": null
}

错误码：

  • 200：成功
  • 500：服务器内部错误
  • 401：未授权
  • 403：权限不足

2. 测试连接

功能描述：测试 Metadata API 连接是否可用，会实际调用 Salesforce API 进行验证。

请求方式：POST

请求路径：/api/metadata/connection/test

权限要求：metadata:connection:test

请求参数：无

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据（成功时为 null）

成功示例：

{
  "code": 200,
  "msg": "连接测试成功",
  "data": null
}

失败示例：

{
  "code": 500,
  "msg": "连接测试失败: 无法连接到 Salesforce 服务器",
  "data": null
}

错误码：

  • 200：连接测试成功
  • 500：连接测试失败

调用场景：

  • 系统启动时自动测试连接
  • 用户手动测试连接状态
  • 定时任务检查连接健康状态

3. 刷新连接

功能描述：刷新 Metadata API 连接，关闭现有连接并重新创建。适用于会话过期或需要重新建立连接的场景。

请求方式：POST

请求路径：/api/metadata/connection/refresh

权限要求：metadata:connection:refresh

请求参数：无

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据（成功时为 null）

成功示例：

{
  "code": 200,
  "msg": "刷新连接成功",
  "data": null
}

失败示例：

{
  "code": 500,
  "msg": "刷新连接失败: 会话已过期",
  "data": null
}

错误码：

  • 200：刷新连接成功
  • 500：刷新连接失败

调用场景：

  • 会话过期后重新建立连接
  • 连接出现异常时恢复连接
  • 切换 org 类型后重新连接

4. 关闭连接

功能描述：关闭 Metadata API 连接，释放相关资源。关闭后需要调用刷新接口重新建立连接。

请求方式：POST

请求路径：/api/metadata/connection/close

权限要求：metadata:connection:close

请求参数：无

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据（成功时为 null）

成功示例：

{
  "code": 200,
  "msg": "关闭连接成功",
  "data": null
}

失败示例：

{
  "code": 500,
  "msg": "关闭连接失败: 连接不存在",
  "data": null
}

错误码：

  • 200：关闭连接成功
  • 500：关闭连接失败

调用场景：

  • 系统关闭时释放资源
  • 切换用户时关闭旧连接
  • 长时间不使用时释放连接

5. 设置调用选项

功能描述：设置 Metadata API 的调用选项，如客户端名称等。这些选项会影响 API 调用的行为。

请求方式：POST

请求路径：/api/metadata/connection/call-options

权限要求：metadata:connection:callOptions

请求参数：

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

请求示例：

{
  "client": "DataiMetadataClient"
}

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据（成功时为 null）

成功示例：

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

失败示例：

{
  "code": 500,
  "msg": "设置调用选项失败: 客户端名称不能为空",
  "data": null
}

错误码：

  • 200：设置调用选项成功
  • 400：请求参数错误
  • 500：设置调用选项失败

调用场景：

  • 初始化连接时设置客户端标识
  • 多客户端环境下区分调用来源
  • 监控和日志记录时标识客户端

6. 获取连接历史记录

功能描述：获取 Metadata API 连接的历史记录，包括连接创建、测试、刷新、关闭等操作的记录。

请求方式：GET

请求路径：/api/metadata/connection/history

权限要求：metadata:connection:history

请求参数：无

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Array 连接历史记录列表
data[].id Long 记录 ID
data[].orgType String ORG 类型（source/target）
data[].status String 连接状态（connected/failed/closed）
data[].testTime String 测试时间（格式：yyyy-MM-dd HH:mm:ss）
data[].responseTime Long 响应时间（毫秒）
data[].errorMessage String 错误信息（如果有）
data[].createTime String 记录创建时间
data[].updateTime String 记录更新时间

成功示例：

{
  "code": 200,
  "msg": "获取连接历史成功",
  "data": [
    {
      "id": 1,
      "orgType": "source",
      "status": "connected",
      "testTime": "2026-02-05 14:30:00",
      "responseTime": 150,
      "errorMessage": null,
      "createTime": "2026-02-05 14:30:00",
      "updateTime": "2026-02-05 14:30:00"
    },
    {
      "id": 2,
      "orgType": "source",
      "status": "failed",
      "testTime": "2026-02-05 14:25:00",
      "responseTime": 0,
      "errorMessage": "会话已过期",
      "createTime": "2026-02-05 14:25:00",
      "updateTime": "2026-02-05 14:25:00"
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "获取连接历史失败: 数据库连接错误",
  "data": null
}

错误码：

  • 200：获取连接历史成功
  • 500：获取连接历史失败

调用场景：

  • 监控连接健康状态
  • 排查连接问题
  • 分析连接使用模式

7. 清除连接缓存

功能描述：清除 Metadata API 连接缓存，强制下次请求时重新创建连接。适用于连接状态异常或需要强制刷新连接的场景。

请求方式：DELETE

请求路径：/api/metadata/connection/cache

权限要求：metadata:connection:clear

请求参数：无

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据（成功时为 null）

成功示例：

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

失败示例：

{
  "code": 500,
  "msg": "清除连接缓存失败: 缓存不存在",
  "data": null
}

错误码：

  • 200：清除连接缓存成功
  • 500：清除连接缓存失败

调用场景：

  • 连接状态异常时强制刷新
  • 切换 org 配置后清除旧缓存
  • 调试和测试时重置连接状态

错误码

系统错误码

错误码 说明 处理建议
200 操作成功 无需处理
400 请求参数错误 检查请求参数是否符合要求
401 未授权 检查 JWT Token 是否有效
403 权限不足 检查用户是否有该接口的权限
404 资源不存在 检查请求路径是否正确
500 服务器内部错误 查看服务器日志，联系管理员

业务错误码

错误码 说明 处理建议
METADATA_CONNECTION_ERROR Metadata API 连接错误 检查网络连接和 Salesforce 服务状态
METADATA_AUTH_ERROR Metadata API 认证错误 检查 Session 是否过期，尝试重新登录
METADATA_OPERATION_ERROR Metadata API 操作错误 检查操作参数是否正确
SESSION_EXPIRED 会话已过期 重新登录获取新的 Session
INVALID_SESSION 无效的会话 检查 Session ID 是否正确
CONNECTION_FAILED 连接失败 检查网络连接和服务器地址

调用示例

完整调用流程

// 1. 获取连接状态
GET /api/metadata/connection/status
Response: {
  "code": 200,
  "msg": "获取连接状态成功",
  "data": {
    "valid": true,
    "testTime": "2026-02-05 14:30:00"
  }
}

// 2. 如果连接无效，刷新连接
POST /api/metadata/connection/refresh
Response: {
  "code": 200,
  "msg": "刷新连接成功"
}

// 3. 测试连接
POST /api/metadata/connection/test
Response: {
  "code": 200,
  "msg": "连接测试成功"
}

// 4. 设置调用选项
POST /api/metadata/connection/call-options
Request Body: {
  "client": "DataiMetadataClient"
}
Response: {
  "code": 200,
  "msg": "设置调用选项成功"
}

// 5. 执行业务操作（如部署元数据）
// ...

// 6. 关闭连接
POST /api/metadata/connection/close
Response: {
  "code": 200,
  "msg": "关闭连接成功"
}

性能指标

响应时间

  • 获取连接状态：< 100ms
  • 测试连接：< 2s（取决于网络状况）
  • 刷新连接：< 3s（取决于网络状况）
  • 关闭连接：< 100ms
  • 设置调用选项：< 100ms
  • 获取连接历史：< 500ms
  • 清除连接缓存：< 100ms

并发限制

  • 单个用户同时只能有一个活跃的 Metadata API 连接
  • 连接缓存按 orgType 进行隔离
  • 建议在高并发场景下使用连接池（后续版本支持）

注意事项

  1. 会话管理：所有接口都依赖有效的 Salesforce 会话，请确保在调用前先完成认证
  2. 连接缓存：连接会被缓存以提高性能，如需强制刷新请使用清除缓存接口
  3. 错误处理：建议对所有接口的错误情况进行处理，特别是认证错误和连接错误
  4. 资源释放：长时间不使用连接时，建议调用关闭连接接口释放资源
  5. 历史记录：连接历史记录会持久化到数据库，可用于监控和审计

相关文档