The mgwutil create-job command creates a data migration task with scheduling rules and filter conditions by specifying parameters such as source address, destination address, overwrite mode, and transfer mode. - Data Online Migration

You can use the mgwutil create-job command to create a data migration task. This command supports configuration options such as overwrite mode, bandwidth throttling, audit method, and filters.

Command syntax

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

Parameter description

Parameter	Required	Description
job-name	Yes	Task name. Format: Letters, digits, underscores (_), and hyphens (-) are allowed. Length must be 3–63 characters.
--src-address	Yes	Specify the source data address.
--dest-address	Yes	Specify the destination data address.
Overwrite mode
--overwrite-mode	Yes	Use --overwrite-mode and --transfer-mode together as follows: always all: Force full overwrite. Always overwrite the destination file, regardless of whether it has changed. always lastmodified: Overwrite based on modification time. Overwrite only if the source file’s last modified time is later than the destination file’s. never "": Never overwrite. Skip migration if the destination file already exists.
--transfer-mode	Yes
Throttling
--max-bandwidth	No	Maximum bandwidth limit for the task. Unit: bits/s.
--max-qps	No	Maximum QPS limit for the task. Throttling values have an upper bound. For details, see Limits.
Audit method
--create-report	No	Generate a migration report for the task. This is a Boolean flag. If present, reporting is enabled. Default: `false` (do not create).
--log-mode	No	Migration log push method. Possible values: 1. off: Disable. Do not push migration logs. 2. basic: Push only file error logs. 3. detail: Push both file error logs and file migration logs.
Filters
--exclude-dir	No	Exclude all directories during migration. Default: `false` (do not exclude).
--exclude-symlink	No	Exclude all symbolic link files during migration. Default: `false` (do not exclude).
--key-filters-excludes	No	Filename exclusion filter. Supports regular expressions. Separate multiple expressions with commas (,). The logical relationship is OR. Example: `--key-filters-excludes ".\.log,.\.tmp"`
--key-filters-includes	No	Filename inclusion filter. Supports regular expressions. Separate multiple expressions with commas (,). The logical relationship is OR. Example: `--key-filters-includes ".\.jpg,.\.png"`
--last-modified-filters-excludes	No	Last modified time exclusion filter. Format: `"YYYY-MM-DD HH:MM:SS > YYYY-MM-DD HH:MM:SS"`. Separate multiple time ranges with commas. Enclose the entire value in quotes. Example: `--last-modified-filters-excludes "2023-01-01 00:00:00 > 2023-01-31 23:59:59"`
--last-modified-filters-includes	No	Last modified time inclusion filter. Uses the same format as above.
Migration configuration
--with-storage-class	No	Preserve the StorageClass attribute of files during migration. Limitation: Only effective when both source and destination are OSS. Default: `false`.
--target-storage-class	No	Force all destination files to use a specific storage class. Limitation: Only effective when the destination is OSS. Valid values: `Standard` (Standard), `IA` (Infrequent Access), `Archive` (Archive Storage), `ColdArchive` (Cold Archive), `DeepColdArchive` (Deep Cold Archive).
--with-last-modify-time	No	Preserve the original `lastModifyTime` (last modified time) after migration. Default: `true` (preserve).
--parent-version	No	Specify the parent task ID. (Required only when creating a child task.) Important When creating a child task, you must provide the `version` field of its parent task. The system performs the following checks: Parent task existence: The specified parent task must exist. Parent task status: The parent task must not be in the `deleting` state. If either check fails, the child task creation request is rejected and an error code is returned.
--convert-symlink-target	No	Convert the target of symbolic links (symlinks). Default: `false` (do not convert; keep the symlink target consistent with the source file).
--appendable-to-normal	No	Convert appendable files from the source into normal or multipart files during migration. Default: `false`.
Scheduling rules
--max-schedule-count	No	Maximum number of executions for a periodically scheduled task. After reaching this limit, the task stops automatic scheduling but can still be manually triggered.
--start-cron-expression	No	Task start scheduling rule. Use a standard 6-field cron expression (seconds minutes hours day month weekday). Example: `"0 0 2 * * *"` starts the task daily at 2:00 AM.
--suspend-cron-expression	No	Task suspend scheduling rule. Uses the same format as above.

Usage example

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"

Response

Success response

{
    "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"
    }
}

Failure response

{
  "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"
}

Error codes

Note

Error codes indicate error categories. For details, see the error message (ErrorMsg).
This list includes common error codes.

ErrorCode	Description
ImportJobDepthExceed	Nesting depth of child tasks exceeds the system limit. Reduce task nesting levels.
ImportJobNumExceed	Number of tasks exceeds the default limit. Reduce the number of tasks and retry.
ImportJobAlreadyExist	A task with the same name already exists. Use a unique name or delete the existing task first.
NoSuchImportAddress	The specified address does not exist. Check that the address configuration name is correct.
NoSuchImportJobParent	The parent task does not exist. Ensure the specified parent task has been created and the ID is correct.
ImportJobRepeatedOnSameAddress	A task with the same source and destination addresses already exists. Avoid duplicate creation.