文档中心

存储迁移服务

任务回调

回调操作

本文档介绍 DMS 任务回调（Callback）能力的完整用法，帮助您将迁移任务的关键事件实时同步到业务侧系统。

配置回调

CallbackConfig 配置方式。

在 CreateTask 请求的 TaskConfig 中传入 CallbackConfig：

{​
  "TaskName": "migration-task",​
  "TaskType": "HalfManaged",​
  "SourceId": "10001",​
  "DestinationId": "10002",​
  "AgentGroupId": "10003",​
  "TaskConfig": {​
    "OverwritePolicy": "Force",​
    "SkipArchiveObject": true,​
    "CallbackConfig": {​
      "CallbackUrl": "https://example.com/dms/callback",​
      "CallbackStates": [​
        "Finished",​
        "Failed"​
      ],​
      "CustomParams": {​
        "BusinessId": "order-20260804-001"​
      }​
    }​
  }​
}​

请求参数

参数	类型	是否必填	说明
CallbackUrl	String	是	接收回调的完整 URL。仅支持 http 和 https，必须包含有效 Host。生产环境建议使用 HTTPS。
CallbackHost	String	否	自定义 HTTP HOST 请求头。不能包含空白、控制字符、协议、路径、查询参数或 Fragment。通常无需配置。
CallbackStates	Array of String	否	需要接收通知的任务状态。空/错误的状态值可能被创建接口接收并保存，但不会触发任何回调。启用回调通知时应至少配置一个状态。状态名区分大小写，V2 不会自动转换或兼容别名。服务端会进行字符串精确匹配；当前版本使用 PascalCase 状态，取值如下： Finished：任务已完成。 Stopped：任务已停止。 Failed：任务执行失败。
CustomParams	Map<String, String>	否	自定义键值对。DMS 会将其合并到回调 JSON Body 中。
CallbackStatus	String	否	只读字段。表示最近一次回调投递状态，创建或更新任务时传入的值不会生效。

例如，仅关注任务最终结果时，CallbackStates 可配置：

{​
  "CallbackStates": [​
    "Finished",​
    "Failed"​
  ]​
}​

回调请求

请求方式

DMS 向 CallbackUrl 发送 HTTP POST 请求，请求体格式为 application/json。

您的回调服务应满足以下要求：

在收到并成功受理请求后返回 HTTP 成功状态。

尽快返回响应，不要在回调请求中执行长耗时同步操作。

先持久化事件，再异步执行后续业务逻辑。

对重复请求进行幂等处理。

请求体

{​
  "task_id": 123456,​
  "task_name": "migration-task",​
  "status": "Finished",​
  "account_id": 10000001,​
  "BusinessId": "order-20260804-001"​
}​

参数	类型	说明
task_id	Integer	迁移任务 ID。
task_name	String	迁移任务名称。
status	String	触发本次回调的 V2 任务状态。
account_id	Integer	火山引擎账号 ID。
其他字段	String	创建任务时配置的 CustomParams。

CustomParams 合并规则

CustomParams 会作为顶层字段合并到回调请求体中。

以下字段为系统保留字段：task_id、task_name、status、account_id。

当 CustomParams 中的 Key 与系统保留字段重名时，系统字段优先，自定义值不会覆盖系统字段。

建议使用业务前缀命名自定义参数，例如 business_order_id，避免与后续新增的系统字段冲突。

查询回调状态

创建任务后，可通过以下接口查询 CallbackConfig：

GetTask 的 Result.TaskConfig.CallbackConfig

ListTasks 的 Result.ItemList[].TaskConfig.CallbackConfig

返回示例：

{​
  "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。

最近更新时间：2026.08.17 15:49:13

这个页面对您有帮助吗？

有用

无用