All Products
Search
Document Center

Cloud Backup:DescribeBackupJobs2

Last Updated:Dec 24, 2024

Queries the information about one or more backup jobs that meet the specified conditions.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
hbr:DescribeBackupJobs2get
*All Resources
*
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
PageNumberintegerNo

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

1
PageSizeintegerNo

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

10
SourceTypestringYes

The type of the data source. Valid values:

  • ECS_FILE: Elastic Compute Service (ECS) files
  • OSS: Object Storage Service (OSS) buckets
  • NAS: Apsara File Storage NAS file systems
  • OTS: Tablestore instances
  • UDM_ECS: ECS instances
  • UDM_ECS_DISK: ECS disks
ECS_FILE
SortDirectionstringNo

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

  • ASCEND: sorts the results in ascending order
  • DESCEND (default value): sorts the results in descending order
DESCEND
Filtersarray<object>No

The keys in the filter.

objectNo

The filter.

KeystringNo

The key 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
  • CreatedTime: the start time of a backup job
  • CompleteTime: the end time of a backup job
  • InstanceName: the name of a Tablestore instance
VaultId
ValuesarrayNo

The variable values of the filter.

stringNo

The value that you want to match in the filter.

["v-*********************"]
OperatorstringNo

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 [Minimum value,Maximum value] format.
  • IN: specifies an array as a collection. The results must fall within the collection.
Note If you specify the CompleteTime parameter as a key to query backup jobs, you cannot use the IN operator to perform a match.
IN

Response parameters

ParameterTypeDescriptionExample
object

Response

RequestIdstring

The ID of the request.

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

Indicates whether the call is successful. Valid values:

  • true: The call is successful.
  • false: The call fails.
true
Codestring

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

200
Messagestring

The message that is returned. If the call is successful, "successful" is returned. If the call fails, an error message is returned.

successful
PageNumberinteger

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

1
PageSizeinteger

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

10
TotalCountlong

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

8
BackupJobsarray<object>

The backup jobs that meet the specified conditions.

BackupJobobject

The details of the backup jobs.

Statusstring

The state of the backup job. Valid values:

  • COMPLETE
  • PARTIAL_COMPLETE
  • FAILED
COMPLETE
ErrorMessagestring

The error message that is returned for the backup job.

PARTIAL_COMPLETE
ActualItemslong

The actual number of objects that are backed up by the backup job. This parameter is returned only if the value of SourceType is ECS_FILE.

6
VaultIdstring

The ID of the backup vault.

v-0006******q
ActualByteslong

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

600
CreateTimelong

The time when the file system was created. This parameter is returned only if the value of SourceType is NAS. This value is a UNIX timestamp representing the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC.

1607436917
BackupTypestring

The backup type. Only COMPLETE may be returned, which indicates full backup.

COMPLETE
Prefixstring

The prefix of objects that are backed up. This parameter is returned only if the value of SourceType is OSS.

example/
SourceTypestring

The type of the data source. Valid values:

  • ECS_FILE: ECS file.
  • OSS: OSS bucket.
  • NAS: NAS file system.
ECS_FILE
Optionsstring

Indicates whether Windows Volume Shadow Copy Service (VSS) is used to define a source path. This parameter is returned only if the value of SourceType is ECS_FILE.

  • This parameter is available only for Windows ECS instances.
  • A value of ["UseVSS":true] indicates that the consistency between the source data and backup data is ensured while data changes occur in the source data.
  • If VSS is used, multiple directories cannot be backed up at a time.
{"UseVSS":false}
ClientIdstring

The ID of the backup client. This parameter is returned only if the value of SourceType is ECS_FILE.

c-*********************
ItemsDonelong

The number of objects that are backed up. This parameter is returned only if the value of SourceType is ECS_FILE.

8
BytesTotallong

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

1000
Excludestring

The paths to the files that are excluded from the backup job. This parameter is returned only if the value of SourceType is ECS_FILE. The value can be up to 255 characters in length.

["/var", "/proc"]
JobNamestring

The name of the backup job.

jobname
CompleteTimelong

The time when the backup job was complete. This value is a UNIX timestamp representing the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC.

1554347313
CreatedTimelong

The time when the backup job was created. This value is a UNIX timestamp representing the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC.

1554347313
Bucketstring

The name of the OSS bucket that is backed up. This parameter is returned only if the value of SourceType is OSS.

hbr-backup-oss
Progressinteger

The backup progress. Valid values: 0 to 10000. For example, a value of 10000 indicates that the progress is 100%.

10000
SpeedLimitstring

The throttling rules. This parameter is returned only if the value of SourceType is ECS_FILE. Format: {start}:{end}:{bandwidth}. Multiple throttling rules are separated by vertical bars (|). The time ranges of the throttling rules cannot overlap.

  • start: the start hour.
  • end: the end hour
  • bandwidth: the bandwidth. Unit: KB/s.
0:24:5120
InstanceIdstring

The ID of the ECS instance. This parameter is returned only if the value of SourceType is NAS.

i-*********************
PlanIdstring

The ID of the backup plan.

plan-20********35
FileSystemIdstring

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

005494
StartTimelong

The time when the backup job started. This value is a UNIX timestamp representing the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC.

1554347313
UpdatedTimelong

The time when the backup job was last updated. This value is a UNIX timestamp representing the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC.

1554347313
JobIdstring

The ID of the backup job.

job-000g********w7
ItemsTotallong

The total number of objects in the data source. This parameter is returned only if the value of SourceType is ECS_FILE.

10
Includestring

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

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

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

800
Pathsarray

The source paths.

Pathstring

The source path.

"/home"
Detailobject

The details of the ECS instance backup job.

DoCopyboolean

Indicates whether remote replication is enabled.

true
DestinationNativeSnapshotIdstring

The ID of the remote replication snapshot.

s-******************
DestinationNativeSnapshotProgressinteger

The progress of the remote replication.

85
DestinationNativeSnapshotStatusstring

The state of the remote replication.

COMPLETE
DestinationRetentionlong

The retention period of the remote replication backup.

30
DestinationSnapshotIdstring

The ID of the remote replication backup.

s-******************
DestinationNativeSnapshotErrorMessagestring

The information about the remote replication failure.

ECS.CreatingSnapshot
NativeSnapshotIdstring

The ID of the backup snapshot.

s-******************
DiskNativeSnapshotIdListarray

The mapping between snapshots and disks.

InstanceInfosobject

ECS instance information, including ECS instance name, instance type, etc.

InstanceNamestring

The name of the Tablestore instance.

instancename
OtsDetailobject

The details of the Tablestore instance.

TableNamesarray

The names of the tables in the Tablestore instance.

TableNamestring

The name of the table in the Tablestore instance.

["table1", "table2", "table3"]
Speedlong

The average speed at which data is backed up. Unit: KB/s.

500
TableNamestring

The name of the table in the Tablestore instance.

table1
CrossAccountTypestring

The backup type. Valid values:

  • SELF_ACCOUNT: Data is backed up within the same Alibaba Cloud account.
  • CROSS_ACCOUNT: Data is backed up across Alibaba Cloud accounts.
SELF_ACCOUNT
CrossAccountUserIdlong

The ID of the source Alibaba Cloud account that authorizes the current Alibaba Cloud account to back up data across Alibaba Cloud accounts.

158975xxxxx4625
CrossAccountRoleNamestring

The name of the Resource Access Management (RAM) role that is created within the source Alibaba Cloud account and assigned to the current Alibaba Cloud account to authorize the current Alibaba Cloud account to back up data across Alibaba Cloud accounts.

BackupRole
Identifierstring

The identifier of the cluster that is backed up in the container backup job. This parameter is returned only if the value of SourceType is CONTAINER. If the cluster is a Container Service for Kubernetes (ACK) cluster, the value of this parameter is the ACK cluster ID.

c83**************************b76
DestSourceTypestring

The data source type at the destination. This parameter is returned only for data synchronization.

OSS
DestDataSourceIdstring

The data source ID at the destination. This parameter is returned only for data synchronization.

ds-000cov4ufudxklj24zdk
DestDataSourceDetailstring

The data source details at the destination. This parameter is returned only for data synchronization.

{\"prefix\":\"/\"}
ChangeListPathstring

The configurations of the incremental file synchronization. This parameter is returned only for data synchronization.

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

The total number of files to be processed.

10
FilesDonelong

The number of files that have been processed.

9
ActualFileslong

The number of files that are actually processed.

8

Examples

Sample success responses

JSONformat

{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "Success": true,
  "Code": "200",
  "Message": "successful",
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 8,
  "BackupJobs": {
    "BackupJob": [
      {
        "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": {
          "Path": [
            "\"/home\""
          ]
        },
        "Detail": {
          "DoCopy": true,
          "DestinationNativeSnapshotId": "s-******************",
          "DestinationNativeSnapshotProgress": 85,
          "DestinationNativeSnapshotStatus": "COMPLETE",
          "DestinationRetention": 30,
          "DestinationSnapshotId": "s-******************",
          "DestinationNativeSnapshotErrorMessage": "ECS.CreatingSnapshot",
          "NativeSnapshotId": "s-******************",
          "DiskNativeSnapshotIdList": {
            "DiskNativeSnapshotId": [
              ""
            ]
          },
          "InstanceInfos": {
            "test": "test",
            "test2": 1
          }
        },
        "InstanceName": "instancename",
        "OtsDetail": {
          "TableNames": {
            "TableName": [
              "[\"table1\", \"table2\", \"table3\"]"
            ]
          }
        },
        "Speed": 500,
        "TableName": "table1",
        "CrossAccountType": "SELF_ACCOUNT",
        "CrossAccountUserId": 0,
        "CrossAccountRoleName": "BackupRole",
        "Identifier": "c83**************************b76",
        "DestSourceType": "OSS",
        "DestDataSourceId": "ds-000cov4ufudxklj24zdk",
        "DestDataSourceDetail": "{\\\"prefix\\\":\\\"/\\\"}",
        "ChangeListPath": "{\"dataSourceId\": \"ds-123456789\", \"path\": \"/changelist\"}",
        "FilesTotal": 10,
        "FilesDone": 9,
        "ActualFiles": 8
      }
    ]
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-07-31The response structure of the API has changedView Change Details
2023-11-16The response structure of the API has changedView Change Details
2023-09-21The response structure of the API has changedView Change Details
2023-07-31The response structure of the API has changedView Change Details
2023-04-21The response structure of the API has changedView Change Details
2023-03-29The response structure of the API has changedView Change Details