You need to enable JavaScript to run this app.
Torch Object Storage

Torch Object Storage

  • Documentation
    • Torch Object StorageAPI ReferenceObjectBasic Object OperationsRestoreObject
Copy page
Download PDF
Basic Object Operations
RestoreObject
Copy page
Download PDF
RestoreObject

Feature description

Call the RestoreObject interface to restore objects stored in Archive, Cold Archive, and Deep Cold Archive storage classes.

Precautions

  • Symlinks do not support restoration. If a symlink’s storage class is Archive, Cold Archive, or Deep Cold Archive, you can access the symlink object directly without restoring it first. When accessing the target file through a symlink, if the target file’s storage class is Archive, Cold Archive, or Deep Cold Archive, you must restore the target file first.
  • Objects in Archive, Cold Archive, and Deep Cold Archive storage classes cannot be read directly. You must restore the object first before reading. You need RestoreObject permission before restoring an object.
  • After restoring Archive, Cold Archive, or Deep Cold Archive objects, TOS generates a temporary copy in the Standard storage class for you to read. The copy will be automatically deleted after the expiration period you set.
  • After restoring objects from archive storage, cold archive, and deep cold archive, you can use the RestoreObject API to extend the copy's validity period.

    warning

    Currently, only extending the copy's validity period is supported; shortening is not supported.

  • The recovery times for objects in archive storage, cold archive, and deep cold archive vary, as explained below:
    • The recovery time for archive storage files is within 1 minute.
    • The recovery time for cold archive objects depends on the recovery mode you choose. Different recovery modes have different retrieval times and billing rates; shorter times have higher rates. The recovery modes are explained as follows:
      • Expedited retrieval: recovery usually completes within 1 to 5 minutes. Suitable for scenarios requiring urgent file retrieval.
      • Standard retrieval: typically completes recovery within 2 to 5 hours.
      • Bulk retrieval: typically completes recovery within 5 to 12 hours.
    • The recovery time for deep cold archive objects depends on the recovery mode you choose. Retrieval times and billing rates vary by recovery mode: the shorter the time, the higher the rate. Recovery modes are explained as follows:
      • Standard retrieval: typically completes recovery within 12 hours.
      • Bulk retrieval: typically completes recovery within 48 hours.
  • Deep cold archiving is currently in beta testing. If you need to use this feature, please contact your account manager.

Request syntax 

POST /objectname?restore 
Host: bucketname.tos-cn-beijing.volces.com 
Date: Mon, 18 Mar 2019 08:25:17 GMT 
Authorization: SignatureValue

Request parameters and headers

This request uses the public request header, see Common parameters.

NameLocationTypeRequiredSample ValueDescription
restoreQueryStringYes-Represents the special identifier for the RestoreObject request.
versionIdQueryStringNo570773C5A7847849299DObject version number. Specify the version to restore the object.

Request body elements

NameTypeRequiredSample ValueDescription

Days

Integer

Yes

10

The number of days to restore the object. Range is 1 to 365.
The parent node is RestoreRequest.

RestoreJobParametersObjectNo-Restore priority information.

Tier

String

No

Standard

Restore priority. The parent node is RestoreJobParameters.

  • The recovery priority for archive storage objects can only be Standard, which means the archive storage object is restored within 1 minute.

Standard has different recovery priority meanings for archive storage, cold archive, and deep cold archive objects, explained as follows:

  • If recovering an archive storage object, setting Tier to Standard completes recovery within 1 minute.

  • If recovering a cold archive object, setting Tier to Standard completes recovery within 2 to 5 hours.

  • If recovering a deep cold archive object, setting Tier to Standard completes recovery within 12 hours.

  • The recovery priorities for cold archive objects are as follows:

  • Expedited: fast retrieval, restored within 1 to 5 minutes.

  • Standard: standard retrieval, restored within 2 to 5 hours.

  • Bulk: bulk retrieval, restored within 5 to 12 hours.

  • The recovery priorities for deep cold archive objects are as follows:

  • Standard: standard retrieval, restored within 12 hours.

  • Bulk: bulk retrieval, restored within 48 hours.

If RestoreJobParameters is not set, it defaults to Standard retrieval mode.

Response headers

This request returns public response message headers. See Common Parameters.

Response body elements

There is no message element in this request response.

Sample request

Sample request 1

Restore objects in archive storage, cold archive, or deep cold archive.

POST /objectname?restore 
Host: examplebucket.tos.cn-beijing.com 
Date: Mon, 18 Mar 2019 08:25:17 GMT 
Authorization: SignatureValue 

{ 
  "Days": 10 
}

Sample request 2

Restore archived, cold archived, or deep cold archived objects of a specified version.

POST /objectname?restore&versionId=*** 
Host: examplebucket.tos.cn-beijing.com 
Date: Mon, 18 Mar 2019 08:25:17 GMT 
Authorization: SignatureValue 

{ 
    "Days": 10, 
    "RestoreJobParameters": { 
        "Tier": "Standard" 
    } 
}

Sample request 3

Extend the expiration time of the copy of archive storage, cold archive, or deep cold archive objects.

POST /objectname?restore 
Host: examplebucket.tos.cn-beijing.com 
Date: Mon, 18 Mar 2019 08:25:17 GMT 
Authorization: SignatureValue 

{ 
  "Days": 12 
}

Sample response

Sample response 1

First restore archive storage, cold archive, or deep cold archive objects.

HTTP/1.1 202 Accepted 
x-tos-id-2: 5726ce090a2d002d-a444ed0 
x-tos-request-id: 5726ce090a2d002d-a444ed0 
Date: Fri, 30 Jul 2021 08:05:36 GMT 
server: TosServer 
Content-Length: 0

Sample response 2

Restore objects in archive storage, cold archive, or deep cold archive that are already in recovery status again.

HTTP/1.1 409 Conflict 
x-tos-id-2: 5726ce090a2d002d-a444ed0 
x-tos-request-id: 5726ce090a2d002d-a444ed0 
Date: Fri, 30 Jul 2021 08:05:36 GMT 
server: TosServer 
Content-Length: 0 

{ 
    "Code": "RestoreAlreadyInProgress", 
    "RequestId": "23480125cb6573606625cb65-ac1a6118-1ryjQL-RO-cb-1AZ-F-LFRZ-B-K2-1", 
    "HostId": "jONFHoplLHsdsOxAENiZdsWlVlti****", 
    "Message": "Object restore is already in progress", 
    "EC": "0017-00000507" 
}

Sample response 3

Extend the retention period of replicas for archive storage, cold archive, or deep cold archive objects that are in a restoration completed state.

HTTP/1.1 200 OK 
x-tos-id-2: 5726ce090a2d002d-a444ed0 
x-tos-request-id: 5726ce090a2d002d-a444ed0 
Date: Fri, 30 Jul 2021 08:05:36 GMT 
server: TosServer 
Content-Length: 0
Last updated: 2025.06.30 17:27:06