How to check whether an OSS object is restored - Object Storage Service

Archive, Cold Archive, and Deep Cold Archive objects must be restored before you can read them. After you initiate a restore, use one of the following approaches to check whether the operation is complete:

A few objects: Call HeadObject and check the x-oss-restore response header. Available through the OSS console, SDKs, ossutil, and the API.
Many objects: Call ListObjectsV2, ListObjects, or ListObjectVersions and check the RestoreInfo response element. Available through SDKs and the API only.

Restoration states

Both approaches return one of three states:

State	`HeadObject` (`x-oss-restore` header)	`ListObjects` (`RestoreInfo` element)
Not restored or restoration timed out	Header not returned	Element not returned
Restoration in progress	`ongoing-request="true"`	`ongoing-request="true"`
Restoration complete	`ongoing-request="false", expiry-date="<date>"`	`ongoing-request="false", expiry-date="<date>"`

When restoration is complete, the expiry-date value indicates when the object becomes unreadable again.

Check a specific object

Use HeadObject to check the restoration status of an individual object.

Usage notes

HeadObject calls on a large number of objects incur high GET request fees. For more information, see API operation calling fees. To check many objects at once, use the batch query approach instead.

Permissions

The oss:GetObject permission is required. For more information, see Attach a custom policy to a RAM user.

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 was performed or the restoration timed 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.

OSS SDKs

The following Python example calls HeadObject to check the restoration status of 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.
# 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.
# Example: 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')

# Print the HTTP response headers as formatted JSON.
print(json.dumps(dict(result.headers), indent=4))

Restoration complete -- Sample response when ongoing-request is false:

{
    "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"
}

In this response, the x-oss-restore header shows ongoing-request="false", which means the restoration is complete. The object is readable until the time specified by expiry-date.

For SDK examples in other programming languages, see Overview.

ossutil

The following command checks the restoration status of exampledir/exampleobject.txt in the examplebucket bucket:

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

Restoration complete -- Sample response when the object has been restored:

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

Look for the X-Oss-Restore field in the output. If it is absent, the object has not been restored or the restoration has timed out. For more information, see stat.

OSS API

To call the RESTful API directly, include the signature calculation in your code. For more information, see HeadObject.

Check multiple objects at once

Use ListObjectsV2, ListObjects, or ListObjectVersions to check the restoration status of multiple objects by prefix.

Important

The OSS console and ossutil do not support batch restoration status queries. Use SDKs or the API.

Usage notes

These operations do not filter objects by storage class. To check only Archive, Cold Archive, or Deep Cold Archive objects, filter the results by the storage-class attribute on the client side.

Permissions

oss:ListObjects permission is required.
To list object versions, the oss:ListObjectVersions permission is also required.

For more information, see Attach a custom policy to a RAM user.

OSS SDKs

The following Python example calls ListObjects to list objects with the exampledir/ prefix in the examplebucket bucket and prints their restoration status:

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

# Obtain access credentials from environment variables.
# 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.
# Example: 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 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****

In this response, restore_info: None means no restoration operation was performed or the restoration timed out. When restoration is in progress, the value is ongoing-request="true". When restoration is complete, the value includes ongoing-request="false" and the expiry-date.

For SDK examples in other programming languages, see Overview.

OSS API

To call the RESTful API directly, include the signature calculation in your code. For more information, see ListObjectsV2 (GetBucketV2), GetBucket (ListObjects), and ListObjectVersions (GetBucketVersions).