Creates a backup plan.

Description

  • A backup plan includes a data source, backup policies, and other backup details. After you execute a backup plan, a backup job is generated to record the backup progress and the backup result. If a backup job is complete, a backup snapshot is generated. You can use a backup snapshot to create a restore job.
  • You can specify only one data source in a backup plan.
  • You can specify only one interval as a backup cycle in a backup plan.
  • Each backup plan allows you to back up data to only one backup vault.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateBackupPlan

The operation that you want to perform. Set the value to CreateBackupPlan.

SourceType String Yes ECS_FILE

The type of the data source. Valid values:

  • ECS_FILE: The system backs up data from Elastic Compute Service (ECS) instances.
  • OSS: The system backs up data from Object Storage Service (OSS) buckets.
  • NAS: The system backs up data from Apsara File Storage NAS file systems.
PlanName String Yes planname

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

BackupType String Yes COMPLETE

The type of the backup. Valid value: COMPLETE: full backup.

VaultId String Yes v-0006******q

The ID of the backup vault.

Schedule String Yes I|1602673264|P1D

The backup policy. Format: I|{startTime}|{interval}. The expression specifies that the system runs the first backup job at a point in time that is specified in the {startTime} parameter and the subsequent backup jobs at an interval that is specified in the {interval} parameter. The system does not run a backup job before the specified point in time. Each backup job, except the first one, starts only after the previous backup job is complete. For example, I|1631685600|P1D specifies that the system runs the first backup job at 2021-09-15 14:00:00 and the subsequent backup jobs once a day.

  • startTime: the time at which the system starts to run a backup job. The time follows the UNIX time format. Unit: seconds.
  • interval: the interval at which the system runs a backup job. The interval must follow the ISO8601 standard. For example, PT1H indicates an interval of 1 hour. P1D indicates an interval of one day.
Retention Long Yes 7

The retention period of the backup. Minimum value: 1. Unit: days.

FileSystemId String No 005494

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

CreateTime Long No 1607436917

This parameter is required only if the SourceType parameter is set to NAS. The time when you want to create the file system. The time must be in the UNIX format. Unit: seconds.

Bucket String No hbr-backup-oss

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

Prefix String No oss-prefix

This parameter is required only if the SourceType parameter is set to OSS. This parameter specifies a prefix. After a prefix is specified, only objects whose names start with the prefix are backed up.

InstanceId String No i-m5e*****6q

This parameter is required only if the SourceType parameter is set to OSS. This parameter specifies the ID of the ECS instance.

SpeedLimit String No 0:24:5120

This parameter is required only if the SourceType parameter is set to ECS_FILE. This parameter indicates the throttling rules. Format: {start}|{end}|{bandwidth}. Multiple throttling rules are separated by vertical bars (<codeph>|</codeph>). A specified time range cannot overlap with another time range.

  • start: the start time.
  • end: the end time.
  • bandwidth: bandwidth. Unit: KB per second.
Include String No ["/home/alice/*.pdf", "/home/bob/*.txt"]

This parameter is required only if the SourceType parameter is set to ECS_FILE. This parameter specifies the paths to the files that you want to back up. The value must be 1 to 255 characters in length.

Exclude String No ["/var", "/proc"]

This parameter is required only if the SourceType parameter is set to ECS_FILE. This parameter indicates the paths to the files that are excluded from the backup job. The value must be 1 to 255 characters in length.

Options String No {"UseVSS":false}

This parameter is required only if the SourceType parameter is set to ECS_FILE. This parameter specifies whether to use Windows VSS to define a backup path.

  • This parameter is available only for Windows ECS instances.
  • If data changes occur in the backup source, the source data must be the same as the data to be backed up before the system sets this parameter to ["UseVSS":true].
  • If you use VSS, you cannot back up data from multiple directories.
Path.N String No ["/home"]

The backup path. The value must be 1 to 65,536 characters in length.

Specify a source path based on the following rules:

  • If the source path does not contain an asterisk (*) wildcard, you can enter up to eight source paths.
  • If the source path contains an asterisk (*) wildcard, you can enter only a single path. The path can be in the /*/* format.
  • Only absolute paths are supported.
  • If VSS backup is used, you can enter only one path. UNC paths and wildcards (*) are not supported. You cannot exclude files from the backup plan.
  • If UNC paths are used, VSS paths and wildcards (*) are not supported. You cannot exclude files from the backup plan. If a UNC path is specified, HBR does not back up the access control list (ACL) of Windows.

Response parameters

Parameter Type Example Description
Code String 200

The HTTP status code. The status code 200 indicates that the request is successful.

Message String successful

The message that is returned. If the request is successful, a value of successful is returned. If the request fails, an error message is returned.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

PlanId String plan-*********************

The ID of the backup plan.

Success Boolean true

Indicates whether the request is successful. Valid values:

  • true: The request is successful.
  • false: The request failed.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateBackupPlan
&SourceType=ECS_FILE
&PlanName=planname
&BackupType=COMPLETE
&VaultId=v-0006******q
&Schedule=I|1602673264|P1D
&Retention=7
&FileSystemId=005494
&CreateTime=1607436917
&Bucket=hbr-backup-oss
&Prefix=oss-prefix
&InstanceId=i-m5e*****6q
&SpeedLimit=0:24:5120
&Include=["/home/alice/*.pdf", "/home/bob/*.txt"]
&Exclude=["/var", "/proc"]
&Options={"UseVSS":false}
&Path=["[\"/home\"]"]
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateBackupPlanResponse>
    <Code>200</Code>
    <Message>successful</Message>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <PlanId>plan-*********************</PlanId>
    <Success>true</Success>
</CreateBackupPlanResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

For a list of error codes, visit the API Error Center.