103 lines
3.4 KiB
Markdown
103 lines
3.4 KiB
Markdown
|
# Metadata 连接管理 API 文档
|
|||
|
|
|
|||
|
|
## 元数据
|
|||
|
|
- 需求编号：003
|
|||
|
|
- 创建时间：2026-02-03
|
|||
|
|
- 创建人：AI Assistant
|
|||
|
|
- 版本：v1.0.0
|
|||
|
|
|
|||
|
|
## API 概述
|
|||
|
|
本模块提供 Salesforce Metadata API 源 Org 的连接管理功能，包括查看连接状态、测试连接、刷新连接和关闭连接。所有接口均需要认证权限。
|
|||
|
|
|
|||
|
|
## 接口列表
|
|||
|
|
|
|||
|
|
### 1. 获取连接状态
|
|||
|
|
- **功能描述**：获取当前 Metadata API 连接的状态信息，包括是否已连接、Session ID 是否有效、Server URL 等。
|
|||
|
|
- **请求方式**：GET
|
|||
|
|
- **请求路径**：`/api/metadata/connection/status`
|
|||
|
|
- **权限要求**：`metadata:connection:status`
|
|||
|
|
- **请求参数**：无
|
|||
|
|
- **响应参数**：
|
|||
|
|
| 参数名 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| code | Integer | 状态码（200 成功） |
|
|||
|
|
| msg | String | 提示信息 |
|
|||
|
|
| data | Object | 连接状态对象 |
|
|||
|
|
| data.connected | Boolean | 是否已连接 |
|
|||
|
|
| data.serverUrl | String | Metadata Server URL |
|
|||
|
|
| data.username | String | 当前用户名 |
|
|||
|
|
| data.apiVersion | String | API 版本 |
|
|||
|
|
- **成功示例**：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "操作成功",
|
|||
|
|
"data": {
|
|||
|
|
"connected": true,
|
|||
|
|
"serverUrl": "https://datai-dev-ed.my.salesforce.com/services/Soap/m/65.0/00D5j00000C...",
|
|||
|
|
"username": "admin@datai.com",
|
|||
|
|
"apiVersion": "65.0"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 测试连接
|
|||
|
|
- **功能描述**：尝试建立 Metadata API 连接并执行一次简单的元数据描述操作（describeMetadata），以验证连接的有效性。
|
|||
|
|
- **请求方式**：POST
|
|||
|
|
- **请求路径**：`/api/metadata/connection/test`
|
|||
|
|
- **权限要求**：`metadata:connection:test`
|
|||
|
|
- **请求参数**：无
|
|||
|
|
- **响应参数**：
|
|||
|
|
| 参数名 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| code | Integer | 状态码 |
|
|||
|
|
| msg | String | 提示信息 |
|
|||
|
|
| data | Boolean | 测试结果（true 成功，false 失败） |
|
|||
|
|
- **成功示例**：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "操作成功",
|
|||
|
|
"data": true
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 刷新连接
|
|||
|
|
- **功能描述**：强制刷新当前的 Metadata API 连接，重新从 SessionManager 获取 Session ID 并建立新连接。
|
|||
|
|
- **请求方式**：POST
|
|||
|
|
- **请求路径**：`/api/metadata/connection/refresh`
|
|||
|
|
- **权限要求**：`metadata:connection:refresh`
|
|||
|
|
- **请求参数**：无
|
|||
|
|
- **响应参数**：
|
|||
|
|
| 参数名 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| code | Integer | 状态码 |
|
|||
|
|
| msg | String | 提示信息 |
|
|||
|
|
| data | Boolean | 刷新结果 |
|
|||
|
|
|
|||
|
|
### 4. 关闭连接
|
|||
|
|
- **功能描述**：关闭当前的 Metadata API 连接，释放资源。
|
|||
|
|
- **请求方式**：POST
|
|||
|
|
- **请求路径**：`/api/metadata/connection/close`
|
|||
|
|
- **权限要求**：`metadata:connection:close`
|
|||
|
|
- **请求参数**：无
|
|||
|
|
- **响应参数**：
|
|||
|
|
| 参数名 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| code | Integer | 状态码 |
|
|||
|
|
| msg | String | 提示信息 |
|
|||
|
|
| data | Boolean | 关闭结果 |
|
|||
|
|
|
|||
|
|
## 错误码
|
|||
|
|
| 错误码 | 说明 | 解决方案 |
|
|||
|
|
|--------|------|----------|
|
|||
|
|
| 500 | 系统内部错误 | 检查服务器日志 |
|
|||
|
|
| 401 | 未认证 | 请先登录系统 |
|
|||
|
|
| 403 | 无权限 | 请联系管理员分配权限 |
|
|||
|
|
| 10001 | Salesforce 认证失败 | Session 已过期，请重新登录 Salesforce |
|
|||
|
|
| 10002 | Salesforce 操作失败 | 检查网络连接或参数配置 |
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
- [需求文档](../requirements/2026-01-28-003-MetadataAPI源org实现.md)
|
|||
|
|
- [设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|