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

Important Do not call the RestoreObject operation on an object whose storage class is not Archive or Cold Archive.

Usage notes

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about the regions and endpoints supported by OSS, see Regions and endpoints.
  • In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient by using custom domain names or STS, see Create an OSSClient instance.
  • To restore an object, you must have the oss:RestoreObject permission. For more information, see Attach a custom policy to a RAM user.

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 it takes several hours to restore a Cold Archive object based on different restoration priorities. The actual restoration time prevails.

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

      For Archive objects, the restored state lasts 24 hours by default. During the 24 hours, you can call RestoreObject again to extend the duration of the restored state for another 24 hours. During one restoration process, you can call RestoreObject for up to seven times to extend the duration of the restored state of the object. In other words, an object can remain in the restored state for up to seven days. You can also configure the duration of the restored state in days by calling RestoreObject. You can specify a duration of up to seven days.

    • Cold Archive objects
      For Cold Archive objects, you can specify the duration of the restored state and the 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 parameter is not passed in, the default restoration mode is Standard.
      • Bulk: The object is restored within five to twelve hours.

      The reference value for the amounts of retrieved data is an average of 500 objects per second. The total amount of retrieved data for the preceding priorities ranges from 100 TB to 120 TB per day.

  4. After the duration of the restored state expires, the object returns to the frozen state.

Restore an Archive object

The following code provides an example on how to restore an Archive object:

<?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;

// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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");        

Restore a Cold Archive object

The following code provides an example on how to restore a Cold Archive object:

<?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;
use OSS\Model\RestoreConfig;

// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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);
    // Specify the duration in which the object can remain in the restored state. Unit: days. Valid values: 1 to 7. 
    $day = 3; 
    // Specify the restoration priority of the object. In this example, this parameter is set to Expedited, which specifies that the object is restored within 1 hour. 
    // If you want to restore the object within 2 to 5 hours, set this parameter to Standard. If you want to restore the object within 5 to 12 hours, set this parameter to Bulk. 
    $tier = "Expedited"; 

    $config = new RestoreConfig($day,$tier);

    $options = array(
      OssClient::OSS_RESTORE_CONFIG => $config
    );

        $result = $ossClient->restoreObject($bucket, $object,$options);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}            

References

For more information about the API operation that you can call to restore Archive and Cold Archive objects, see RestoreObject.