How do I check whether OSS objects are restored? - Object Storage Service

After you restore Archive, Cold Archive, or Deep Cold Archive objects, make sure that the objects are restored before you read the objects. After you restore a large number of objects, you can call related API operations to check the restoration status of objects whose names contain a specific prefix. After you restore a small number of objects, you can call the HeadObject operation to check the restoration status of an object whose name is specified.

Query restoration information about multiple objects at the same time

If you want to query restoration information about multiple objects at the same time, you can call the ListObjectsV2, ListObjects, or ListObjectVersions operation and check the RestoreInfo response element.

If no restoration operation is performed or the restoration operation times out, the RestoreInfo response element is not returned.
If a restoration operation is in progress, ongoing-request="true" is displayed to the right of the RestoreInfo response element.
If a restoration operation is complete, ongoing-request="false" is displayed to the right of the RestoreInfo response element. In this case, expiry-date is included in the RestoreInfo response element to indicate the time after which the object cannot be read.

Usage notes

When you call the ListObjectsV2, ListObjects, or ListObjectVersions operation, you cannot specify the storage classes of objects. If you want to filter objects in the returned results based on storage classes, such as Archive, Cold Archive, or Deep Cold Archive, check the storage-class attribute of each object and filter out objects whose storage classes are not specified on the client.

Permissions

To query restoration information about multiple objects at the same time, you must have the oss:ListObjects permission.
To query restoration information about all versions of objects at the same time, you must have the oss:ListObjectVersions permission.
For more information, see Attach a custom policy to a RAM user.

Important

You cannot call the ListObjectsV2, ListObjects, or ListObjectVersions operation to query restoration information about multiple objects at the same time in the Object Storage Service (OSS) console or by using ossutil.

Use OSS SDKs

The following sample code provides an example on how to call the ListObjects operation in Python to query restoration information about objects whose names contain the exampledir/ prefix in the bucket named examplebucket:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.AuthProvider(EnvironmentVariableCredentialsProvider())

# 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 the endpoint 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')

# List all objects in the examlpedir directory of the bucket. 
for obj in oss2.ObjectIterator(bucket, prefix='exampledir/'):
    # Check whether the storage class of the objects is Archive, Cold Archive, or Deep Cold Archive.
    if obj.storage_class in ['Archive', 'ColdArchive', 'DeepArchive']:
        print("etag:", obj.etag)
        print("key:", obj.key)
        print("last_modified:", obj.last_modified)
        print("size:", obj.size)
        print("storage_class:", obj.storage_class)
        print("type:", obj.type)
        print("restore_info:", obj.restore_info)
        print("owner.id:", obj.owner.id)
        print("owner.display_name:", obj.owner.display_name)

Sample response:

etag: 1797116AF33DB090B2DC79FE70E6F685
key: exampledir/exampleobjec2.txt
last_modified: 1704262519
size: 941
storage_class: DeepColdArchive
type: Normal
restore_info: None
owner.id: 137918634953****
owner.display_name: 137918634953****
etag: 1797116AF33DB090B2DC79FE70E6F685
key: exampledir/exampleobject.txt
last_modified: 1704262504
size: 941
storage_class: ColdArchive
type: Normal
restore_info: None
owner.id: 137918634953****
owner.display_name: 137918634953****
etag: 1797116AF33DB090B2DC79FE70E6F685
key: exampledir/exampleobject1.txt
last_modified: 1704262612
size: 941
storage_class: Archive
type: Normal
restore_info: None
owner.id: 137918634953****
owner.display_name: 137918634953****

For the sample code that is used to list objects in other programming languages, see Overview.

Use the OSS API

If your business requires a high level of customization, you can directly call RESTful APIs. To directly call an API, you must include the signature calculation in your code. For more information, see ListObjectsV2 (GetBucketV2), GetBucket (ListObjects), and ListObjectVersions (GetBucketVersions).

Query restoration information about specific objects

If the number of objects is small, you can check the restoration status of objects by calling the HeadObject operation and check the x-oss-restore response header.

If no restoration operation is performed or the restoration operation times out, the x-oss-restore response header is not returned.
If a restoration operation is in progress, ongoing-request="true" is displayed to the right of the x-oss-restore response header.
If a restoration operation is complete, ongoing-request="false" is displayed to the right of the x-oss-restore response header. In this case, expiry-date is included in the x-oss-restore response header to indicate the time after which the object cannot be read.

Usage notes

If you call the HeadObject operation for a large number of objects, you are charged high fees for GET requests. For more information, see API operation calling fees.

Permissions

To query restoration information about specific objects, you must have the oss:GetObject permission. For more information, see Attach a custom policy to a RAM user.

Use the OSS console

Log on to the OSS console.
In the left-side navigation pane, click Buckets. On the Buckets page, click the bucket that you want to manage.
In the left-side navigation tree, choose Object Management > Objects.
In the Actions column of the object that you want to manage, click View Details.
- If no restoration operation is performed or the restoration operation times out, Restore is displayed to the right of the Object Name field in the View Details panel.
- If a restoration operation is in progress, Restoring is displayed to the right of the Object Name field in the View Details panel.
- If a restoration operation is complete, Restored is displayed to the right of the Object Name field in the View Details panel and a specific period of time is displayed to the right of the Validity Period of Restored Status field to indicate the period during which the object can be read.

Use OSS SDKs

The following sample code provides an example on how to call the HeadObject operation in Python to query restoration information about an Archive object named exampleobject.txt in the exampledir directory of the examplebucket bucket:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import json

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# 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 the endpoint 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')

# Query the metadata of the object. 
result = bucket.head_object('exampledir/exampleobject.txt')

# Return HTTP response headers to query specific metadata of the object. Use json.dumps to format the displayed JSON data. 
print(json.dumps(dict(result.headers), indent=4))

Sample response:

{
    "Server": "AliyunOSS",
    "Date": "Wed, 03 Jan 2024 03:32:58 GMT",
    "Content-Type": "text/plain",
    "Content-Length": "941",
    "Connection": "keep-alive",
    "x-oss-request-id": "6594D56AE80D013535FE****",
    "Accept-Ranges": "bytes",
    "ETag": "\"1797116AF33DB090B2DC79FE70E6F685\"",
    "Last-Modified": "Wed, 03 Jan 2024 03:26:50 GMT",
    "x-oss-object-type": "Normal",
    "x-oss-hash-crc64ecma": "10914985812740272941",
    "x-oss-storage-class": "Archive",
    "x-oss-restore": "ongoing-request=\"false\", expiry-date=\"Thu, 04 Jan 2024 03:28:54 GMT\"",
    "x-oss-expiration": "expiry-date=\"Thu, 04 Jan 2024 00:00:00 GMT\", rule-id=\"ae01d217-94e8-44a6-989a-b89583b****\"",
    "x-oss-version-id": "null",
    "Content-MD5": "F5cRavM9sJCy3Hn+cOb2hQ==",
    "x-oss-server-time": "54"
}

For the sample code that is used to query object metadata in other programming languages, see Overview.

Use ossutil

Run the following command to query restoration information about an object named exampledir/exampleobject.txt in the examplebucket bucket:

ossutil stat oss://examplebucket/exampledir/exampleobject.txt

Sample response if the restoration is complete:

ACL                   : private
Accept-Ranges         : bytes
Content-Length        : 941
Content-Md5           : F5cRavM9sJCy3Hn+cOb2hQ==
Content-Type          : text/plain
Etag                  : 1797116AF33DB090B2DC79FE70E6F685
Last-Modified         : 2024-01-03 11:26:50 +0800 CST
Owner                 : 137918634953****
X-Oss-Expiration      : expiry-date="Thu, 04 Jan 2024 00:00:00 GMT", rule-id="ae01d217-94e8-44a6-989a-b89583b****"
X-Oss-Hash-Crc64ecma  : 10914985812740272941
X-Oss-Object-Type     : Normal
X-Oss-Restore         : ongoing-request="false", expiry-date="Thu, 04 Jan 2024 03:28:54 GMT"
X-Oss-Storage-Class   : Archive
X-Oss-Version-Id      : null

0.291855(s) elapsed

For more information, see stat.