All Products
Search

This Product

    Cloud Backup:CreateBackupPlan

    Document Center

    Cloud Backup:CreateBackupPlan

    Last Updated:Mar 27, 2026

    Creates a backup plan.

    Operation description

    Important

    • Call this API to use features such as the basic edition of ECS file backup, cloud disk backup, container backup, the free trial of TableStore backup, archiving, or data synchronization.

    • To use the 30-day free trial for NAS backup or OSS backup, call the CreateTrialBackupPlan operation.

    • To use the standard capabilities of ECS file backup, local file backup, ECS instance backup, NAS backup, OSS backup, or CPFS backup, call the CreatePolicyV2 and CreatePolicyBindings operations.

    • Executing a backup plan creates a backup job to record its progress and result. A successful job generates a backup snapshot, which you can use to create a restore job.

    • A backup plan supports only one data source.

    • A backup plan supports only one backup policy with a fixed-interval cycle.

    • A backup plan can back up to only one backup repository.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    hbr:CreateBackupPlan

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    SourceType

    string

    Yes

    The type of the data source. Valid values:

    • ECS_FILE: Backs up files from ECS instances.

    • OSS: Backs up OSS buckets.

    • NAS: Backs up NAS file systems.

    • OTS: Backs up Tablestore instances.

    • UDM_ECS: Backs up an entire ECS instance.

    • SYNC: Performs data synchronization.

    ECS_FILE
    PlanName

    string

    No

    The name of the backup plan. The name must be 1 to 64 characters in length. The name must be unique for each data source type within a backup repository.

    planname
    BackupType

    string

    No

    The backup type. Set the value to COMPLETE, which specifies a full backup.

    COMPLETE
    VaultId

    string

    No

    The ID of the backup repository.

    v-0006******q
    Schedule

    string

    No

    The backup policy. The format is I|{startTime}|{interval}. This specifies that a backup job runs at an interval of {interval}, starting from {startTime}. Overdue backup jobs are not retried. If the previous backup job is not complete, the next backup job is not triggered. For example, I|1631685600|P1D indicates that a backup job runs daily starting from 14:00:00 on September 15, 2021.

    • startTime: The start time for the backup, specified as a UNIX timestamp in seconds.

    • interval: The backup interval, specified in the ISO 8601 duration format. For example, PT1H represents one hour and P1D represents one day.

    I|1602673264|P1D
    Retention

    integer

    No

    The backup retention period, in days. The minimum value is 1.

    7
    ClusterId

    string

    No

    The ID of the client group that runs the data synchronization job. This parameter is required only if SourceType is set to SYNC.

    cl-***************
    FileSystemId

    string

    No

    The ID of the file system. This parameter is required only if SourceType is set to NAS.

    005494
    CreateTime

    integer

    No

    The time when the file system was created, specified as a UNIX timestamp in seconds. This parameter is required only if SourceType is set to NAS.

    1607436917
    Bucket

    string

    No

    The name of the OSS bucket. This parameter is required only if SourceType is set to OSS.

    hbr-backup-oss
    Prefix

    string

    No

    The prefix of the objects to back up. If specified, only objects with this prefix are backed up. This parameter is required only if SourceType is set to OSS.

    oss-prefix
    InstanceId

    string

    No

    The ID of the ECS instance. This parameter is required only if SourceType is set to ECS_FILE.

    i-m5e*****6q
    Detail

    object

    No

    The details of an entire instance backup, specified as a JSON string.

    • snapshotGroup: Specifies whether to use a snapshot-consistent group. This feature is available only if all disks of the instance are ESSDs.

    • appConsistent: Specifies whether to enable application consistency. This must be used with the preScriptPath and postScriptPath parameters.

    • preScriptPath: The path to the pre-freeze script.

    • postScriptPath: The path to the post-thaw script.

    {\"EnableFsFreeze\":true,\"appConsistent\":false,\"postScriptPath\":\"\",\"preScriptPath\":\"\",\"snapshotGroup\":true,\"timeoutInSeconds\":60}
    UdmRegionId

    string

    No

    The region where the ECS instance is located.

    cn-shanghai
    SpeedLimit

    string

    No

    The traffic shaping policy for the backup. Format: {start}:{end}:{bandwidth}. You can specify multiple rules separated by vertical bars (|). The specified time ranges cannot overlap. This parameter is required only if SourceType is set to ECS_FILE.

    • start: The start hour.

    • end: The end hour.

    • bandwidth: The bandwidth limit, in KB/s.

    0:24:5120
    Include

    string

    No

    The paths of the files and directories to include in the backup. The path can be up to 255 characters in length. This parameter is required only if SourceType is set to ECS_FILE.

    ["/home/alice/*.pdf", "/home/bob/*.txt"]
    Exclude

    string

    No

    The paths of the files and directories to exclude from the backup. The path can be up to 255 characters in length. This parameter is required only if SourceType is set to ECS_FILE.

    ["/var", "/proc"]
    Options

    string

    No

    Specifies whether to use Windows Volume Shadow Copy Service (VSS) to ensure data consistency. This parameter is required only if SourceType is set to ECS_FILE.

    • This feature is available only for Windows ECS instances.

    • If data in the backup source changes during the backup, set this parameter to {"UseVSS":true} to ensure data consistency.

    • If you enable VSS, you cannot back up multiple file directories at the same time.

    {"UseVSS":false}
    DataSourceId

    string

    No

    The ID of the source data source. This parameter is required only if SourceType is set to SYNC.

    ds-****************
    Path

    array

    No

    The backup paths.

    string

    No

    A backup path. The path can be up to 65,536 characters in length. The following rules apply to backup paths:

    • If you do not use wildcards (*), you can specify up to 20 paths.

    • If you use wildcards (*), you can specify only one path. Wildcard patterns such as /*/* are supported.

    • Each path must be an absolute path.

    • If VSS is enabled, you cannot use multiple paths, UNC paths, wildcards, or file exclusions.

    • When a UNC path is used, VSS, wildcards, and file exclusions are not supported. If the backup source contains UNC paths, Windows ACLs are not backed up.

    ["/home"]
    Rule

    array<object>

    No

    The backup rules.

    object

    No

    A backup rule.

    DestinationRetention

    integer

    No

    The retention period of the geo-redundant backup, in days.

    7
    Schedule

    string

    No

    The backup policy. The format is I|{startTime}|{interval}. This specifies that a backup job runs at an interval of {interval}, starting from {startTime}. Overdue backup jobs are not retried. If the previous backup job is not complete, the next backup job is not triggered. For example, I|1631685600|P1D indicates that a backup job runs daily starting from 14:00:00 on September 15, 2021.

    In the format, startTime is the backup start time (a UNIX timestamp in seconds), and interval is the backup interval (in ISO 8601 duration format). For example, PT1H represents one hour and P1D represents one day.

    I|1602673264|P1D
    Retention

    integer

    No

    The retention period of the backup, in days.

    7
    Disabled

    boolean

    No

    Specifies whether to disable the rule.

    false
    DoCopy

    boolean

    No

    Specifies whether to enable geo-redundancy for the backup.

    false
    DestinationRegionId

    string

    No

    The ID of the destination region for geo-redundancy.

    cn-hangzhou
    RuleName

    string

    No

    The name of the rule.

    rule-test-name
    BackupType

    string

    No

    The backup type.

    COMPLETE
    InstanceName

    string

    No

    The name of the Tablestore instance.

    instancename
    OtsDetail OtsDetail

    No

    The details of the Tablestore instance.

    CrossAccountType

    string

    No

    The type of cross-account backup. Valid values:

    • SELF_ACCOUNT: Backs up data within the same account.

    • CROSS_ACCOUNT: Backs up data to a different account.

    Valid values:

    • SELF_ACCOUNT :

      SELF_ACCOUNT

    • CROSS_ACCOUNT :

      CROSS_ACCOUNT

    CROSS_ACCOUNT
    CrossAccountUserId

    integer

    No

    The ID of the source Alibaba Cloud account for a cross-account backup.

    15897534xxxx4625
    CrossAccountRoleName

    string

    No

    The name of the RAM role that is created in the source account.

    BackupRole
    KeepLatestSnapshots

    integer

    No

    Specifies whether to permanently retain the latest backup snapshots.

    • 0: Do not retain.

    • 1: Retain.

    Valid values:

    • 0 :

      No

    • 1 :

      Yes

    1
    DestSourceType

    string

    No

    The type of the destination data source. This parameter is required only if SourceType is set to SYNC.

    OSS
    DestDataSourceId

    string

    No

    The ID of the destination data source. This parameter is required only if SourceType is set to SYNC.

    ds-*********************

    DestDataSourceDetail

    object

    No

    The details of the destination data source. This parameter is required only if SourceType is set to SYNC.

    {\"prefix\":\"/\"}
    ChangeListPath

    string

    No

    The changelist configuration for incremental file synchronization. This parameter is required only if SourceType is set to SYNC.

    {"dataSourceId": "ds-123456789", "path": "/changelist"}
    Disabled

    boolean

    No

    Specifies whether to disable the backup plan upon creation.

    true
    Edition

    string

    No

    The edition of the backup plan. Valid values are BASIC and STANDARD. Default value: STANDARD.

    STANDARD

    Response elements

    Element

    Type

    Description

    Example

    object

    The data returned.

    Code

    string

    The response code. A value of 200 indicates that the request was successful.

    200
    Message

    string

    The response message. If the request is successful, the value is successful. If the request fails, an error message is returned.

    successful
    RequestId

    string

    The request ID.

    473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
    PlanId

    string

    The backup plan ID.

    plan-*********************
    Success

    boolean

    Indicates whether the request was successful.

    • true: The request was successful.

    • false: The request failed.

    true

    Examples

    Success response

    JSON format

    {
  "Code": "200",
  "Message": "successful",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "PlanId": "plan-*********************",
  "Success": true
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.