配置任务
更新时间：2025-08-21
接口说明
配置传输任务，内容包括传输对象的映射关系，数据库连接信息等。
任务配置范围：
配置任务接口仅限任务状态为：'ready', 'checkPass', 'checkFailed', 'runFailed', 'stopped', 'configFailed', 'unConfig'时可以配置
请求结构
JSON
1POST /v{version}/task/{dtsId}/config
2Host: dts.baidubce.com
3Authorization: authorization string
4{
5 "taskName": "dtsmxxxxxxxxx"
6 "type": "migration",
7 "granularity" : "instance",
8 "dataType" : [ "base" ],
9 "srcConnection" : {
10 "dbPass" : "dbPass",
11 "dbPort" : 3306,
12 "instanceId" : "rdsmfgdti3d53f5",
13 "instanceType" : "bcerds",
14 "dbUser" : "_dts_trans_",
15 "dbType" : "mysql",
16 "dbHost" : "192.168.1.1",
17 "region" : "bj",
18 "field_whitelist" : "test.table_src[k,c];",
19 "field_blacklist" : "test.table_src[k2,c2]",
20 },
21 "dstConnection" : {
22 "dbPass" : "dbPass",
23 "dbPort" : 3306,
24 "instanceId" : "rdsmfgdtisfsfds",
25 "instanceType" : "bcerds",
26 "dbUser" : "_dts_trans_2",
27 "dbType" : "mysql",
28 "dbHost" : "192.168.1.2",
29 "region" : "bj"
30 },
31 "schemaMapping" : [ {
32 "dst" : "test.table_dst",
33 "src" : "test.table_src",
34 "where" : "id > 1 AND status = 'success'",
35 "type" : "table"
36 }],
37}请求体参数
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 | 参数位置 |
|---|---|---|---|---|---|
| version | String | 是 | API版本号 | "1" | URL参数 |
| dtsId | String | 是 | 任务ID | "dtsmxxxyyy" | URL参数 |
| type | String | 是 | 任务类型（数据传输任务：migration），目前仅支持数据传输任务 | migration | Request Body 参数 |
| dataType | String[] | 是 | 传输数据类型数组（schema：结构迁移；base：全量迁移；increment：增量迁移） | ["base"] | Request Body 参数 |
| taskName | String | 是 | 任务名称 | dtsmxxxxxx | Request Body 参数 |
| srcConnection | Connection | 是 | 源端 | srcConnection | Request Body 参数 |
| dstConnection | Connection | 是 | 目标端 | dstConnection | Request Body 参数 |
| granularity | String | 是 | 传输任务的粒度（instance：实例级；dbtb：库表级） | instance | Request Body 参数 |
| schemaMapping | Schema[] | 是 | schema | schema | Request Body 参数 |
| accountMapping | AccountMapping[] | 否 | 账号迁移 | accountMapping | Request Body 参数 |
| incrIgnoreType | String | 否 | 特殊DDL过滤 | drop,truncate | Request Body 参数 |
| initPosition | InitPosition | 否 | 自定义同步点 | initPosition | Request Body 参数 |
Connection字段数据结构说明
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 |
|---|---|---|---|---|
| instanceType | String | 是 | 实例类型 | bcerds |
| region | String | 是 | 地域 | bj |
| dbType | String | 是 | 数据库类型 | mysql |
| dbUser | String | 否 | 数据库访问账号 | dts_trans |
| dbPass | String | 否 | 数据库访问密码 | |
| dbPort | Integer | 否 | 数据库访问端口 | 3306 |
| dbHost | String | 否 | 数据库IP或主机名 | 192.168.1.1 |
| dbName | String | 否 | 数据库名称 | mssql_datatype |
| instanceId | String | 否 | 实例ID | rdsmfgdti3d53f5 |
| dbServer | String | 否 | 数据库IP或主机名。支持IP：端口，IP或域名与端口以英文冒号分隔，多个地址以英文逗号分隔 | 192.168.1.1:3306 |
| clusterTopo | String | 否 | 接入类型为自建接入类型，数据类型为redisCluster、openRedisCluster时需要填写，配置中填写了clusterTopo后，无需再填写dbServer，建议删除dbServer字段 | 172.0.0.1:6379,172.0.0.2:6379;172.0.1.1:6379,172.0.1.2:6379;172.0.2.1:6379,172.0.2.2:6379 |
| shardUrl | String | 否 | 分片IP或主机名。支持IP：端口，IP或域名与端口以英文冒号分隔，多个地址以英文逗号分隔 注意： .Redis可支持同时设置不同分片及同一分片不同节点的IP：端口，当源端/目标端主从切换等导致的原有主节点变动时，可自动寻主，提升传输链路高可用能力。当您需要同时设置链路高可用时，需按分片维度分别填写主从IP：端口，各分片之间IP/端口以英文分号分隔，同一分片不同节点之间以英文逗号分隔。当您无需设置链路高可用时，不同分片之间英文分号间隔即可· 分片集MongoDB可支持同时设置主从shard的IP：端口，当源端/目标端主从切换等导致的原有主节点变动时，可自动寻主，提升传输链路高可用能力。当您需要同时设置主从shard 的IP：端口时，需按shard维度分别填写主从shard的IP：端口，主从shard 地址之间以英文逗号分隔，不同shard之间以分号分隔 | 192.168.1.1:3306,192.168.1.1:3306 |
| announceServer | String | 否 | redis cluster announce IP/Port。若redis cluster低于4.0或未设置announce IP/Port该字段填空即可。长度限制10240 | 192.168.1.1:3306,192.168.1.1:3306(与dbServer一一对应) |
| field_whitelist | FieldWhitelist | 否 | 列过滤（白名单） | "db.table[列名1、列名2..];db2.table[列名1, 列名2...]" |
| field_blacklist | FieldBlacklist | 否 | 列过滤（黑名单） | "db.table[列名1、列名2..];db2.table[列名1, 列名2...]" |
| srcDstFlag | String | 否 | 公有云上redis实例：必选，标识公有云上实例源端和目标端 源端取值"src"，目标端取值"dst" 非公有云，非redis实例：可为空 |
src |
| supportOnlineDDL | String | 否 | 同步Online DDL，同步Online DDL会引起目标端数据替换，可能出现同步失败或目标端数据丢失 | true，false |
| maxRetryTime | String | 否 | 重试时间，源库、目标库无法连接后自动重试，用户可根据实际情况， 调整重试时间，或者在源端和目标端的实例释放后尽快释放DTS实例 | 720 |
| sqlType | String | 否 | 同步语句选择 | I,U,D,Q (I:INSERT, U:UPDATE, D:DELETE, Q:DDL) |
| positionStrategy | String | 否 | 可选值：fail（如果给定offset不存在，这任务报错退出） base（如果给定offset不存在，则任务从全量开始重新同步） | fail |
| zone | String | 否 | 接入类型为bcegateway时，需要指定可用区 | cn-bd-a |
| vpcShortId | String | 否 | 接入类型为bcegateway时，需要指定VPC短ID | vpc-46k27rb9wppz |
| subnetShortId | String | 否 | 接入类型为bcegateway时，需要指定子网短ID | sbn-qtm3d4eituqc |
| version | String | 否 | 接入类型为kafka时，需要指定kafka版本 | 0.9.0.1 |
| brokers | String | 否 | 接入类型为kafka时，需要指定Broker列表 | 10.152.80.28:9092 |
| topic | String | 否 | 接入类型为kafka时，需要指定topic | 10.152.80.29:9092 |
| control | String | 否 | 接入类型为kafka时，需要指定访问控制类型 | "" |
| sid | String | 否 | 接入类型为oracle时，需要指定Service Name | DCLHR |
| charset | String | 否 | 接入类型为oracle时，需要指定导出类型 | ""；ZHS16GBK；UTF8 |
| incrType | String | 否 | 物化视图日志：mlog ，归档日志：logminer | mlog |
| mqPartitionRule | String | 否 | 目标端为kafka rocketMQ数据类型时，可填写 | 示例："table";可选值：table（按库名 + 表名分配）、primaryKey（按主键分配）、field（按指定列分配） |
| mqPartitionField | String | 否 | 目标端消息队列指定mqPartitionRule为field时，具体的指定列规则 | 示例:"testdb1.testtbl1[id];testdb2.testtbl1[id]" |
| mqProtocol | String | 否 | 目标端为kafka rocketMQ数据类型时需要指定，可填写消息格式 | BAIDU_JSON_V1、BAIDU_JSON_V2 |
| messageType | String | 否 | 消息类型 | 可选值：normal(普通消息)、fifo(顺序消息) |
| saslMechanisms | String | 否 | kafka 鉴权机制 | PLAIN、SCRAM-SHA-256、SCRAM-SHA-512 |
| consumerGroup | String | 否 | kafka 设置消费组名称，源端为kafka时，此参数生效 | dtsgxxxxxx |
| useOriginType | String | 是 | "false"、"true"；注意：数据类型为Elasticsearch时需要传此字段； | "false": 字符串（string）- 目标端所有字段类型转为字符串; "true": 原始数据类型-目标端各字段类型与源端一致； |
| baseMaxTps | String | 否 | 迁移限速：全量每秒迁移的行数,每秒钟同步到目标端的行数，值为空或者0时表示不限制迁移速度（如果需要此参数，传参放到srcConnection中） | 10 |
| baseMaxThroughput | String | 否 | 迁移限速：全量每秒迁移的数据量,每秒钟同步到目标端的数据量，值为空或者0时表示不限制迁移速度，单位字节；（如果需要此参数，传参放到srcConnection中） | 1024 |
| incrMaxTps | String | 否 | 迁移限速：增量每秒迁移的行数,每秒钟同步到目标端的行数，值为空或者0时表示不限制迁移速度；（如果需要此参数，传参放到srcConnection中） | 10 |
| incrMaxThroughput | String | 否 | 迁移限速：增量每秒迁移的数据量,每秒钟同步到目标端的数据量，值为空或者0时表示不限制迁移速度，单位字节；（如果需要此参数，传参放到srcConnection中） | 1024 |
Schema字段数据结构说明
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 |
|---|---|---|---|---|
| type | String | 否 | 需要传输的对象类型，取值有：db（库），table（表）， view（视图），function（函数）， procedure（存储过程） | table |
| src | String | 否 | 源库的schema名称 | test.table_src |
| dst | String | 否 | 目标库的schema名称 | test.table_dst |
| where | String | 否 | where 行过滤条件 | where |
| updateTriggerColumns | String | 否 | 更新触发列；符合条件的列被更新之后，该行数据才会被同步，仅对Update语句生效，示例：n1, n2 (只有 n1 或者 n2列被更新之后才同步该数据) | k, pad |
| field | Field | 否 | Field；仅限mysql数据类型支持此字段 | 列名映射 |
Field字段数据结构说明
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 |
|---|---|---|---|---|
| mapping | List<Mapping> | 是 | Mapping |
Mapping字段数据结构说明
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 |
|---|---|---|---|---|
| from | String | 是 | 旧值 | name |
| to | String | 是 | 新值 | new_name |
AccountMapping字段数据结构说明
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 |
|---|---|---|---|---|
| user | String | 否 | 用户 | dts_user |
| hosts | String[] | 否 | 地址 | ["%", "1.2.3.4", "10.10.10.1"] |
InitPosition字段数据结构说明
| 参数名称 | 参数类型 | 是否必须选 | 描述 | 示例值 |
|---|---|---|---|---|
| type | String | 否 | · mysql数据流包括binlog和gtidset两种· redis数据流为offset | offset |
| position | String | 否 | · mysql binlog示例： mysql-bin.000000:123456， binlog文件的起始position值为4· mysql gtidset示例：3f36fc07-d556-11e9-b75c-a0d3c1fa9c05:1-24541631,6a6878f3-27e6-11ea-bfcb-b8599f4c2f78:1-2659 未指定点位默认从最新点位开始迁移· redis实例replication backlog中有效有效的offset值，格式为:"9654766427"。若不填写则标识做全量+增量迁移 | 9654766427 |
响应头参数
除公共头域，无其它特殊头域。
响应体参数
响应体字段数据结构说明
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 |
|---|---|---|---|---|
| dtsId | String | 是 | 任务ID | dtsxxxyyyzzz |
请求示例
JSON
1POST /v1/task/{dtsId}/config
2Host: dts.baidubce.com
3ContentType: application/json
4Authorization: bce-auth-v1/5a6f0606bf5e48f29dd132aa76aa5182/2017-06-12T13:13:05Z/1800/content-type;host;x-bce-date/8baeafe6bfc35b0cf6205e87e4ce6c0dbb442375951ace4d16e6c7a4dab95943
5{
6 "taskName": "dtsmxxxxxx",
7 "type": "migration",
8 "granularity" : "instance",
9 "schemaMapping" : [ {
10 "dst" : "test.table_dst",
11 "src" : "test.table_src",
12 "where" : "where",
13 "type" : "table"
14 } ],
15 "dataType" : [ "base" ],
16 "srcConnection" : {
17 "dbPass" : "dbPass",
18 "dbPort" : 3306,
19 "instanceId" : "rdsmfgdti3d53f5",
20 "instanceType" : "bcerds",
21 "dbUser" : "_dts_trans_",
22 "field_whitelist" : "field_whitelist",
23 "dbType" : "mysql",
24 "dbHost" : "192.168.1.1",
25 "field_whitelist" : "test.table_src[k,c];",
26 "field_blacklist" : "test.table_src[k2,c2]",
27 "region" : "bj",
28 },
29 "dstConnection" : {
30 "dbPass" : "dbPass",
31 "dbPort" : 3306,
32 "instanceId" : "rdsmfgdtisfsfds",
33 "instanceType" : "bcerds",
34 "dbUser" : "_dts_trans_2",
35 "dbType" : "mysql",
36 "dbHost" : "192.168.1.2",
37 "region" : "bj"
38 }
39}响应示例
JSON
1HTTP/1.1 200 OK
2
3{
4 "dtsId" : "dtsxxxyyyzzz"
5}Connection (数据类型：mysql)
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 | 备注 |
|---|---|---|---|---|---|
| instanceType | String | 是 | 接入类型 | bcerds; 枚举：bcebcc、bcedcc、bcebbc、bceet、bcegateway、public | |
| region | String | 是 | 地域 | bj;枚举：gz、su、bd、fwh、hkg、cd | |
| dbType | String | 是 | 数据库类型 | mysql | |
| dbUser | String | 否 | 数据库访问账号 | dts_trans | 接入类型为自建时需要传，如：bcebcc、bcebbc、bcedcc、bceddc、bceet、bcegateway、public |
| dbPass | String | 否 | 数据库访问密码 | 接入类型为自建时需要传 | |
| dbPort | Integer | 否 | 数据库访问端口 | 3306 | 接入类型为自建时需要传 |
| dbHost | String | 否 | 数据库IP或主机名 | 192.168.1.1 | 接入类型为：public, bceet, bcegateway |
| dbName | String | 否 | 数据库名称 | mssql_datatype | 接入类型为自建时需要传 |
| instanceId | String | 否 | 实例ID | rdsmfgdti3d53f5 | 接入类型为bcerds、bcebcc、bcedcc、bcebbc、bceddc |
| vpcId | String | 否 | vpc短ID | vpc-46k27rb9wppz | 接入类型为：bceet、bcegateway时需要指定VPC短ID |
| subnetShortId | String | 否 | 子网短ID | sbn-qtm3d4eituqc | 接入类型为bcegateway时，需要指定子网短ID |
| zone | String | 否 | 可用区 | cn-bd-a | 接入类型为bcegateway时，需要指定可用区 |
Connection （数据类型：rocketMQ）
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 | 备注 |
|---|---|---|---|---|---|
| instanceType | String | 是 | 接入类型 | public 枚举：bcebcc、bcedcc、bcebbc、bceet、bcegateway、public | |
| region | String | 是 | 地域 | bj;枚举：gz、su、bd、fwh、hkg、cd | |
| dbType | String | 是 | 数据库类型 | rocketmq | |
| accessKey | String | 否 | 鉴权AK | 12345 | |
| secretKey | String | 否 | 鉴权SK | qertyu | |
| grpcPort | Integer | 是 | GRPC协议端口 | 3306 | |
| dbHost | String | 否 | 数据库IP或主机名 | 192.168.1.1 | |
| topic | String | 是 | 主题 | test_topic_1 | |
| messageType | String | 是 | 消息类型 | normal | RocketMQ 消息类型。可选值：normal(普通消息)、fifo(顺序消息) |
| vpcShortId | String | 是 | vpc短ID | vpc-46k27rb9wppz | 接入类型为：bceet、bcegateway时需要指定VPC短ID |
| subnetShortId | String | 是 | 子网短ID | sbn-qtm3d4eituqc | 接入类型为bcegateway时，需要指定子网短ID |
| mqPartitionRule | String | 否 | 目标端消息队列消息分区规则 | table | 可选值：table（按库名 + 表名分配）、primaryKey（按主键分配）、field（按指定列分配） |
| mqPartitionField | String | 否 | 目标端消息队列指定mqPartitionRule为field时，具体的指定列规则 | testdb1.testtbl1[id];testdb2.testtbl1[id] | |
| mqProtocol | String | 是 | 消息格式 | BAIDU_JSON_V1、BAIDU_JSON_V2 | |
| sqlType | String | 是 | 同步语句选择 | I,U,D |
Connection（数据类型：kafka）
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 | 备注 |
|---|---|---|---|---|---|
| instanceType | String | 是 | 接入类型 | public; 枚举：bcebcc、bcedcc、bcebbc、bceet（vpc接入）、bcegateway（专线接入）、public(自建)、bcebms（ 百度消息服务-共享版）、bcebmscluster（百度消息服务-专享版） | |
| region | String | 是 | 地域 | bj;枚举：gz、su、bd、fwh、hkg、cd | |
| dbType | String | 是 | 数据库类型 | kafka | |
| broker | String | 是 | 数据类型为kafka时，需要指定Broker列表 | 10.12.80.28:8092,11.12.82.29:9092 | |
| dbUser | String | 否 | 用户名 | admin | |
| dbPass | String | 否 | 密码 | admin | |
| saslMechanisms | String | 否 | 鉴权机制 | PLAIN、SCRAM-SHA-256、SCRAM-SHA-512 | 接入类型为自建时，此参数才生效。当saslMechanisms有值时，需要填写dbUser、dbPass |
| buffer | Integer | 是 | 本地内存缓冲消息个数 | 1000 | |
| dbHost | String | 否 | 数据库IP或主机名 | 192.168.1.1 | |
| topic | String | 是 | 主题 | dtstest123 | |
| version | String | 否 | 版本 | 0.9.0.1 | 10.10.2.1 |
| mqPartitionRule | String | 否 | 目标端消息队列消息分区规则 | table | 可选值：table（按库名 + 表名分配）、primaryKey（按主键分配）、field（按指定列分配） |
| mqPartitionField | String | 否 | 目标端消息队列指定mqPartitionRule为field时，具体的指定列规则 | testdb1.testtbl1[id];testdb2.testtbl1[id] | |
| mqProtocol | String | 是 | 消息格式 | BAIDU_JSON_V1、BAIDU_JSON_V2 | |
| sqlType | String | 是 | 同步语句选择 | I,U,D,Q | Q必须填 |
| consumerGroup | String | 否 | 设置消费者组名称 | dtsgxxxxxx | 由字母组成的字符串即可 |
Connection（数据类型：elasticsearch）
| 参数名称 | 参数类型 | 是否必选 | 描述 | 示例值 | 备注 |
|---|---|---|---|---|---|
| instanceType | String | 是 | 接入类型 | public; 枚举：bcebes（百度elasticsearch）、bcebcc、bcedcc、bcebbc、public(自建) | |
| region | String | 是 | 地域 | bj;枚举：gz、su、bd、fwh、hkg、cd | |
| dbType | String | 是 | 数据库类型 | elasticsearch | |
| instanceId | String | 否 | bcebes（百度elasticsearch），需要指定instanceId | ||
| dbUser | String | 否 | 用户名 | admin | |
| dbPass | String | 否 | 密码 | admin | |
| insertType | String | 是 | 插入方式 | 枚举： " "、 upsert | upsert |
| buffer | Integer | 是 | 本地内存缓冲消息个数 | 1000 | |
| dbHost | String | 否 | 数据库IP或主机名 | 192.168.1.1 | |
| topic | String | 是 | 主题 | dtstest123 | |
| version | String | 否 | 版本 | 0.9.0.1 | 10.10.2.1 |
| sqlType | String | 是 | 同步语句选择 | I,U,D | |
| useOriginType | String | 是 | "false"、"true" | "false": 字符串（string）- 目标端所有字段类型转为字符串; "true": 原始数据类型-目标端各字段类型与源端一致 |