本文档介绍 DMS 任务回调（Callback）能力的完整用法，帮助您将迁移任务的关键事件实时同步到业务侧系统。 ## 配置回调 CallbackConfig 配置方式在 `CreateDataMigrateTask` 请求的顶层传入 `CallbackConfig`： ```JSON { "BasicConfig": {}, "Source": {}, "Target": {}, "CallbackConfig": { "CallbackUrl": "https://example.com/dms/callback", "CallbackStates": [ "SUCCESS", "FAILURE" ], "CustomParams": { "BusinessId": "order-20260804-001" } } } ``` 请求参数 |参数 |类型 |是否必填 |说明 | |---|---|---|---| |CallbackUrl |String |是 |接收回调的完整 URL。仅支持 `http` 和 `https`，必须包含有效 Host。生产环境建议使用 HTTPS。 | |CallbackHost |String |否 |自定义 HTTP HOST 请求头。不能包含空白、控制字符、协议、路径、查询参数或 Fragment。通常无需配置。 | |CallbackStates |Array of String |否 |指定需要接收回调通知的任务状态集合，用于控制回调触发范围。使用时需注意：

* **必须配置**：启用回调通知时，请至少配置一个状态；`CallbackStates` 为空或包含非法值时接口仍可能保存成功，但不会触发任何回调。

* **区分大小写**：状态名严格区分大小写，V1 不会自动转换或兼容别名。

* **精确匹配**：服务端按字符串精确匹配，传入值的写法在当前版本内部状态均为全大写。

取值如下：

* SUCCESS：任务迁移成功。

* STOPPED：任务已停止。

* FAILURE：任务迁移失败。 | |CustomParams |Map |否 |自定义键值对。DMS 会将其合并到回调 JSON Body 中。 | |CallbackStatus |String |否 |只读字段。表示最近一次回调投递状态，创建或更新任务时传入的值不会生效。 | 例如，仅关注成功和失败时，`CallbackStates` 应配置： ```JSON { "CallbackStates": [ "SUCCESS", "FAILURE" ] } ``` ## 回调请求 ### 请求方式 DMS 向 `CallbackUrl` 发送 HTTP POST 请求，请求体格式为 `application/json`。您的回调服务应满足以下方式： * 在收到并成功受理请求后返回 `HTTP` 成功状态。 * 尽快返回响应，不要在回调请求中执行长耗时同步操作。 * 先持久化事件，再异步执行后续业务逻辑。 * 对重复请求进行幂等处理。 ### 请求体 ```JSON { "task_id": 123456, "task_name": "migration-task", "status": "SUCCESS", "trans_ok": 1000, "BusinessId": "order-20260804-001" } ``` |参数 |类型 |说明 | |---|---|---| |task_id |Integer |迁移任务 ID。 | |task_name |String |迁移任务名称。 | |status |String |触发本次回调的 V1 任务内部状态。 | |trans_ok |Integer |已成功迁移的对象数量。 | |其他字段 |String |创建任务时配置的 CustomParams。 | ### CustomParams 合并规则 * `CustomParams` 会作为顶层字段合并到回调请求体中。 * 以下字段为系统保留字段：`task_id`、`task_name`、`status`、`trans_ok`。 * 当 `CustomParams` 中的 Key 与系统保留字段重名时，系统字段优先，自定义值不会覆盖系统字段。 * 建议使用业务前缀命名自定义参数，例如 `business_order_id`，避免与后续新增的系统字段冲突。 ## 查询回调状态创建任务后，可通过以下接口查询 `CallbackConfig`：`QueryDataMigrateTask` 的 `Result.CallbackConfig`。返回示例： ```JSON { "CallbackConfig": { "CallbackUrl": "https://example.com/dms/callback", "CallbackStates": [ "Finished", "Failed" ], "CustomParams": { "BusinessId": "order-20260804-001" }, "CallbackStatus": "Success" } } ``` `CallbackStatus` 取值如下： |状态 |说明 |是否允许人工重试 | |---|---|---| |Waiting |已配置回调，但尚未进入投递流程，或当前任务状态未命中订阅状态。 |否 | |Pending |回调正在投递。 |通常否；持续超过 5 分钟后可重试。 | |Success |最近一次回调投递成功。 |否 | |Failed |最近一次回调投递失败。 |是 |

说明

CallbackStatus 仅表示最近一次回调投递结果，不代表迁移任务本身的状态。

当前仅保留最近一次投递状态，不提供回调历史列表。如果任务先后命中多个订阅状态，后一次投递结果会覆盖前一次 CallbackStatus。

存储迁移服务