How do I check whether an OSS object is restored? - Object Storage Service

After restoring archived, cold archived, or deep cold archived OSS objects, you must confirm that the objects are restored before reading them. You can use the relevant API to batch check the restoration status of multiple objects by specifying a prefix. For individual objects, the HeadObject API allows you to check the restoration status by specifying the object name.

Batch check the restoration status of objects

To batch check the restoration status of multiple objects, use the ListObjectsV2, ListObjects, or ListObjectVersions API and examine the RestoreInfo response element for restoration status information:

If not restored or the restoration has timed out, the RestoreInfo field is not returned.
If restoring, the RestoreInfo field indicates ongoing-request="true".
Once restoration is completed, the RestoreInfo field shows ongoing-request="false" and includes an expiry-date that specifies when the object's readable state will expire.

Notes

The APIs ListObjectsV2, ListObjects, and ListObjectVersions do not support filtering by storage class. To filter objects of specific storage classes like Archive, Cold Archive, or Deep Cold Archive, you must manually inspect the storage-class property of each object and filter them on the client side.

Permissions

To batch check the restoration status of objects, you need the oss:ListObjects permission.
To check the restoration status of all object versions, the oss:ListObjectVersions permission is required.
For more information, see grant custom policy to RAM users.

Important

The OSS console and the command line tool ossutil do not support batch checking the restoration status of objects using the ListObjectsV2, ListObjects, or ListObjectVersions API.

Use Alibaba Cloud SDKs

The following Python sample code demonstrates how to use the ListObjects API to check the restoration status of objects with the prefix exampledir/ in the bucket 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 for 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 exampledir 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)

The output returned is as follows:

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 sample code in additional languages, refer to the file listing section in the SDK overview.

Use RESTful API operations

For more customized options, you can directly invoke RESTful API operations. This requires including signature calculations in your code. For details, see ListObjectsV2 (GetBucketV2), GetBucket (ListObjects), ListObjectVersions (GetBucketVersions).

Check the restoration status of a specified object

For a small number of objects, use the HeadObject API and examine the response header x-oss-restore for restoration status information:

If not restored or the restoration has timed out, the x-oss-restore field is not returned.
If restoring, the x-oss-restore field indicates ongoing-request="true".
Once restoration is completed, the x-oss-restore field shows ongoing-request="false" and includes an expiry-date that specifies when the object's readable state will expire.

Notes

When checking the restoration status of many objects, using the HeadObject API can result in high GET request fees. For more information, see request fees.

Permissions

To check the restoration status of a specific object, the oss:GetObject permission is required. For details, see grant custom policy to RAM users.

Use the OSS console

Log on to the OSS Management Console.
Click Bucket List, and then click the name of the desired bucket.
In the left-side navigation pane, select File Management > File List.
In the action column on the right side of the target object, click Details.
- If not restored or the restoration has timed out, the Details panel displays Restore next to the Object Name.
- If restoring, the Details panel indicates Restoring next to the Object Name.
- Once restoration is completed, the Details panel shows Restoration Completed next to the Object Name, and the Valid Restoration Time indicates the expiration time of the readable state.

Use Alibaba Cloud SDKs

The following Python sample code illustrates how to use the HeadObject API to check the restoration status of the archived object exampleobject.txt in the exampledir directory of the bucket examplebucket:

# -*- 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 for 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))

The output returned is as follows:

{
    "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 sample code in more languages, refer to the metadata retrieval section in the SDK overview.

Use the command line tool ossutil

The following sample command demonstrates how to check the restoration status of the object with the key exampledir/exampleobject.txt in the bucket examplebucket:

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

If the restoration is complete, the following response is returned:

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 (query bucket and object information).

Use RESTful API operations

For more customized options, you can directly invoke RESTful API operations. This requires including signature calculations in your code. For details, see HeadObject.