datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-06-003-04-api.md

API 文档：003-04 异步操作

元数据

• 需求编号: 003-04
• 需求名称: 异步操作
• 创建时间: 2026-02-06
• 创建人: AI Assistant
• 版本号: v1.0.0
• 状态: 已完成

---

API 概述

本文档描述了 Metadata API 异步操作管理模块的 REST API 接口，提供异步操作状态查询、服务端同步轮询、异步操作取消、操作历史记录等功能。

基础信息

• 基础路径: /salesforce/metadata/async
• 权限前缀: salesforce:metadata:async
• 内容类型: application/json

---

接口列表

1. 获取异步操作状态

功能描述: 查询指定异步操作的当前状态，立即返回当前状态信息。

请求方式: GET

请求路径: /salesforce/metadata/async/status/{asyncId}

权限要求: salesforce:metadata:async:query

请求参数

参数名	类型	必填	位置	说明
asyncId	String	是	Path	异步操作 ID，Salesforce 返回的 ID，如 0Afxx0000000001CAA

响应参数

参数名	类型	说明
code	Integer	状态码，200 表示成功
msg	String	提示信息
data	Object	异步操作结果
data.id	String	异步操作 ID
data.done	Boolean	操作是否完成
data.message	String	操作消息
data.state	String	操作状态，可选值：Queued、InProgress、Completed、Failed、Canceled
data.checkTime	String	状态检查时间，ISO 8601 格式

成功示例

请求:

GET /salesforce/metadata/async/status/0Afxx0000000001CAA

响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000000001CAA",
    "done": true,
    "message": "部署成功",
    "state": "Completed",
    "checkTime": "2026-02-06T14:30:00"
  }
}

失败示例

请求:

GET /salesforce/metadata/async/status/invalid-id

响应:

{
  "code": 500,
  "msg": "获取异步操作状态失败: 无效的异步操作 ID"
}

使用场景

• 前端需要立即获取异步操作的当前状态
• 用户主动刷新状态
• 轮询前的初始状态查询

---

2. 同步轮询异步操作状态

功能描述: 服务端轮询直到异步操作完成（成功、失败或取消），最多轮询 60 次，每 5 秒一次，5 分钟超时。注意：此接口会阻塞直到操作完成或超时。

请求方式: GET

请求路径: /salesforce/metadata/async/poll/{asyncId}

权限要求: salesforce:metadata:async:query

请求参数

参数名	类型	必填	位置	默认值	说明
asyncId	String	是	Path	-	异步操作 ID
interval	Long	否	Query	5000	轮询间隔（毫秒），最小 1000
timeout	Long	否	Query	300000	超时时间（毫秒），最大 600000

响应参数

与"获取异步操作状态"接口相同。

成功示例

请求:

GET /salesforce/metadata/async/poll/0Afxx0000000001CAA?interval=5000&timeout=300000

响应（操作完成）:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000000001CAA",
    "done": true,
    "message": "部署成功",
    "state": "Completed",
    "checkTime": "2026-02-06T14:35:00"
  }
}

超时示例

请求:

GET /salesforce/metadata/async/poll/0Afxx0000000001CAA?timeout=10000

响应:

{
  "code": 500,
  "msg": "同步轮询异步操作状态失败: 异步操作轮询超时，已等待 10 秒"
}

使用场景

• 前端需要等待异步操作完成后再进行下一步操作
• 部署操作后等待部署完成
• 需要确保操作完成后再返回给用户的场景

---

3. 取消异步操作

功能描述: 尝试取消指定的异步操作。注意：已完成的操作无法取消。

请求方式: POST

请求路径: /salesforce/metadata/async/cancel/{asyncId}

权限要求: salesforce:metadata:async:cancel

请求参数

参数名	类型	必填	位置	说明
asyncId	String	是	Path	异步操作 ID

响应参数

参数名	类型	说明
code	Integer	状态码，200 表示成功
msg	String	提示信息
data	Object	取消结果
data.asyncId	String	异步操作 ID
data.success	Boolean	是否成功取消
data.cancelTime	String	取消操作时间，ISO 8601 格式
data.message	String	消息说明

成功示例

请求:

POST /salesforce/metadata/async/cancel/0Afxx0000000001CAA

响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "asyncId": "0Afxx0000000001CAA",
    "success": true,
    "cancelTime": "2026-02-06T14:30:00",
    "message": "异步操作已成功取消"
  }
}

失败示例

请求:

POST /salesforce/metadata/async/cancel/0Afxx0000000001CAA

响应（操作已完成）:

{
  "code": 500,
  "msg": "取消异步操作失败: 操作可能已完成或无法取消"
}

使用场景

• 用户需要取消正在进行的部署操作
• 发现操作配置错误，需要立即停止
• 系统需要自动取消超时的操作

---

4. 获取异步操作历史

功能描述: 查询最近的异步操作历史记录。

请求方式: GET

请求路径: /salesforce/metadata/async/history

权限要求: salesforce:metadata:async:query

请求参数

参数名	类型	必填	位置	默认值	说明
limit	Integer	否	Query	10	返回数量限制，最大 100

响应参数

参数名	类型	说明
code	Integer	状态码，200 表示成功
msg	String	提示信息
data	Array	异步操作历史列表
data[].id	Long	记录 ID
data[].asyncId	String	异步操作 ID
data[].status	String	操作状态
data[].done	Boolean	是否完成
data[].message	String	操作消息
data[].errorMessage	String	错误消息
data[].createTime	String	创建时间
data[].updateTime	String	更新时间
data[].createBy	String	创建人

成功示例

请求:

GET /salesforce/metadata/async/history?limit=5

响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "asyncId": "0Afxx0000000001CAA",
      "status": "Completed",
      "done": true,
      "message": "部署成功",
      "errorMessage": null,
      "createTime": "2026-02-06T14:00:00",
      "updateTime": "2026-02-06T14:30:00",
      "createBy": "admin"
    },
    {
      "id": 2,
      "asyncId": "0Afxx0000000002CAA",
      "status": "Failed",
      "done": true,
      "message": "部署失败",
      "errorMessage": "Invalid metadata",
      "createTime": "2026-02-06T13:00:00",
      "updateTime": "2026-02-06T13:05:00",
      "createBy": "admin"
    }
  ]
}

使用场景

• 查看最近的异步操作记录
• 审计和监控异步操作
• 排查问题

---

5. 根据 asyncId 查询异步操作记录

功能描述: 根据 Salesforce 返回的异步操作 ID 查询本地记录。

请求方式: GET

请求路径: /salesforce/metadata/async/record/{asyncId}

权限要求: salesforce:metadata:async:query

请求参数

参数名	类型	必填	位置	说明
asyncId	String	是	Path	异步操作 ID

响应参数

与"获取异步操作历史"接口中的单条记录格式相同。

成功示例

请求:

GET /salesforce/metadata/async/record/0Afxx0000000001CAA

响应:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "asyncId": "0Afxx0000000001CAA",
    "status": "Completed",
    "done": true,
    "message": "部署成功",
    "errorMessage": null,
    "createTime": "2026-02-06T14:00:00",
    "updateTime": "2026-02-06T14:30:00",
    "createBy": "admin"
  }
}

失败示例

请求:

GET /salesforce/metadata/async/record/invalid-id

响应:

{
  "code": 500,
  "msg": "未找到异步操作记录: invalid-id"
}

使用场景

• 根据 asyncId 查询特定操作的详细记录
• 查看操作的历史状态变化

---

错误码

业务错误码

错误码	错误信息	说明
200	操作成功	请求处理成功
500	操作失败	通用错误，具体信息见 msg 字段

异常类型

异常类型	触发条件	HTTP 状态码
SalesforceAuthException	会话过期、未授权	401
SalesforceOperationException	无效的操作 ID、操作失败	500
IllegalArgumentException	参数校验失败	400

常见错误场景

场景	错误信息	解决方案
会话过期	"Salesforce 会话已过期，请重新连接"	重新连接 Salesforce
无效的操作 ID	"无效的异步操作 ID"	检查 asyncId 是否正确
操作已完成	"取消异步操作失败，操作可能已完成或无法取消"	无法取消已完成的操作
轮询超时	"异步操作轮询超时，已等待 X 秒"	增加超时时间或检查操作状态
轮询被中断	"异步操作轮询被中断"	重新发起轮询请求

---

状态说明

异步操作状态

状态	说明	是否可取消
Queued	已排队，等待执行	是
InProgress	正在进行中	是
Completed	已完成	否
Failed	失败	否
Canceled	已取消	否

状态流转

Queued → InProgress → Completed
   ↓         ↓           ↓
Canceled   Failed      (结束)

---

使用建议

1. 状态查询 vs 轮询

• 状态查询: 适用于需要立即获取当前状态的场景，不阻塞
• 轮询: 适用于需要等待操作完成的场景，会阻塞直到完成或超时

2. 超时设置

• 默认超时 5 分钟（300 秒）适用于大多数部署操作
• 对于大型部署，可以适当增加超时时间
• 不建议设置过长的超时时间，以免占用过多服务器资源

3. 错误处理

• 对于会话过期错误，应提示用户重新连接
• 对于无效的操作 ID，应检查 ID 是否正确
• 对于超时错误，可以再次发起轮询或查询状态

4. 权限控制

• 查询操作需要 salesforce:metadata:async:query 权限
• 取消操作需要 salesforce:metadata:async:cancel 权限
• 建议将取消权限授予更高级别的用户

---

相关文档

• 需求文档
• 设计文档
• 决策记录
• 复盘文档
• 变更日志
• 会话记录