You must restore an Archive or a Cold Archive object before you can read it. This topic describes how to restore an Archive or a Cold Archive object.

Restoration

If you want to read an Archive object or a Cold Archive object, you must restore the object in advance. It takes several minutes to restore an Archive object and takes several hours to restore a Cold Archive object.

The following section describes the status of an Archive object or a Cold Archive object throughout the restoration process:
  1. By default, an Archive or a Cold Archive object is in the frozen state before restoration.
  2. After you submit a restore request, the object is in the restoring state.
  3. After the server completes the restore task, the object enters the restored state and you can read the object.
    • Archive objects

      For Archive objects, the restored state lasts 24 hours by default. During the 24 hours, if you call RestoreObject again, the restored state is extended by 24 hours. You can extend the restored state to seven days by calling RestoreObject six times during the first 24 hours of restored state. You can also configure the duration of the restored state in days by calling RestoreObject once. You can specify a duration of at most seven days.

    • Cold Archive objects
      For Cold Archive objects, you can specify the duration of restored state and restoration priority. The duration of the restored state must be at least one day and at most 365 days. The time required to restore a Cold Archive object to the readable state is determined based on the restoration priority of the object:
      • Expedited: The object is restored within one hour.
      • Standard: The object is restored within two to five hours. If the JobParameters element is not passed in, the default restoration priority is Standard.
      • Bulk: The object is restored within five to twelve hours.
  4. After the restored state expires, the object returns to the frozen state.

Precautions

  • The RestoreObject operation applies only to archived objects or cold archived objects. This operation does not apply to Standard or IA objects.
  • The first time RestoreObject is called on an object, HTTP status code 202 is returned.
  • The first time RestoreObject is called on an object, HTTP status code 202 is returned. When you call RestoreObject that was called on a frozen object whose restored state expires, 200 OK is returned.
  • In a versioned bucket, the storage classes of different versions of an object can be different. By default, when you call RestoreObject to restore an object, the current version of the object is restored. You can specify a version ID in the request to restore the specified version of the object.

Billing

  • Data retrieval fees are generated when you restore Archive and Cold Archive objects. For more information, see Data processing fees.
  • The restored state of an Archive object can persist up to seven days and that of a Cold Archive object can persist up to 365 days. You are not repeatedly charged data retrieval fees during this process.
  • After the restored state expires, the object returns to the frozen state. Data retrieval fees are generated if you perform the restore operation on the object again.
  • When you restore a Cold Archive object, a Standard replica is generated for temporary access. OSS charges the temporary storage fees of the replica for the duration during which the replica is available based on Standard storage. For more information, see Temporary storage fees.

Use the OSS console

Use ossbrowser

ossbrowser supports the same operations related to objects as the Object Storage Service (OSS) console. You can follow the on-screen instructions in ossbrowser to restore objects. For more information about how to use ossbrowser, see Use ossbrowser.

Use OSS SDKs

The following code provides examples on how to restore objects by using OSS SDKs for common programming languages. For more information about how to restore objects by using OSS SDKs for other programming languages, see Overview.

// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Specify the name of the bucket. 
String bucketName = "yourBucketName";
// Specify the full path of the Archive object. The path cannot contain the bucket name. 
String objectName = "yourArchiveObjectName";

// Create an OSSClient instance. 
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);

ObjectMetadata objectMetadata = ossClient.getObjectMetadata(bucketName, objectName);

// Check whether the object is an Archive object. 
StorageClass storageClass = objectMetadata.getObjectStorageClass();
if (storageClass == StorageClass.Archive) {
    // Restores the object. 
    ossClient.restoreObject(bucketName, objectName);

    // Wait until the object is restored. 
    do {
        Thread.sleep(1000);
        objectMetadata = ossClient.getObjectMetadata(bucketName, objectName);
    } while (!objectMetadata.isRestoreCompleted());
}

// Obtain the restored object. 
OSSObject ossObject = ossClient.getObject(bucketName, objectName);
ossObject.getObjectContent().close();

// Shut down the OSSClient instance. 
ossClient.shutdown();
            
<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\OssClient;
use OSS\Core\OssException;

// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
$accessKeyId = "yourAccessKeyId";
$accessKeySecret = "yourAccessKeySecret";
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// Specify the name of the bucket. Example: examplebucket. 
$bucket= "examplebucket";
// Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: srcexampleobject.txt. 
$object = "srcexampleobject.txt";

try {
    $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint);
    // Restore the object. 
    $ossClient->restoreObject($bucket, $object);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}
print(__FUNCTION__ . ": OK" . "\n");        
# -*- coding: utf-8 -*-
import oss2

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. The path cannot contain the bucket name. 
objectName = 'yourObjectName'

bucket.restore_object(objectName)            
package main

import (
    "fmt"
    "os"
    "time"
    "strings"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func HandleError(err error) {
    fmt.Println("Error:", err)
    os.Exit(-1)
}

func main() {
    // Create an OSSClient instance. 
    // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify the actual endpoint. 
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS, because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
    if err != nil {
        HandleError(err)
    }
    // Specify the name of the bucket. Example: examplebucket. 
    bucketName := "examplebucket"
    // Specify the full path of the object. The path cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    objectName := "exampledir/exampleobject.txt"
    // Specify the full path of the local file that you want to upload. Example: D:\\localpath\\examplefile.txt. 
    localFilename := "D:\\localpath\\examplefile.txt"

    // Create the bucket. 
    err = client.CreateBucket(bucketName, oss.StorageClass(oss.StorageArchive))
    if err != nil {
        HandleError(err)
    }

    // Obtain the bucket. 
    archiveBucket, err := client.Bucket(bucketName)
    if err != nil {
        HandleError(err)
    }

    // Upload the local file. 
    var val = "More than just cloud."
    err = archiveBucket.PutObject(objectName, strings.NewReader(val))
    if err != nil {
        HandleError(err)
    }

    // Check whether the object is an Archive object. 
    meta, err := archiveBucket.GetObjectDetailedMeta(objectName)
    if err != nil {
        HandleError(err)
    }

    fmt.Println("X-Oss-Storage-Class : ", meta.Get("X-Oss-Storage-Class"))
    if meta.Get("X-Oss-Storage-Class") == string(oss.StorageArchive) {
        // Restore the Archive object. 
        var restoreConfig oss.RestoreConfiguration
        // Specify the duration for which the object can remain in the restored state. Unit: days. Valid values: 1 to 7. 
        restoreConfig.Days = 1
        err = archiveBucket.RestoreObjectDetail(objectName,restoreConfig)
        if err != nil {
            HandleError(err)
        }

        // Wait until the Archive object is restored. 
        meta, err = archiveBucket.GetObjectDetailedMeta(objectName)
        for meta.Get("X-Oss-Restore") == "ongoing-request=\"true\"" {
            fmt.Println("x-oss-restore:" + meta.Get("X-Oss-Restore"))
            time.Sleep(10 * time.Second)
            meta, err = archiveBucket.GetObjectDetailedMeta(objectName)
        }
    }

    // Download the restored object. 
    err = archiveBucket.GetObjectToFile(objectName, localFilename)
    if err != nil {
        HandleError(err)
    }

    // Restore the Archive object again. 
    err = archiveBucket.RestoreObject(objectName)

    fmt.Println("ArchiveSample completed")
}            
using Aliyun.OSS;
using Aliyun.OSS.Model;

// Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
var endpoint = "yourEndpoint";
// Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS, because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
var accessKeyId = "yourAccessKeyId";
var accessKeySecret = "yourAccessKeySecret";
// Specify the name of the bucket. 
var bucketName = "examplebucket";
// Specify the full path of the object. The path cannot contain the bucket name. 
var objectName = "yourObjectName";
// Specify the content of the object. 
var objectContent = "More than just cloud.";
int maxWaitTimeInSeconds = 600;
// Create an OSSClient instance. 
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // Create an Archive bucket. 
    var bucket = client.CreateBucket(bucketName, StorageClass.Archive);
    Console.WriteLine("Create Archive bucket succeeded, {0} ", bucket.Name);
}
catch (Exception ex)
{
    Console.WriteLine("Create Archive bucket failed, {0}", ex.Message);
}
// Upload the object to the bucket and set the storage class of the object to Archive. 
try
{
    byte[] binaryData = Encoding.ASCII.GetBytes(objectContent);
    MemoryStream requestContent = new MemoryStream(binaryData);
    client.PutObject(bucketName, objectName, requestContent);
    Console.WriteLine("Put object succeeded, {0}", objectName);
}
catch (Exception ex)
{
    Console.WriteLine("Put object failed, {0}", ex.Message);
}
var metadata = client.GetObjectMetadata(bucketName, objectName);
string storageClass = metadata.HttpMetadata["x-oss-storage-class"] as string;
if (storageClass != "Archive")
{
    Console.WriteLine("StorageClass is {0}", storageClass);
    return;
}
// Restore the Archive object. 
RestoreObjectResult result = client.RestoreObject(bucketName, objectName);
Console.WriteLine("RestoreObject result HttpStatusCode : {0}", result.HttpStatusCode);
if (result.HttpStatusCode != HttpStatusCode.Accepted)
{
    throw new OssException(result.RequestId + ", " + result.HttpStatusCode + " ,");
}
while (maxWaitTimeInSeconds > 0)
{
    var meta = client.GetObjectMetadata(bucketName, objectName);
    string restoreStatus = meta.HttpMetadata["x-oss-restore"] as string;
    if (restoreStatus != null && restoreStatus.StartsWith("ongoing-request=\"false\"", StringComparison.InvariantCultureIgnoreCase))
    {
        break;
    }
    Thread.Sleep(1000);
    maxWaitTimeInSeconds--;
}
if (maxWaitTimeInSeconds == 0)
{
    Console.WriteLine("RestoreObject is timeout. ");
    throw new TimeoutException();
}
else
{
    Console.WriteLine("RestoreObject is successful. ");
}
#include <alibabacloud/oss/OssClient.h>
#include <thread>
#include <chrono>
using namespace AlibabaCloud::OSS;

int main(void)
{

    /* Initialize OSS account information. */
    /* Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS, because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. */
    std::string AccessKeyId = "yourAccessKeyId";
    std::string AccessKeySecret = "yourAccessKeySecret";
    /* Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Specify the name of the bucket. Example: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Specify the full path of the object. The path cannot contain the bucket name. */
    std::string ObjectName = "yourObjectName";

    /* Initialize resources such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

    /* Restore the Archive object. */
    auto outcome = client.RestoreObject(BucketName, ObjectName);

    /* You cannot restore objects of the non-Archive storage class. */
    if (!outcome.isSuccess()) {
        /* Handle exceptions. */
        std::cout << "RestoreObject fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        ShutdownSdk();
        return -1;
    }

    std::string onGoingRestore("ongoing-request=\"false\"");

    int maxWaitTimeInSeconds = 600;
    while (maxWaitTimeInSeconds > 0)
    {
        auto meta = client.HeadObject(BucketName, ObjectName);

        std::string restoreStatus = meta.result().HttpMetaData()["x-oss-restore"];
        std::transform(restoreStatus.begin(), restoreStatus.end(), restoreStatus.begin(), ::tolower);
        if (!restoreStatus.empty() && 
        restoreStatus.compare(0, onGoingRestore.size(), onGoingRestore)==0) {
            std::cout << " success, restore status:" << restoreStatus << std::endl;
            /* The Archive object is restored. */
            break;
        }

        std::cout << " info, WaitTime:" << maxWaitTimeInSeconds
        << "; restore status:" << restoreStatus << std::endl;

        std::this_thread::sleep_for(std::chrono::seconds(10));
        maxWaitTimeInSeconds--;     
    }

    if (maxWaitTimeInSeconds == 0)
    {
        std::cout << "RestoreObject fail, TimeoutException" << std::endl;
    }

    /* Release resources such as network resources. */
    ShutdownSdk();
    return 0;
}

Use ossutil

For more information about how to restore Archive or Cold Archive objects by using ossutil, see restore (restore objects).

Use the RESTful API

If your program requires more custom options to restore objects, you can call RESTful API operations. In this case, you must manually write code to calculate the signature. For more information, see RestoreObject

References

If you send a RestoreObject request to restore an Archive object or a Cold Archive object, you can call GetBucket (ListObjects), GetBucketV2 (ListObjectsV2), or GetBucketVersions(ListObjectVersions) to check whether the object is restored.