Queries one or more backup plans that meet the specified conditions.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeBackupPlans

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

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.
PageNumber Integer No 1

The number of the page to return. Pages start from page 1. Default value: 1.

PageSize Integer No 10

The number of entries to return on each page. Valid values: 1 to 99. Default value: 10.

Filters.N.Key String No vaultId

The keys in the filter. Valid values:

  • RegionId: the ID of a region.
  • restoreId: the ID of a restore job.
  • sourceType: the type of a data source.
  • vaultId: the ID of a backup vault.
  • targetInstanceId: the ID of an ECS instance.
  • targetBucket: the name of an OSS bucket.
  • targetFileSystemId: the ID of a file system.
Filters.N.Values.N RepeatList No ["v-*********************"]

The values that you want to match in the filter.

Response parameters

Parameter Type Example Description
BackupPlans Array of BackupPlan

The returned backup plans that meet the specified conditions.

BackupPlan
BackupType String COMPLETE

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

Bucket String hbr-backup-oss

This parameter is returned only if the SourceType parameter is set to OSS. This parameter indicates the name of the OSS bucket.

CreateTime Long 1554347313

This parameter is returned only if the SourceType parameter is set to NAS. This parameter indicates the time when the file system was created. The time follows the UNIX time format. Unit: seconds.

CreatedTime Long 1554347313

The time when the backup plan was created. The time must be in the UNIX format. Unit: seconds.

Disabled Boolean false

Indicates whether the backup plan is disabled. Valid values:

  • true: disabled.
  • false: enabled.
Exclude String ["/var", "/proc"]

This parameter is returned only if the SourceType parameter is set to ECS_FILE. This parameter indicates the paths that are excluded from the backup plan. No files in the paths are backed up.

FileSystemId String 00594

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

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

This parameter is returned only if the SourceType parameter is set to ECS_FILE. This parameter indicates the paths that are included in the backup plan. All file in the paths are backed up.

InstanceId String i-*********************

This parameter is returned only if the SourceType parameter is set to ECS_FILE. This parameter indicates the ID of the ECS instance.

Options String {"UseVSS":false}

This parameter is returned only if the SourceType parameter is set to ECS_FILE. This parameter indicates whether Windows VSS is used to define a backup path.

Paths List ["/home"]

This parameter is returned only if the SourceType parameter is set to ECS_FILE. The parameter indicates the backup paths.

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

The ID of the backup plan.

PlanName String planname

The name of the backup plan.

Prefix String oss-prefix

This parameter is returned only if the SourceType parameter is set to OSS. This parameter indicates the prefix of the backup file.

Retention Long 7

The retention period of the backup file. Unit: days.

Schedule String 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 following 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 following 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 starts to run a backup job. The interval must follow the ISO8601 standard. For example, PT1H indicates an interval of one hour and P1D indicates an interval of one day.
SourceType String 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.
SpeedLimit String 0:24:5120

If the SourceType parameter is set to ECS_FILE, this parameter is available. This parameter indicates throttling rules. Format: {start}|{end}|{bandwidth}. Separate multiple throttling rules with vertical bars (|). A specified time range cannot overlap with another one.

  • start: the start hour.
  • end: the end time.
  • bandwidth: the bandwidth. Unit: KB per second.
UpdatedTime Long 1554347313

The time when the backup plan was updated. The time follows the UNIX time format. Unit: seconds.

VaultId String v-*********************

The ID of the backup vault.

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.

PageNumber Integer 1

The page number of the returned page. Pages start from page 1. Default value: 1.

PageSize Integer 10

The number of entries returned per page. Valid values: 1 to 99. Default value: 10.

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

The ID of the request.

Success Boolean true

Indicates whether the request is successful. Valid values:

  • true: indicates that the request is successful.
  • false: indicates that the request fails.
TotalCount Long 8

The total number of returned backup plans that meet the specified conditions.

Examples

Sample requests

http(s)://[Endpoint]/?Action=DescribeBackupPlans
&SourceType=ECS_FILE
&<Common request parameters>

Sample success responses

XML format

<DescribeBackupPlansReponse>
  <TotalCount>8</TotalCount>
  <PageSize>10</PageSize>
  <Message>successful</Message>
  <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
  <PageNumber>1</PageNumber>
  <BackupPlans>
        <BackupPlan>
              <Options>{"UseVSS":false}</Options>
              <Exclude>["/var", "/proc"]    </Exclude>
              <CreatedTime>1554347313</CreatedTime>
              <SpeedLimit>0:24:5120</SpeedLimit>
              <InstanceId>i-*********************</InstanceId>
              <CreateTime>1554347313</CreateTime>
              <SourceType>ECS_FILE</SourceType>
              <PlanId>plan-*********************</PlanId>
              <Include>["/home/alice/*.pdf", "/home/bob/*.txt"]</Include>
              <Prefix>oss-prefix</Prefix>
              <Retention>7</Retention>
              <PlanName>planname</PlanName>
              <VaultId>v-*********************</VaultId>
              <Bucket>hbr-backup-oss</Bucket>
              <Schedule>I|1602673264|P1D</Schedule>
              <FileSystemId>00594</FileSystemId>
              <BackupType>COMPLETE</BackupType>
              <UpdatedTime>1554347313</UpdatedTime>
              <Disabled>false</Disabled>
              <Paths>
                    <Path>["/home"]</Path>
              </Paths>
        </BackupPlan>
  </BackupPlans>
  <Code>200</Code>
  <Success>true</Success>
</DescribeBackupPlansReponse>

JSON format

{
    "TotalCount": 8,
    "PageSize": 10,
    "Message": "successful",
    "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
    "PageNumber": 1,
    "BackupPlans": {
        "BackupPlan": {
            "Options": "{\"UseVSS\":false}",
            "Exclude": "[\"/var\", \"/proc\"]",
            "CreatedTime": 1554347313,
            "SpeedLimit": "0:24:5120",
            "InstanceId": "i-*********************",
            "CreateTime": 1554347313,
            "SourceType": "ECS_FILE",
            "PlanId": "plan-*********************",
            "Include": "[\"/home/alice/*.pdf\", \"/home/bob/*.txt\"]",
            "Prefix": "oss-prefix",
            "Retention": 7,
            "PlanName": "planname",
            "VaultId": "v-*********************",
            "Bucket": "hbr-backup-oss",
            "Schedule": "I|1602673264|P1D",
            "FileSystemId": 594,
            "BackupType": "COMPLETE",
            "UpdatedTime": 1554347313,
            "Disabled": false,
            "Paths": {
                "Path": "[\"/home\"]"
            }
        }
    },
    "Code": 200,
    "Success": true
}

Error codes

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