使用mgwutil的create-job命令创建并配置迁移任务-在线迁移服务-阿里云

使用 mgwutil create-job 命令创建一个迁移任务，支持覆盖方式、限流、审计方式、过滤器等配置。

命令格式

mgwutil create-job <job-name> \
--src-address <value>  --dest-address <value> \
--overwrite-mode <value> --transfer-mode <value> \
[--max-bandwidth <value>] [--max-qps <value>]...

参数说明

参数	必填	说明
job-name	是	任务名称。格式：支持字母、数字、下划线（_）和短划线（-）。长度为 3~63 个字符。
--src-address	是	指定源端数据地址。
--dest-address	是	指定目的端数据地址。
覆盖方式
--overwrite-mode	是	--overwrite-mode 、--transfer-mode 需按照如下方式组合使用： always all 强制全覆盖：无论文件是否变化，始终覆盖目标文件。 always lastmodified 按修改时间覆盖：仅当源文件的最后修改时间晚于目标文件时，才执行覆盖。 never "" 永不覆盖：若目标文件已存在，则跳过迁移。
--transfer-mode	是
限流
--max-bandwidth	否	任务的最大带宽限制。单位：bits/s。
--max-qps	否	任务的最大 QPS 限制。限流值有上限，详情请参见使用限制。
审计方式
--create-report	否	是否为任务生成迁移报告。此为布尔标志，出现即表示启用。默认值：`false`（不创建）。
--log-mode	否	迁移日志推送方式，可能值： 1.off：关闭，不推送迁移日志； 2.basic：仅推送文件错误日志； 3.detail：推送文件错误日志和文件迁移日志。
过滤器
--exclude-dir	否	是否在迁移中排除所有目录。默认值：`false`（不排除）。
--exclude-symlink	否	是否在迁移中排除所有软链接文件。默认值：`false`（不排除）。
--key-filters-excludes	否	文件名排除过滤器，支持正则表达式。多个表达式用逗号（,）分隔，逻辑关系为“或”。示例：`--key-filters-excludes ".\.log,.\.tmp"`
--key-filters-includes	否	文件名包含过滤器，支持正则表达式。多个表达式用逗号（,）分隔，逻辑关系为“或”。示例：`--key-filters-includes ".\.jpg,.\.png"`
--last-modified-filters-excludes	否	最后修改时间排除过滤器。格式为 `"YYYY-MM-DD HH:MM:SS > YYYY-MM-DD HH:MM:SS"`，多个时间段用逗号分隔。建议使用引号将整个值包围。示例：`--last-modified-filters-excludes "2023-01-01 00:00:00 > 2023-01-31 23:59:59"`
--last-modified-filters-includes	否	最后修改时间包含过滤器，格式同上。
迁移配置
--with-storage-class	否	是否在迁移过程中同步文件的存储类型（StorageClass）属性。限制：仅在源端和目的端均为 OSS 时生效。默认值：`false`。
--target-storage-class	否	强制指定目的端所有文件的存储类型。限制：仅在目的端为 OSS 时生效。可选值：`Standard`（标准存储）、`IA`（低频访问存储）、`Archive`（归档存储）、`ColdArchive`（冷归档存储）、`DeepColdArchive`（深度冷归档存储）。
--with-last-modify-time	否	是否在迁移后保留文件的原始 `lastModifyTime`（最后修改时间）。默认值：`true`（保留）。
--parent-version	否	指定父任务 ID。（该参数仅在创建子任务时必填）。重要当创建子任务时，必须提供其父任务的 `version` 字段。系统将执行以下校验：父任务存在性检查：指定的父任务必须已存在；父任务状态检查：父任务不得处于 `deleting`（删除中）状态。若上述任一校验失败，子任务创建请求将被拒绝，并返回相应错误码。
--convert-symlink-target	否	是否转换软链接（symlink）指向的目标文件。默认值：`false`（不转换，目的软链接target和源端文件保持一致）。
--appendable-to-normal	否	是否将源端的可追加（appendable）类型文件转换为普通（normal）或分片（multipart）文件进行迁移。默认值：`false`。
调度规则
--max-schedule-count	否	周期性调度任务的最大执行轮次，达到轮次限制后任务将不再自动调度，但仍能手动调度。
--start-cron-expression	否	任务启动调度规则。使用标准的 6 位 Cron 表达式（秒分时日月周）。示例：`"0 0 2 * * *"` 表示每天凌晨 2 点启动任务。
--suspend-cron-expression	否	任务暂停调度规则。格式同上。

使用示例

mgwutil create-job "full-migration-job" \
--src-address "oss-src-address" --dest-address "oss-dest-address" \
--overwrite-mode always --transfer-mode all \
--start-cron-expression "0 0 2 * * *" --max-schedule-count 10 \
--key-filters-includes "(.*).gif, (.*).pdf" \
--last-modified-filters-includes "2025-07-03 00:00:00 > 2025-07-04 00:00:00"

返回结果

成功返回

{
    "Code": "success",
    "StatusCode": 200,
    "LogTime": "2025-12-25 17:51:37",
    "Data": {
        "JobName": "daily-backup-job",
        "Version": "a1b2c3d4-e5f6-7890-1234-abcdef123456",
        "CreateTime": "2025-07-17T13:39:25.000Z",
        "Status": "IMPORT_JOB_BEGIN",
        "SrcAddr": "nas-agent-data",
        "DestAddr": "oss-agent-backup"
    }
}

失败返回

{
  "Code": "fail",
  "StatusCode": 404,
  "LogTime": "2026-01-16 13:55:52",
  "ErrorMsg": "SDKError:    StatusCode: 404    Code: NoSuchImportAddress    Message: The specified import address does not exist    Data: {'AccessDeniedDetail':null,'Recommend':null,'ecCode':null,'hostId':'1***09****69****.cn-hangzhou.mgw.aliyuncs.com','requestId':'6969D2E89367063631F7AB51','statusCode':404} ",
  "ErrorCode": "NoSuchImportAddress",
  "RequestId": "6969D2E89367063631F7AB51"
}

错误码

说明

错误码表示错误类别，详情请参考错误信息（ErrorMsg）。
此错误码包含通用错误码。

ErrorCode	说明
ImportJobDepthExceed	子任务嵌套深度超过系统限制，请减少任务层级嵌套。
ImportJobNumExceed	任务数量超过默认限制，请减少任务数量后重试。
ImportJobAlreadyExist	同名任务已存在，请使用唯一名称或先删除现有任务。
NoSuchImportAddress	指定的地址不存在，请检查地址配置项名称是否正确。
NoSuchImportJobParent	父任务不存在，请确保指定的父任务已创建且 ID 正确。
ImportJobRepeatedOnSameAddress	源地址与目的地址相同的任务已存在，请避免重复创建。