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.

Notice Do not call RestoreObject to restore an object whose storage class is not Archive or Cold Archive.

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.
  4. After the duration of the restored state expires, the object returns to the frozen state.

Restore Archive objects

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

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {
    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access Object Storage Service (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. 
        String accessKeyId = "yourAccessKeyId";
        String accessKeySecret = "yourAccessKeySecret";
        // Specify the bucket name. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the Archive object. The path cannot contain the bucket name. 
        String objectName = "exampledir/object";

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

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

            // Check whether the object is an Archive object. 
            StorageClass storageClass = objectMetadata.getObjectStorageClass();
            if (storageClass == StorageClass.Archive) {
                // Restore 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();
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}           

Restore a Cold Archive object

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

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {
    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access 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. 
        String accessKeyId = "yourAccessKeyId";
        String accessKeySecret = "yourAccessKeySecret";
        // Specify the bucket name. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the full path of the Cold Archive object. The path cannot contain the bucket name. 
        String objectName = "exampledir/object";

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

        try {
            // If you want to set the storage class of the object to Cold Archive when you upload the object, use the following code. 
            // Create a PutObjectRequest object. 
            // PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName, new ByteArrayInputStream("<yourContent>".getBytes()));
            // Set the storage class of the object to Cold Archive in the object metadata. 
            // ObjectMetadata metadata = new ObjectMetadata();
            // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.ColdArchive.toString());
            // putObjectRequest.setMetadata(metadata);
            // Set the storage class of the object when you upload the object. 
            // ossClient.putObject(putObjectRequest);

            // Set the restoration priority of the Cold Archive object. 
            // RestoreTier.RESTORE_TIER_EXPEDITED: The object is restored within an hour. 
            // RestoreTier.RESTORE_TIER_STANDARD: The object is restored within two to five hours. 
            // RestoreTier.RESTORE_TIER_STANDARD: The object is restored within five to twelve hours. 
            RestoreJobParameters jobParameters = new RestoreJobParameters(RestoreTier.RESTORE_TIER_EXPEDITED);

            // Configure parameters. For example, set the restoration priority of the object to Standard, and set the duration for which the object can remain in the restored state to two days. 
            // The first parameter indicates the validity period of the restored state. The default value is one day. This parameter applies to Archive and Cold Archive objects. 
            // jobParameters indicates the restoration priority of the object and applies only to Cold Archive objects. 
            RestoreConfiguration configuration = new RestoreConfiguration(2, jobParameters);

            // Initiate a restore request. 
            ossClient.restoreObject(bucketName, objectName, configuration);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

References

  • For the complete sample code that is used to restore Archive and Cold Archive objects, visit GitHub.
  • For more information about the API operation that you can call to restore Archive and Cold Archive objects, see RestoreObject.