DocsICP FilingConsole
Documentation
Home Page Object Storage Service Developer Reference Developer tools ossutil 2.0 CLI Advanced commands restore

restore

Updated at:
Copy as MD
Product
My Favorites

If real-time access of Archive objects is not enabled, you can read an Archive object only after you restore it. Real-time access is not supported for Cold Archive or Deep Cold Archive objects, so you can read these objects only after you restore them. Restoring an Archive object usually takes several minutes, restoring a Cold Archive object usually takes several hours, and restoring a Deep Cold Archive object usually takes 12 to 48 hours. These durations are estimates, and the actual restoration time may vary. This topic describes how to run the restore command to restore objects.

Usage notes

  • To restore a single object, you must have the oss:RestoreObject permission. To restore objects by directory, you must have the oss:RestoreObject and oss:ListObjects permissions. For instructions, see Grant a custom policy.

  • For more information about the restoration status and billing rules of Archive, Cold Archive, and Deep Cold Archive objects, see Restore objects.

Command syntax

ossutil restore oss://bucket/object [flags]

Parameter

Type

Description

--days

int

The number of days for which the object remains in the restored state. Valid values: 1 to 365.

When you perform a batch operation on objects in mixed storage classes, and the --days value exceeds the maximum value supported by a storage class, the value is automatically adjusted to the maximum value supported by that storage class. For example, Archive supports a maximum of 7 days and Deep Cold Archive supports 365 days. If you set --days to 100, the value is automatically adjusted to 7 for Archive objects, and 100 is used for Deep Cold Archive objects.

Note

--days 3 specifies that the object remains readable for 3 days after it is restored.

--tier

string

The restoration priority. You do not need to specify this parameter for Archive objects, which are restored in 1 minute.

  • Cold Archive:

    • Expedited: The object is restored within 1 hour.

    • Standard: The object is restored within 2 to 5 hours.

    • Bulk: The object is restored within 5 to 12 hours.

  • Deep Cold Archive:

    • Expedited: The object is restored within 12 hours.

    • Standard: The object is restored within 48 hours.

When you perform a batch operation on objects in mixed storage classes, and the --tier value exceeds the priority supported by a storage class, the value is automatically adjusted to the lowest priority supported by that storage class. For example, Cold Archive supports Bulk and Deep Cold Archive supports only Standard. If you set --tier to Bulk, the value is automatically adjusted to Standard for Deep Cold Archive objects.

Note

--tier Standard specifies that Cold Archive or Deep Cold Archive objects are restored at the Standard priority.

Different restoration priorities incur different data retrieval request fees and data retrieval capacity fees. Expedited incurs the highest fees. For more information, see Request fees.

--archive-max-days

int

The maximum number of days for which Archive objects remain in the restored state in a batch restore operation. Default value: 7. If --days is greater than this value, Archive objects are restored for this number of days, and objects in other storage classes are still restored for the number of days specified by --days.

Note

ossutil restore oss://examplebucket/dir/ -r --days 30 --archive-max-days 7 specifies that Cold Archive and Deep Cold Archive objects are restored for 30 days and Archive objects are restored for 7 days.

--checkers

int

The number of check tasks that run in parallel. Default value: 16.

Note

--checkers 32 specifies that 32 check tasks run in parallel.

--dirs

/

Returns the objects and subdirectories in the current directory instead of recursively listing all objects in all subdirectories.

Note

ossutil restore oss://examplebucket/dir/ -d specifies that only the objects directly in dir/ are restored, and objects in its subdirectories, such as dir/sub/, are not restored.

--encoding-type

string

The encoding method of the object name or file name that you specify. Valid value: url.

Note

ossutil restore "oss://examplebucket/%E6%B5%8B%E8%AF%95.txt" --encoding-type url specifies that the object name is URL-encoded. The object that is actually restored is the one whose name is URL-encoded as %E6%B5%8B%E8%AF%95.txt.

--end-with

string

Returns objects whose names are alphabetically before the specified value, including the specified value.

Note

--end-with dir/c.txt specifies that only objects whose names are alphabetically before dir/c.txt are processed, including dir/c.txt.

--exclude

stringArray

The exclusion rule for paths or object names.

Note

--exclude "*.csv" specifies that objects whose names end with .csv are not processed.

--exclude-from

stringArray

Reads exclusion rules from a rule file.

Note

--exclude-from exclude.txt specifies that exclusion rules are read from exclude.txt, which contains one rule per line, such as *.csv.

--files-from

stringArray

Reads the list of source object names from a file. Empty lines and comment lines are ignored.

Note

ossutil restore oss://examplebucket/ -r --files-from list.txt specifies that only the objects listed in list.txt are restored. The file contains one object name per line, such as dir/a.txt. Empty lines and comment lines that start with # or ; are ignored.

--files-from-raw

stringArray

Reads the list of source object names from a file.

Note

ossutil restore oss://examplebucket/ -r --files-from-raw list.txt specifies that only the objects listed in list.txt are restored. Each line in the file is used as an object name as is: leading and trailing spaces are not removed, and comment lines are not ignored.

--filter

stringArray

The filter rule for paths or object names.

Note

--filter "+ *.txt" --filter "- *" specifies that only objects whose names end with .txt are processed.

--filter-from

stringArray

Reads filter rules from a rule file.

Note

--filter-from rules.txt specifies that filter rules are read from rules.txt, which contains one rule per line, such as + *.txt and - *.

-f, --force

/

Forces the operation without prompting for confirmation.

Note

ossutil restore oss://examplebucket/dir/ -r -f specifies that the objects in dir/ are restored recursively without prompting for confirmation.

--include

stringArray

The inclusion rule for paths or object names.

Note

--include "*.txt" specifies that only objects whose names end with .txt are processed.

--include-from

stringArray

Reads inclusion rules from a rule file.

Note

--include-from include.txt specifies that inclusion rules are read from include.txt, which contains one rule per line, such as *.txt.

-j, --job

int

The number of concurrent tasks across multiple objects in a batch operation. Default value: 3.

Note

-j 10 specifies that restore requests are sent for 10 objects at the same time.

--limited-num

int

The maximum number of results to return.

Note

--limited-num 100 specifies that a maximum of 100 objects are processed.

--list-objects

/

Lists objects by calling the ListObjects operation.

Note

ossutil restore oss://examplebucket/dir/ -r --list-objects specifies that the objects to restore are listed by calling ListObjects instead of the default ListObjectsV2.

--min-age

Duration

Excludes objects whose last modified time is later than this value. The default unit is seconds. You can also append a unit suffix. For example, 1h indicates one hour.

Note

--min-age 1h specifies that only objects modified one hour ago or earlier are processed.

--max-age

Duration

Excludes objects whose last modified time is earlier than this value. The default unit is seconds. You can also append a unit suffix. For example, 1h indicates one hour.

Note

--max-age 3d specifies that only objects modified within the last 3 days are processed.

--min-mtime

Time

Excludes objects whose last modified time is earlier than this value. The time must be in UTC. Example: 2006-01-02T15:04:05.

Note

--min-mtime "2006-01-02T15:04:05" specifies that only objects modified after 15:04:05 on January 2, 2006 are processed.

--max-mtime

Time

Excludes objects whose last modified time is later than this value. The time must be in UTC. Example: 2006-01-02T15:04:05.

Note

--max-mtime "2006-01-02T15:04:05" specifies that only objects modified before 15:04:05 on January 2, 2006 are processed.

--max-size

SizeSuffix

The maximum size of an object to transfer. The default unit is bytes. You can also append a unit suffix: B, K, M, G, T, or P, where 1K (KiB) = 1024B.

Note

--max-size 100K specifies that only objects no larger than 100 KiB are processed.

--metadata-exclude

stringArray

Excludes objects whose metadata matches the rule. Metadata is matched in the key=value format, and the value supports the * wildcard. If you specify only key= without a value, the rule matches no objects, including objects that have not been restored, so it has the same effect as not setting this exclusion rule.

Note

  1. --metadata-exclude "x-oss-storage-class=DeepColdArchive" specifies that only Deep Cold Archive objects are excluded.

  2. --metadata-exclude "x-oss-restore=*" specifies that objects that are being restored and objects whose restoration is complete are excluded.

  3. --metadata-exclude 'x-oss-restore=ongoing-request="false"*' specifies that only objects whose restoration is complete are excluded.

--metadata-filter

stringArray

The filter rule for object metadata. For details, see Filter objects based on object metadata.

Note

--metadata-filter "+ x-oss-storage-class=ColdArchive" --metadata-filter "- **" specifies that only Cold Archive objects are processed.

--metadata-filter-from

stringArray

Reads object metadata filter rules from a rule file. For details, see Filter objects based on object metadata.

Note

--metadata-filter-from rules.txt specifies that metadata filter rules are read from rules.txt, which contains one rule per line, such as + x-oss-storage-class=ColdArchive and - **.

--metadata-include

stringArray

Includes only objects whose metadata matches the rule. Other objects are excluded by default. Metadata is matched in the key=value format, and the value supports the * wildcard.

Note

  1. --metadata-include "x-oss-storage-class=ColdArchive" specifies that only Cold Archive objects are processed.

  2. --metadata-include "x-oss-storage-class=*Archive" specifies that only Archive, Cold Archive, and Deep Cold Archive objects are processed.

--min-size

SizeSuffix

The minimum size of an object to transfer. The default unit is bytes. You can also append a unit suffix: B, K, M, G, T, or P, where 1K (KiB) = 1024B.

Note

--min-size 100K specifies that only objects no smaller than 100 KiB are processed.

--no-check-status

/

Takes effect only in list:// list mode. Skips the object status check and sends a restore request directly for every object in the list. If this parameter is not specified, list mode works the same way as recursive mode: it skips objects that are being restored and objects whose storage class is not Archive, Cold Archive, or Deep Cold Archive, but still sends another restore request for objects whose restoration is complete. If this parameter is specified, objects that are being restored return the RestoreAlreadyInProgress error, and objects whose storage class is not Archive, Cold Archive, or Deep Cold Archive return the OperationNotSupported error. This parameter has no effect in recursive mode.

Note

ossutil restore list://list.txt --no-check-status specifies that restore requests are sent for all objects in list.txt without checking their status. Confirm the scope of the list before you run the command.

--no-error-report

/

Does not generate an error report file during a batch operation.

Note

ossutil restore oss://examplebucket/dir/ -r --no-error-report specifies that no error report file is generated during a recursive restore operation, even if some objects fail to be restored.

--no-progress

/

Does not display the progress.

Note

ossutil restore oss://examplebucket/dir/ -r --no-progress specifies that the progress is not displayed during a recursive restore operation.

--output-dir

string

The output directory of the error report file generated during a batch operation. Default value: ossutil_output.

Note

--output-dir ./restore_report specifies that the error report file is generated in the restore_report directory.

--page-size

int

The maximum number of objects to return per page when objects are listed in a batch operation. Default value: 1000. Valid values: 1 to 1000.

Note

--page-size 100 specifies that a maximum of 100 objects are returned per page when objects are listed.

-r, --recursive

/

Performs the operation recursively. If this option is specified, the command operates on all matching objects in the bucket. Otherwise, the command operates only on the object specified by the path.

Note

ossutil restore oss://examplebucket/dir/ -r specifies that all matching objects in dir/ and its subdirectories are restored. If -r is not specified, dir/ is treated as the name of a single object.

--request-payer

string

The payer of the request. Set this value if pay-by-requester mode is used. Valid value: requester.

Note

--request-payer requester specifies that the requester pays the fees incurred by this restore request.

--start-after

string

Returns objects whose names are alphabetically after the specified value, excluding the specified value.

Note

--start-after dir/c.txt specifies that only objects whose names are alphabetically after dir/c.txt are processed, excluding dir/c.txt.

--support-dir-object

/

Treats directory objects, which are objects whose names end with /, as regular objects when the object list is read from a file, such as when you use --files-from.

Note

ossutil restore oss://examplebucket/ -r --files-from list.txt --support-dir-object specifies that entries in list.txt that end with /, such as dir/folder/, are restored as directory objects themselves. If this parameter is not specified, such entries match no objects.

--version-id

string

The version ID of the object.

Note

ossutil restore oss://examplebucket/exampleobject.txt --version-id CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** specifies that the specified version of exampleobject.txt is restored.

--list-format

string

The format of the list file. Valid values: plain and inventory.

Note

--list-format inventory specifies that the list file is an inventory result file. In this case, you must also specify --list-manifest-from.

--list-manifest-from

string

Reads the format description of the list file from a file. You must set this parameter if the format of the list file is inventory.

Note

--list-format inventory --list-manifest-from manifest.json specifies that the format description of the list file is read from manifest.json in the inventory results.
Note

For more information, see Command-line options.

Examples

Restore Archive objects

  • The following example restores the Archive object exampleobject.txt in the destination bucket examplebucket.

    ossutil restore oss://examplebucket/exampleobject.txt

  • The following example restores the Archive object exampleobject.txt in the destination bucket examplebucket and keeps the object in the restored state for 3 days.

    ossutil restore oss://examplebucket/exampleobject.txt --days 3

  • The following example restores objects from a list.

    Note

    Each line in the list file represents one object and uses the OSS path format oss://{bucket}/{key}. The following list.txt file is an example:

    oss://examplebucket/key1
oss://examplebucket/key2
    ossutil restore list://list.txt

  • The following example uses list mode to send restore requests directly for the objects in list.txt without checking their status. Objects in the list that are being restored return the RestoreAlreadyInProgress error, and objects whose storage class is not Archive, Cold Archive, or Deep Cold Archive return the OperationNotSupported error.

    ossutil restore list://list.txt --no-check-status

  • The following example restores objects from an inventory file.

    Note

    After an inventory task runs, a csv.gz file and a manifest.json file are generated in the inventory results. Both files are required to restore objects from an inventory file.

    ossutil restore list://ca8007fc-4123-493e-9a01-dd1511fbac54.csv.gz --list-format inventory --list-manifest-from manifest.json

  • The following example restores objects directly from an inventory file without checking the status of the objects.

    ossutil restore list://ca8007fc-4123-493e-9a01-dd1511fbac54.csv.gz --list-format inventory --list-manifest-from manifest.json --no-check-status

Restore Cold Archive objects

The following example restores the Cold Archive object exampleobject.txt in the destination bucket examplebucket and keeps the object in the restored state for 5 days.

ossutil restore oss://examplebucket/exampleobject.txt --tier Bulk --days 5

The following example recursively restores all Cold Archive .csv objects in the dir directory of the destination bucket examplebucket and keeps the objects in the restored state for 5 days.

ossutil restore oss://examplebucket/dir/ -r --include "*.csv" --metadata-include "x-oss-storage-class=ColdArchive" --tier Bulk --days 5

The following example recursively selects Cold Archive objects in the dir directory and explicitly excludes objects whose restoration is complete. The ongoing-request="false" value indicates completed restoration, and the trailing * matches the varying expiry date. Place the exclusion rule before the inclusion rule. The default status check of a batch restore operation skips objects that are still being restored.

ossutil restore oss://examplebucket/dir/ -r --tier Standard --days 365 --metadata-exclude 'x-oss-restore=ongoing-request="false"*' --metadata-include "x-oss-storage-class=ColdArchive"

To exclude both objects that are being restored and objects whose restoration is complete, use x-oss-restore=* instead. Do not use x-oss-restore=, which matches no objects, so the exclusion rule has no effect.

ossutil restore oss://examplebucket/dir/ -r --tier Standard --days 365 --metadata-exclude "x-oss-restore=*" --metadata-include "x-oss-storage-class=ColdArchive"

Restore Deep Cold Archive objects

The following example restores the Deep Cold Archive object exampleobject.txt in the destination bucket examplebucket and keeps the object in the restored state for 10 days.

ossutil restore oss://examplebucket/exampleobject.txt --tier Standard --days 10

The following example recursively restores all Deep Cold Archive .csv objects in the dir directory of the destination bucket examplebucket and keeps the objects in the restored state for 10 days.

ossutil restore oss://examplebucket/dir/ -r --include "*.csv" --tier Standard --days 10

Billing

  • You are charged data retrieval fees when you restore Archive, Cold Archive, and Deep Cold Archive objects. For more information, see Data processing fees.

  • You are charged Put request fees when you restore Archive objects. For more information, see Request fees.

  • You are charged data retrieval request fees when you restore Cold Archive and Deep Cold Archive objects. For more information, see Request fees.

  • Archive, Cold Archive, and Deep Cold Archive objects are charged storage fees based on their respective storage classes both while they are being restored and after they are restored. For more information, see Storage fees.

  • When you restore a Cold Archive or Deep Cold Archive object, a replica of the object is created in the Standard storage class to allow access. While the object is in the restored state, you are charged for the temporary storage of this replica at the rate of the Standard storage class. For more information, see Temporary storage fees.

  • Archive objects can remain in the restored state for up to 7 days. Cold Archive and Deep Cold Archive objects can remain in the restored state for up to 365 days. No additional data retrieval fees are incurred during this period.

  • After the restored state ends, the object returns to the frozen state. If you restore the object again, data retrieval fees are incurred.

Previous：presign (generate signed URL)Next：unrestore (Remove restored objects)