All Products
Search
Document Center

Cloud Backup:SearchHistoricalSnapshots

Last Updated:Oct 31, 2024

Queries the information about one or more backup snapshots 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:SearchHistoricalSnapshotsget
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
SourceTypestringYes

The type of the data source. Valid values:

  • ECS_FILE: backup snapshots for Elastic Compute Service (ECS) files
  • OSS: backup snapshots for Object Storage Service (OSS) buckets
  • NAS: backup snapshots for Apsara File Storage NAS file systems
ECS_FILE
QueryarrayNo

The query 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 Elastic Compute Service (ECS) instance. If the SourceType parameter is set to ECS_FILE, this field is required.
    • Bucket: specifies the name of the Object Storage Service (OSS) bucket. If the SourceType parameter is set to OSS, this field is required.
    • FileSystemId: specifies the ID of the Apsara File Storage NAS (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 snapshot was completed.
    • PlanId: the ID of a backup plan.
  • 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 [Minimum 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.
anyNo

The query 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 name 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 snapshot was completed.
    • PlanId: the ID of a backup plan.
  • 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 [Minimum 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.
[ { "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" } ]
LimitintegerNo

The maximum number of rows that you want the current query to return. To query only the number of matched rows without the need to return specific data, you can set the Limit parameter to 0. Then, the operation returns only the number of matched rows.

10
NextTokenstringNo

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

caeba0bbb2be03f84eb48b699f0a****
SortBystringNo

The field that is used to sort data.

CreatedTime
OrderstringNo

The ordering mode. Valid values:

  • ASC (default): ascending order
  • DESC: descending order
ASC

Response parameters

ParameterTypeDescriptionExample
object
NextTokenstring

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

BE
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
Limitinteger

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

10
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
TotalCountinteger

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

20
Snapshotsarray<object>

The historical backup snapshots.

Snapshotobject
Statusstring

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 has failed.
COMPLETE
SnapshotHashstring

The hash value of the backup snapshot.

f2fe...
VaultIdstring

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

v-0003rf9m17pap3ltpqx5
ActualItemslong

The actual number of backup snapshots.

Note This parameter is available only for file backup.
6
BackupTypestring

The backup type. Valid value: COMPLETE, which indicates full backup.

COMPLETE
CreateTimelong

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 value is a UNIX timestamp. Unit: seconds.

1607436917
ActualByteslong

The actual data amount of backup snapshots after duplicates are removed. Unit: bytes.

600
SourceTypestring

The type of the data source. Valid values:

  • ECS_FILE: backup snapshots for ECS files
  • OSS: backup snapshots for OSS buckets
  • NAS: backup snapshots for NAS file systems
ECS_FILE
Prefixstring

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

example/
ClientIdstring

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

c-*********************
BytesTotallong

The total amount of data. Unit: bytes.

1000
ItemsDonelong

The number of objects that are backed up.

Note This parameter is available only for file backup.
8
CompleteTimelong

The time when the backup snapshot was completed. The value is a UNIX timestamp. Unit: seconds.

1554347313
Retentionlong

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

7
CreatedTimelong

The time when the backup snapshot was created. The value is a UNIX timestamp. Unit: seconds.

1554347313
Bucketstring

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

hbr-backup-oss
ParentSnapshotHashstring

The hash value of the parent backup snapshot.

f2fe..
InstanceIdstring

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

i-*********************
FileSystemIdstring

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

005494
ErrorFilestring

The files that record the information about backup failures, including the information about partially completed backups.

Item Error Message C:\Program Files (x86)\Symantec\Symantec Endpoint Protection\14.3.558.0000.105\Bin\service.dat Open: open \\?\C:\Program Files (x86)\Symantec\Symantec Endpoint Protection\14.3.558.0000.105\Bin\service.dat: The process cannot access the file because it is being used by another process. C:\ProgramData\McAfee\Agent\data\InstallerFiles\172e8a3b04b7ab0fd0215f4fb7707e3744b37d83b6743b3eacb94447c74dc9af_contrib.ini Open: open \\?\C:\ProgramData\McAfee\Agent\data\InstallerFiles\172e8a3b04b7ab0fd0215f4fb7707e3744b37d83b6743b3eacb94447c74dc9af_contrib.ini: Access is denied.
StartTimelong

The time when the backup snapshot started. The value is a UNIX timestamp. Unit: seconds.

1554347313
UpdatedTimelong

The time when the backup snapshot was updated. The value is a UNIX timestamp. Unit: seconds.

1554347313
SnapshotIdstring

The ID of the backup snapshot.

s-*********************
JobIdstring

The ID of the backup job.

v-*********************
Pathstring

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.

["/home"]
ItemsTotallong

The total number of objects in the data source.

Note This parameter is available only for file backup.
10
BytesDonelong

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

800
Pathsarray

The source paths.

Pathstring

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

"/home"
InstanceNamestring

The name of the Tablestore instance.

instancename
TableNamestring

The name of a table in the Tablestore instance.

table2
RangeStartlong

The time when the backup job started. The value is a UNIX timestamp. Unit: milliseconds.

1642492553038
RangeEndlong

The time when the backup job ended. The value is a UNIX timestamp. Unit: milliseconds.

1642521709966
ExpireTimelong

The time when the snapshot expired. The value is a UNIX timestamp. Unit: seconds.

1640334062

Examples

Sample success responses

JSONformat

{
  "NextToken": "BE",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "Success": true,
  "Limit": 10,
  "Code": "200",
  "Message": "successful",
  "TotalCount": 20,
  "Snapshots": {
    "Snapshot": [
      {
        "Status": "COMPLETE",
        "SnapshotHash": "f2fe...",
        "VaultId": "v-0003rf9m17pap3ltpqx5",
        "ActualItems": 6,
        "BackupType": "COMPLETE",
        "CreateTime": 1607436917,
        "ActualBytes": 600,
        "SourceType": "ECS_FILE",
        "Prefix": "example/",
        "ClientId": "c-*********************",
        "BytesTotal": 1000,
        "ItemsDone": 8,
        "CompleteTime": 1554347313,
        "Retention": 7,
        "CreatedTime": 1554347313,
        "Bucket": "hbr-backup-oss",
        "ParentSnapshotHash": "f2fe..",
        "InstanceId": "i-*********************",
        "FileSystemId": "005494",
        "ErrorFile": "Item\tError Message C:\\Program Files (x86)\\Symantec\\Symantec Endpoint Protection\\14.3.558.0000.105\\Bin\\service.dat\tOpen: open \\\\?\\C:\\Program Files (x86)\\Symantec\\Symantec Endpoint Protection\\14.3.558.0000.105\\Bin\\service.dat: The process cannot access the file because it is being used by another process. C:\\ProgramData\\McAfee\\Agent\\data\\InstallerFiles\\172e8a3b04b7ab0fd0215f4fb7707e3744b37d83b6743b3eacb94447c74dc9af_contrib.ini\tOpen: open \\\\?\\C:\\ProgramData\\McAfee\\Agent\\data\\InstallerFiles\\172e8a3b04b7ab0fd0215f4fb7707e3744b37d83b6743b3eacb94447c74dc9af_contrib.ini: Access is denied.",
        "StartTime": 1554347313,
        "UpdatedTime": 1554347313,
        "SnapshotId": "s-*********************",
        "JobId": "v-*********************",
        "Path": "[\"/home\"]",
        "ItemsTotal": 10,
        "BytesDone": 800,
        "Paths": {
          "Path": [
            "\"/home\""
          ]
        },
        "InstanceName": "instancename",
        "TableName": "table2",
        "RangeStart": 1642492553038,
        "RangeEnd": 1642521709966,
        "ExpireTime": 1640334062,
        "SourceSnapshotHash": "qwer***",
        "SourceParentSnapshotHash": "qwer***",
        "StorageClass": "STANDARD",
        "ArchiveTime": 1640334062,
        "UseCommonNas": false,
        "Include": "[\\\"/test/example_cn-huhehaote_3.txt\\\", \\\"/test/example_cn-huhehaote_9.txt\\\", \\\"/test/example_cn-huhehaote_5.txt\\\", \\\"/test/example_cn-huhehaote_1.txt\\\", \\\"/test/example_cn-huhehaote_7.txt\\\"]",
        "Exclude": "[\\\"/test/example_cn-hangzhou_7.txt\\\", \\\"/test/example_cn-hangzhou_1.txt\\\", \\\"/test/example_cn-hangzhou_3.txt\\\", \\\"/test/example_cn-hangzhou_9.txt\\\", \\\"/test/example_cn-hangzhou_6.txt\\\"]"
      }
    ]
  }
}

Error codes

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

Change history

Change timeSummary of changesOperation
2024-01-05The request parameters of the API has changedView Change Details
2023-07-18The response structure of the API has changedView Change Details
2023-03-29The response structure of the API has changedView Change Details