kris/datai

Fork 0

Kris 6357f1c579 feat：提交所有模块基础搭建完成

2026-02-06 09:58:58 +08:00

13 KiB

Raw Permalink Blame History

API 文档 - 检查部署和检索状态

元数据

需求编号：003-07
需求名称：检查部署和检索状态
创建时间：2026-02-06
创建人：AI Assistant
版本号：v1.0.0
状态：已完成

API 概述

本模块提供 Salesforce Metadata API 的部署和检索状态检查功能，支持单次状态查询、轮询监控和历史记录查询。所有接口都需要用户已登录并具有相应的权限。

核心功能

部署状态检查：查询指定部署操作的当前状态
检索状态检查：查询指定检索操作的当前状态
部署状态轮询：轮询部署状态直到完成或超时
检索状态轮询：轮询检索状态直到完成或超时
状态查询历史：查询状态检查的历史记录

技术特点

支持轻量级调用（includeDetails=false）
轮询参数可配置（间隔、超时）
异步记录审计日志
自动同步关联表状态

接口列表

1. 检查部署状态

接口说明

查询指定部署操作的当前状态，返回部署结果详情。

请求信息

请求方式：GET
请求路径：/salesforce/metadata/status/deploy/{asyncId}
Content-Type：application/json

路径参数

参数名	类型	必填	说明
asyncId	String	是	异步操作 ID，Salesforce 返回的 AsyncResult ID

查询参数

参数名	类型	必填	默认值	说明
includeDetails	Boolean	否	true	是否包含详细信息（如错误详情）

请求示例

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	错误消息（失败时）

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "numberComponentErrors": 0,
    "numberComponentsDeployed": 5,
    "numberTestErrors": 0,
    "numberTestsCompleted": 10,
    "errorMessage": null
  }
}

失败响应示例

{
  "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	是否包含详细信息（如错误详情）

请求示例

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 编码，成功时）

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "success": true,
    "errorMessage": null,
    "zipFile": "UEsDBBQAAAAIA..."
  }
}

失败响应示例

{
  "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 分钟

请求示例

GET /salesforce/metadata/status/deploy/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	DeployResult 对象（最终状态）

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "numberComponentErrors": 0,
    "numberComponentsDeployed": 5,
    "numberTestErrors": 0,
    "numberTestsCompleted": 10,
    "errorMessage": null
  }
}

超时响应示例

{
  "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 分钟

请求示例

GET /salesforce/metadata/status/retrieve/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000

响应参数

参数名	类型	说明
code	Integer	状态码（200 成功，其他失败）
msg	String	提示信息
data	Object	RetrieveResult 对象（最终状态）

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "success": true,
    "errorMessage": null,
    "zipFile": "UEsDBBQAAAAIA..."
  }
}

中断响应示例

{
  "code": 500,
  "msg": "轮询被中断",
  "data": null
}

5. 获取状态查询历史

接口说明

查询状态检查的历史记录，支持按操作类型筛选。

请求信息

请求方式：GET
请求路径：/salesforce/metadata/status/history
Content-Type：application/json

查询参数

参数名	类型	必填	默认值	说明
operationType	String	否	-	操作类型（DEPLOY/RETRIEVE），不填则查询所有
limit	Integer	否	50	返回数量限制

请求示例

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	错误消息

成功响应示例

{
  "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：检查部署状态

// 前端调用示例
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：轮询检索状态直到完成

// 前端调用示例
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：查询部署历史

// 前端调用示例
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. 关联表状态同步

状态检查会自动更新部署日志表和检索记录表的状态
无需手动更新这些表

13 KiB Raw Permalink Blame History Unescape Escape

API 文档 - 检查部署和检索状态

元数据

API 概述

核心功能

技术特点

接口列表

1. 检查部署状态

接口说明

请求信息

路径参数

查询参数

请求示例

响应参数

DeployResult 对象

成功响应示例

失败响应示例

2. 检查检索状态

接口说明

请求信息

路径参数

查询参数

请求示例

响应参数

RetrieveResult 对象

成功响应示例

失败响应示例

3. 轮询部署状态

接口说明

请求信息

路径参数

查询参数

请求示例

响应参数

成功响应示例

超时响应示例

4. 轮询检索状态

接口说明

请求信息

路径参数

查询参数

请求示例

响应参数

成功响应示例

中断响应示例

5. 获取状态查询历史

接口说明

请求信息

查询参数

请求示例

响应参数

StatusCheckHistoryVo 对象

成功响应示例

错误码

状态检查错误码

HTTP 状态码

数据字典

部署状态（Deploy Status）

检索状态（Retrieve Status）

操作类型（Operation Type）

使用示例

场景 1：检查部署状态

场景 2：轮询检索状态直到完成

场景 3：查询部署历史

注意事项

1. 轮询超时处理

2. 轻量级调用

3. 审计日志

4. 关联表状态同步

相关文档

13 KiB

Raw Permalink Blame History