All Products
Search

This Product

    Cloud Backup:SearchHistoricalSnapshots

    Document Center

    Cloud Backup:SearchHistoricalSnapshots

    Last Updated:Mar 03, 2024

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

    Debugging

    OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

    Authorization information

    There is currently no authorization information disclosed in the API.

    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 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 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
    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****

    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
    Snapshotsobject []

    The historical backup snapshots.

    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.

    string

    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
      }
    ]
  }
}

    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 changedsee changesets
    Change itemChange content
    Input ParametersThe request parameters of the API has changed.
      Added Input Parameters: SortBy
      Added Input Parameters: Order
    2023-07-18The response structure of the API has changedsee changesets
    Change itemChange content
    Output ParametersThe response structure of the API has changed.
    2023-03-29The response structure of the API has changedsee changesets
    Change itemChange content
    Output ParametersThe response structure of the API has changed.