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-06-003-07-api.md

481 lines
13 KiB
Markdown
Raw Normal View History

feat：提交所有模块基础搭建完成
2026-02-06 09:58:58 +08:00
# API 文档 - 检查部署和检索状态
## 元数据
- 需求编号：003-07
- 需求名称：检查部署和检索状态
- 创建时间：2026-02-06
- 创建人：AI Assistant
- 版本号：v1.0.0
- 状态：已完成
## API 概述
本模块提供 Salesforce Metadata API 的部署和检索状态检查功能，支持单次状态查询、轮询监控和历史记录查询。所有接口都需要用户已登录并具有相应的权限。
### 核心功能
1. **部署状态检查**：查询指定部署操作的当前状态
2. **检索状态检查**：查询指定检索操作的当前状态
3. **部署状态轮询**：轮询部署状态直到完成或超时
4. **检索状态轮询**：轮询检索状态直到完成或超时
5. **状态查询历史**：查询状态检查的历史记录
### 技术特点
- 支持轻量级调用（`includeDetails=false`）
- 轮询参数可配置（间隔、超时）
- 异步记录审计日志
- 自动同步关联表状态
## 接口列表
### 1. 检查部署状态
#### 接口说明
查询指定部署操作的当前状态，返回部署结果详情。
#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/deploy/{asyncId}`
- **Content-Type**：application/json
#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |
#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| includeDetails | Boolean | 否 | true | 是否包含详细信息（如错误详情） |
#### 请求示例
```http
GET /salesforce/metadata/status/deploy/0Afxx0000004M5sCAE?includeDetails=true
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | DeployResult 对象 |
#### DeployResult 对象
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 异步操作 ID |
| status | String | 部署状态（Queued/InProgress/Succeeded/Failed/Canceled） |
| numberComponentErrors | Integer | 组件错误数 |
| numberComponentsDeployed | Integer | 已部署组件数 |
| numberTestErrors | Integer | 测试错误数 |
| numberTestsCompleted | Integer | 已完成测试数 |
| errorMessage | String | 错误消息（失败时） |
#### 成功响应示例
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"id": "0Afxx0000004M5sCAE",
"status": "Succeeded",
"numberComponentErrors": 0,
"numberComponentsDeployed": 5,
"numberTestErrors": 0,
"numberTestsCompleted": 10,
"errorMessage": null
}
}
```
#### 失败响应示例
```json
{
"code": 500,
"msg": "检查部署状态失败: 无效的异步操作 ID",
"data": null
}
```
---
### 2. 检查检索状态
#### 接口说明
查询指定检索操作的当前状态，返回检索结果详情。
#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/retrieve/{asyncId}`
- **Content-Type**：application/json
#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |
#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| includeDetails | Boolean | 否 | true | 是否包含详细信息（如错误详情） |
#### 请求示例
```http
GET /salesforce/metadata/status/retrieve/0Afxx0000004M5sCAE?includeDetails=true
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | RetrieveResult 对象 |
#### RetrieveResult 对象
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 异步操作 ID |
| status | String | 检索状态（Queued/InProgress/Succeeded/Failed/Canceled） |
| success | Boolean | 是否成功 |
| errorMessage | String | 错误消息（失败时） |
| zipFile | String | ZIP 文件内容（Base64 编码，成功时） |
#### 成功响应示例
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"id": "0Afxx0000004M5sCAE",
"status": "Succeeded",
"success": true,
"errorMessage": null,
"zipFile": "UEsDBBQAAAAIA..."
}
}
```
#### 失败响应示例
```json
{
"code": 500,
"msg": "检查检索状态失败: 异步操作未找到",
"data": null
}
```
---
### 3. 轮询部署状态
#### 接口说明
轮询部署状态直到完成（Succeeded/Failed/Canceled）或超时。适用于需要等待部署完成的场景。
#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/deploy/poll/{asyncId}`
- **Content-Type**：application/json
#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |
#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| interval | Long | 否 | 2000 | 轮询间隔（毫秒） |
| timeout | Long | 否 | 300000 | 超时时间（毫秒），默认 5 分钟 |
#### 请求示例
```http
GET /salesforce/metadata/status/deploy/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | DeployResult 对象（最终状态） |
#### 成功响应示例
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"id": "0Afxx0000004M5sCAE",
"status": "Succeeded",
"numberComponentErrors": 0,
"numberComponentsDeployed": 5,
"numberTestErrors": 0,
"numberTestsCompleted": 10,
"errorMessage": null
}
}
```
#### 超时响应示例
```json
{
"code": 500,
"msg": "部署轮询超时",
"data": null
}
```
---
### 4. 轮询检索状态
#### 接口说明
轮询检索状态直到完成（Succeeded/Failed/Canceled）或超时。适用于需要等待检索完成的场景。
#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/retrieve/poll/{asyncId}`
- **Content-Type**：application/json
#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |
#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| interval | Long | 否 | 2000 | 轮询间隔（毫秒） |
| timeout | Long | 否 | 300000 | 超时时间（毫秒），默认 5 分钟 |
#### 请求示例
```http
GET /salesforce/metadata/status/retrieve/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | RetrieveResult 对象（最终状态） |
#### 成功响应示例
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"id": "0Afxx0000004M5sCAE",
"status": "Succeeded",
"success": true,
"errorMessage": null,
"zipFile": "UEsDBBQAAAAIA..."
}
}
```
#### 中断响应示例
```json
{
"code": 500,
"msg": "轮询被中断",
"data": null
}
```
---
### 5. 获取状态查询历史
#### 接口说明
查询状态检查的历史记录，支持按操作类型筛选。
#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/history`
- **Content-Type**：application/json
#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| operationType | String | 否 | - | 操作类型（DEPLOY/RETRIEVE），不填则查询所有 |
| limit | Integer | 否 | 50 | 返回数量限制 |
#### 请求示例
```http
GET /salesforce/metadata/status/history?operationType=DEPLOY&limit=50
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 状态检查历史列表 |
#### StatusCheckHistoryVo 对象
| 参数名 | 类型 | 说明 |
|--------|------|------|
| checkId | String | 检查记录 ID |
| asyncId | String | 异步操作 ID |
| operationType | String | 操作类型（DEPLOY/RETRIEVE） |
| status | String | 状态 |
| checkTime | String | 检查时间（ISO 8601 格式） |
| errorMessage | String | 错误消息 |
#### 成功响应示例
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"checkId": "CHK202502060001",
"asyncId": "0Afxx0000004M5sCAE",
"operationType": "DEPLOY",
"status": "Succeeded",
"checkTime": "2026-02-06T10:30:00Z",
"errorMessage": null
},
{
"checkId": "CHK202502060002",
"asyncId": "0Afxx0000004M5sCAF",
"operationType": "RETRIEVE",
"status": "Failed",
"checkTime": "2026-02-06T10:25:00Z",
"errorMessage": "Invalid metadata type"
}
]
}
```
---
## 错误码
### 状态检查错误码
| 错误码 | 说明 | 场景 |
|--------|------|------|
| STATUS_001 | 会话已过期 | Salesforce 会话过期 |
| STATUS_002 | 未授权访问 | 用户没有权限访问 |
| STATUS_003 | 无效的异步操作 ID | asyncId 格式不正确 |
| STATUS_004 | 异步操作未找到 | 指定的 asyncId 不存在 |
| STATUS_005 | 检查状态失败 | API 调用失败 |
| STATUS_006 | 轮询超时 | 轮询时间超过 timeout 参数 |
| STATUS_007 | 轮询被中断 | 线程被中断 |
| STATUS_008 | 远程调用失败 | 网络异常或 Salesforce 服务不可用 |
| STATUS_009 | 查询历史失败 | 数据库查询失败 |
### HTTP 状态码
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
## 数据字典
### 部署状态（Deploy Status）
| 状态值 | 说明 |
|--------|------|
| Queued | 已排队，等待执行 |
| InProgress | 进行中 |
| Succeeded | 成功完成 |
| Failed | 失败 |
| Canceled | 已取消 |
### 检索状态（Retrieve Status）
| 状态值 | 说明 |
|--------|------|
| Queued | 已排队，等待执行 |
| InProgress | 进行中 |
| Succeeded | 成功完成 |
| Failed | 失败 |
| Canceled | 已取消 |
### 操作类型（Operation Type）
| 类型值 | 说明 |
|--------|------|
| DEPLOY | 部署操作 |
| RETRIEVE | 检索操作 |
## 使用示例
### 场景 1：检查部署状态
```java
// 前端调用示例
fetch('/salesforce/metadata/status/deploy/0Afxx0000004M5sCAE?includeDetails=true')
.then(response => response.json())
.then(data => {
if (data.code === 200) {
console.log('部署状态:', data.data.status);
} else {
console.error('查询失败:', data.msg);
}
});
```
### 场景 2：轮询检索状态直到完成
```java
// 前端调用示例
fetch('/salesforce/metadata/status/retrieve/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000')
.then(response => response.json())
.then(data => {
if (data.code === 200) {
console.log('检索完成，状态:', data.data.status);
if (data.data.success) {
// 处理 ZIP 文件
console.log('ZIP 文件:', data.data.zipFile);
}
} else {
console.error('轮询失败:', data.msg);
}
});
```
### 场景 3：查询部署历史
```java
// 前端调用示例
fetch('/salesforce/metadata/status/history?operationType=DEPLOY&limit=10')
.then(response => response.json())
.then(data => {
if (data.code === 200) {
data.data.forEach(record => {
console.log('检查记录:', record.checkId, record.status);
});
}
});
```
## 注意事项
### 1. 轮询超时处理
- 轮询接口可能会长时间阻塞（默认最长 5 分钟）
- 建议在前端设置更长的超时时间或异步处理
- 如果超时，可以再次调用轮询接口继续等待
### 2. 轻量级调用
- 如果不需要详细的错误信息，建议设置 `includeDetails=false`
- 轻量级调用可以减少网络传输和 Salesforce API 调用开销
### 3. 审计日志
- 每次状态检查都会异步记录到数据库
- 审计日志不影响主流程性能
- 可以通过历史查询接口查看审计日志
### 4. 关联表状态同步
- 状态检查会自动更新部署日志表和检索记录表的状态
- 无需手动更新这些表
## 相关文档
- [需求文档](../requirements/sub/2026-01-28-003-07-检查部署和检索状态.md)
- [设计文档](../design/2026-02-03-003-07-检查部署和检索状态-设计.md)
- [决策记录](../decisions/2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md)
- [变更日志](../changelog/2026-02-06-003-07-changelog.md)
- [复盘文档](../retros/2026-02-06-003-07-retro.md)
- [会话记录](../sessions/2026-02-03-003-07-session.md)
- [部署操作 API 文档](./2026-02-06-003-03-api.md)
- [检索操作 API 文档](./2026-02-06-003-06-api.md)
Reference in New Issue Copy Permalink