Queries one or more historical backup files that meet the specified conditions.

Request parameters

Parameter Type Required Example Description
Action String Yes SearchHistoricalSnapshots

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

SourceType String Yes ECS_FILE

The type of the data source. Valid values:

  • ECS_FILE: backup files for Elastic Compute Service (ECS) instances
  • OSS: backup files for Object Storage Service (OSS) buckets
  • NAS: backup files for Apsara File Storage NAS file systems
Query Json No [ { "field": "VaultId", "value": "v-0003rf9m17pap3ltpqx5", "operation": "MATCH_TERM" }, { "field": "InstanceId", "value": "i-bp1i20zq2wuzdie9368m", "operation": "MATCH_TERM" }, { "field": "PlanId", "value": "plan-0005vkqhpesqgkd1iu4f", "operation": "MATCH_TERM" }, { "field": "CompleteTime", "value": 1626769913, "operation": "GREATER_THAN_OR_EQUAL" } ]

The search conditions. Example:


[
  {
    "field": "VaultId",
    "value": "v-0003rf9m*****qx5",
    "operation": "MATCH_TERM"
  },
  {
    "field": "InstanceId",
    "value": "i-bp1i20zq2*****e9368m",
    "operation": "MATCH_TERM"
  },
  {
    "field": "PlanId",
    "value": "plan-0005vk*****gkd1iu4f",
    "operation": "MATCH_TERM"
  },
  {
    "field": "CompleteTime",
    "value": 1626769913,
    "operation": "GREATER_THAN_OR_EQUAL"
  }
]
                                
  • The following fields are supported:
    • VaultId: specifies the ID of the backup vault. This field is required.
    • InstanceId: specifies the ID of the ECS instance. If the SourceType parameter is set to ECS_FILE, this field is required.
    • Bucket: specifies the ID of the OSS bucket. If the SourceType parameter is set to OSS, this field is required.
    • FileSystemId: specifies the ID of the NAS file system. If the SourceType parameter is set to NAS, this field is required.
    • CreateTime: specifies the time when the NAS file system was created. If the SourceType parameter is set to NAS, this field is required.
    • CompleteTime: specifies the time when the backup file was completed.
  • The following operations are supported:
    • MATCH_TERM: exact match.
    • 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.
    • NOT_IN: specifies an array as a collection. The results cannot fall within the collection.
Limit Integer No 10

The maximum number of items that the current query returns.

To query only the number of matched rows without the need to return specific data, you can specify limit to 0. Then, the operation returns only the number of matched rows.

NextToken String No caeba0bbb2be03f84eb48b699f0a****

The token that is required to obtain the next page of backup files.

Response parameters

Parameter Type Example Description
Code String 200

The HTTP status code. The status code 200 indicates a successful request.

Limit Integer 10

The number of historical backup files that are displayed on the current page.

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.

NextToken String BE

The token that is required to obtain the next page of backup files.

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

The ID of the request.

Snapshots Array of Snapshot

The historical backup files.

Snapshot
ActualBytes Long 600

The actual amount of data after the system deduplicates backup files. Unit: bytes.

ActualItems Long 6

The actual number of backup files.

Note This parameter is available only for file backup.
BackupType String COMPLETE

The backup type. Valid value: COMPLETE: 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.

BytesDone Long 800

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

BytesTotal Long 1000

The total amount of data. Unit: bytes.

ClientId String c-*********************

This parameter is returned only if the SourceType parameter is set to ECS_FILE. This parameter indicates the ID of the backup client.

CompleteTime Long 1554347313

The time when the backup file was completed. The time is in the UNIX format. Unit: seconds.

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

CreatedTime Long 1554347313

The time when the backup file was created The time is in the UNIX format. Unit: seconds.

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.

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.

ItemsDone Long 8

The number of items that are backed up.

Note This parameter is available only for file backup.
ItemsTotal Long 10

The total number of data sources.

Note This parameter is available only for file backup.
JobId String v-*********************

The ID of the backup job.

ParentSnapshotHash String f2fe..

The HASH value of the parent backup file.

Path String ["/home"]

This parameter is returned only if the SourceType parameter is set to ECS_FILE. This parameter indicates the path to the files that are backed up.

Paths List "/home"

This parameter is returned only if the SourceType parameter is set to NAS. This parameter indicates the paths to the files that are backed up.

Prefix String example/

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.

SnapshotHash String f2fe...

The HASH value of the backup file.

SnapshotId String s-*********************

The ID of the backup file.

SourceType String ECS_FILE

The type of the data source. Valid values:

  • ECS_FILE: backup files for Elastic Compute Service (ECS) instances
  • OSS: backup files for Object Storage Service (OSS) buckets
  • NAS: backup files for Apsara File Storage NAS file systems
StartTime Long 1554347313

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

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.
UpdatedTime Long 1554347313

The time when the backup file was updated. The time is in the UNIX format. Unit: seconds.

VaultId String v-0003rf9m17pap3ltpqx5

The ID of the backup vault that stores the backup file.

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 Integer 20

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

Examples

Sample requests

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

Sample success responses

XML format

<SearchHistoricalSnapshotsResponse>
  <TotalCount>20</TotalCount>
  <NextToken>BE</NextToken>
  <Message>successful</Message>
  <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
  <Limit>10</Limit>
  <Code>200</Code>
  <Snapshots>
        <Snapshot>
              <CreatedTime>1554347313</CreatedTime>
              <SourceType>ECS_FILE</SourceType>
              <Prefix>example/</Prefix>
              <VaultId>v-0003rf9m17pap3ltpqx5</VaultId>
              <Retention>7</Retention>
              <BytesTotal>1000</BytesTotal>
              <ErrorFile></ErrorFile>
              <ActualItems>6</ActualItems>
              <ItemsDone>8</ItemsDone>
              <BytesDone>800</BytesDone>
              <ClientId>c-*********************</ClientId>
              <FileSystemId>005494</FileSystemId>
              <BackupType>COMPLETE</BackupType>
              <ActualBytes>600</ActualBytes>
              <CompleteTime>1554347313</CompleteTime>
              <JobId>v-*********************</JobId>
              <Path>["/home"]</Path>
              <Status>COMPLETE</Status>
              <InstanceId>i-*********************</InstanceId>
              <ItemsTotal>10</ItemsTotal>
              <CreateTime>1607436917</CreateTime>
              <StartTime>1554347313</StartTime>
              <SnapshotHash>f2fe...</SnapshotHash>
              <SnapshotId>s-*********************</SnapshotId>
              <Bucket>hbr-backup-oss</Bucket>
              <ParentSnapshotHash>f2fe..</ParentSnapshotHash>
              <UpdatedTime>1554347313</UpdatedTime>
              <Paths>
                    <Path>"/home"</Path>
              </Paths>
        </Snapshot>
  </Snapshots>
  <Success>true</Success>
</SearchHistoricalSnapshotsResponse>

JSON format

{
    "TotalCount": 20,
    "NextToken": "BE",
    "Message": "successful",
    "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
    "Limit": 10,
    "Code": 200,
    "Snapshots": {
        "Snapshot": {
            "CreatedTime": 1554347313,
            "SourceType": "ECS_FILE",
            "Prefix": "example/",
            "VaultId": "v-0003rf9m17pap3ltpqx5",
            "Retention": 7,
            "BytesTotal": 1000,
            "ErrorFile": "",
            "ActualItems": 6,
            "ItemsDone": 8,
            "BytesDone": 800,
            "ClientId": "c-*********************",
            "FileSystemId": 5494,
            "BackupType": "COMPLETE",
            "ActualBytes": 600,
            "CompleteTime": 1554347313,
            "JobId": "v-*********************",
            "Path": "[\"/home\"]",
            "Status": "COMPLETE",
            "InstanceId": "i-*********************",
            "ItemsTotal": 10,
            "CreateTime": 1607436917,
            "StartTime": 1554347313,
            "SnapshotHash": "f2fe...",
            "SnapshotId": "s-*********************",
            "Bucket": "hbr-backup-oss",
            "ParentSnapshotHash": "f2fe..",
            "UpdatedTime": 1554347313,
            "Paths": {
                "Path": "\"/home\""
            }
        }
    },
    "Success": true
}

Error codes

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