Queries one or more backup jobs that meet specified conditions.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeBackupJobs2

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

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.

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.
SortDirection String No DESCEND

The order in which you want to sort the results. Valid values:

  • ASCEND: sorts the results in ascending order.
  • DESCEND: sorts the results in descending order. Default value: DESCEND.
Filters.N.Key String No vaultId

The keys in the filter. Valid values:

  • RegionId: the ID of a region.
  • PlanId: the ID of a backup plan.
  • JobId: the ID of a backup job.
  • VaultId: the ID of a backup vault.
  • InstanceId: the ID of an ECS instance.
  • Bucket: the name of an OSS bucket.
  • FileSystemId: the ID of a file system.
  • Status: the status of a backup job.
  • CompleteTime: the end time of a backup job.
Filters.N.Values.N String No ["v-*********************"]

The values that you want to match in the filter.

Filters.N.Operator String No IN

The matching method. Default value: IN. This parameter specifies the operator that you want to use to match a key and a value in the filter. Valid values:

  • EQUAL: equal to
  • NOT_EQUAL: not equal to
  • GREATER_THAN: greater than
  • GREATER_THAN_OR_EQUAL: greater than or equal to
  • LESS_THAN: less than
  • LESS_THAN_OR_EQUAL: less than or equal to
  • BETWEEN: specifies a JSON array as a range. The results must fall within the range in the [Mininum value,maximum value] format.
  • IN: specifies an array as a collection. The results must fall within the collection.
Note If you specify CompleteTime as a key to query backup jobs, you cannot use the IN operator to perform a match.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Success Boolean true

Indicates whether the request is successful. Valid values:

  • true: The request is successful.
  • false: The request failed.
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.

TotalCount Long 8

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

BackupJobs Array of BackupJob

The returned backup jobs that meet the specified conditions.

BackupJob
Status String COMPLETE

The status of the backup job. Valid values:

  • COMPLETE: The backup job is completed.
  • PARTIAL_COMPLETE: The backup job is partially completed.
  • FAILED: The backup job failed.
ErrorMessage String PARTIAL_COMPLETE

The error message that is returned by the backup job.

ActualItems Long 6

If the SourceType parameter is set to ECS_FILE, this parameter is available. This parameter indicates the actual number of objects that are backed up by backup jobs.

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

The ID of the backup vault.

ActualBytes Long 600

The actual amount of data that is backed up after the system removes duplicate files. Unit: bytes.

CreateTime Long 1607436917

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 must be in the UNIX format. Unit: seconds.

BackupType String COMPLETE

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

Prefix String example/

This parameter is returned only if the SourceType parameter is set to OSS. This parameter indicates the prefix of objects that are backed up.

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.
Options String null

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 system ensures that the source data is 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.
ClientId String c-*********************

If the SourceType parameter is set to ECS_FILE, this parameter is available. This parameter indicates the ID of the backup client.

ItemsDone Long 8

If the SourceType parameter is set to ECS_FILE, this parameter is available. This parameter indicates the number of objects that are backed up.

BytesTotal Long 1000

The total amount of data that is backed up from the data source. Unit: bytes.

Exclude String ["/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.

JobName String jobname

The name of the backup job.

CompleteTime Long 1554347313

The time when the backup job was completed. The time follows the UNIX time format. Unit: seconds.

CreatedTime Long 1554347313

The time when the backup job was created. The time follows the UNIX time format. Unit: seconds.

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 that is backed up.

Progress Integer 10000

The backup progress. Valid values: [0,1]

SpeedLimit String 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}. Separate multiple throttling rules with vertical bars (|). A specified time range cannot overlap with another one.

  • start: the start time
  • end: the end time
  • bandwidth: bandwidth. Unit: KB per second.
InstanceId String i-*********************

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

PlanId String plan-20********35

The ID of the backup plan.

FileSystemId String 005494

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

StartTime Long 1554347313

The time when the backup job started. The time follows the UNIX time format. Unit: seconds.

UpdatedTime Long 1554347313

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

JobId String job-000g********w7

The ID of the backup task.

ItemsTotal Long 10

If the SourceType parameter is set to ECS_FILE, this parameter is available. This parameter indicates the total number of objects in the data source.

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

The paths to the files that are included in the backup job.

BytesDone Long 800

The actual amount of data that is generated by incremental backups. Unit: bytes.

Paths Array of String "/home"

The backup paths.

Examples

Sample requests

http(s)://[Endpoint]/?Action=DescribeBackupJobs2
&PageNumber=1
&PageSize=10
&SourceType=ECS_FILE
&SortDirection=DESCEND
&Filters=[{"Key":"vaultId","Values":["[\"v-*********************\"]"],"Operator":"IN"}]
&<Common request parameters>

Sample success responses

XML format

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

<DescribeBackupJobs2Response>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <Success>true</Success>
    <Code>200</Code>
    <Message>successful</Message>
    <PageNumber>1</PageNumber>
    <PageSize>10</PageSize>
    <TotalCount>8</TotalCount>
    <BackupJobs>
        <Status>COMPLETE</Status>
        <ErrorMessage>PARTIAL_COMPLETE</ErrorMessage>
        <ActualItems>6</ActualItems>
        <VaultId>v-0006******q</VaultId>
        <ActualBytes>600</ActualBytes>
        <CreateTime>1607436917</CreateTime>
        <BackupType>COMPLETE</BackupType>
        <Prefix>example/</Prefix>
        <SourceType>ECS_FILE</SourceType>
        <Options>{"UseVSS":false}</Options>
        <ClientId>c-*********************</ClientId>
        <ItemsDone>8</ItemsDone>
        <BytesTotal>1000</BytesTotal>
        <Exclude>["/var", "/proc"]</Exclude>
        <JobName>jobname</JobName>
        <CompleteTime>1554347313</CompleteTime>
        <CreatedTime>1554347313</CreatedTime>
        <Bucket>hbr-backup-oss</Bucket>
        <Progress>10000</Progress>
        <SpeedLimit>0:24:5120</SpeedLimit>
        <InstanceId>i-*********************</InstanceId>
        <PlanId>plan-20********35</PlanId>
        <FileSystemId>005494</FileSystemId>
        <StartTime>1554347313</StartTime>
        <UpdatedTime>1554347313</UpdatedTime>
        <JobId>job-000g********w7</JobId>
        <ItemsTotal>10</ItemsTotal>
        <Include>["/home/alice/*.pdf", "/home/bob/*.txt"]</Include>
        <BytesDone>800</BytesDone>
        <Paths>"/home"</Paths>
    </BackupJobs>
</DescribeBackupJobs2Response>

JSON format

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

{
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "Success" : true,
  "Code" : "200",
  "Message" : "successful",
  "PageNumber" : 1,
  "PageSize" : 10,
  "TotalCount" : 8,
  "BackupJobs" : [ {
    "Status" : "COMPLETE",
    "ErrorMessage" : "PARTIAL_COMPLETE",
    "ActualItems" : 6,
    "VaultId" : "v-0006******q",
    "ActualBytes" : 600,
    "CreateTime" : 1607436917,
    "BackupType" : "COMPLETE",
    "Prefix" : "example/",
    "SourceType" : "ECS_FILE",
    "Options" : "{\"UseVSS\":false}",
    "ClientId" : "c-*********************",
    "ItemsDone" : 8,
    "BytesTotal" : 1000,
    "Exclude" : "[\"/var\", \"/proc\"]",
    "JobName" : "jobname",
    "CompleteTime" : 1554347313,
    "CreatedTime" : 1554347313,
    "Bucket" : "hbr-backup-oss",
    "Progress" : 10000,
    "SpeedLimit" : "0:24:5120",
    "InstanceId" : "i-*********************",
    "PlanId" : "plan-20********35",
    "FileSystemId" : "005494",
    "StartTime" : 1554347313,
    "UpdatedTime" : 1554347313,
    "JobId" : "job-000g********w7",
    "ItemsTotal" : 10,
    "Include" : "[\"/home/alice/*.pdf\", \"/home/bob/*.txt\"]",
    "BytesDone" : 800,
    "Paths" : [ "\"/home\"" ]
  } ]
}

Error codes

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