You need to enable JavaScript to run this app.
Torch Object Storage

Torch Object Storage

  • Documentation
    • Torch Object StorageAPI ReferenceObjectBasic Object OperationsRenameObject
Copy page
Download PDF
Basic Object Operations
RenameObject
Copy page
Download PDF
RenameObject

Feature description

Call the RenameObject interface to rename an object.

Prerequisites

For flat buckets (FNS): the RenameObject feature must be enabled. For detailed steps, see Use RenameObject or PutBucketRename.
For hierarchical buckets (HNS): RenameObject is supported by default and does not require additional enablement.

Precautions

CategoryPrecautions
PermissionsBefore executing the RenameObject operation, ensure the account you use has RenameObject and PutObject permissions.
Constraints and limitationsThe RenameObject feature is mutually exclusive with the version control feature. If version control is enabled or paused on your bucket, the RenameObject feature cannot be used. (Version control is not yet supported for hierarchical buckets, so this constraint does not apply.)
Renamed contentThe RenameObject interface modifies the object’s name and updates the object's modification time.

The renamed object

  • * Only objects uploaded after enabling RenameObject can be renamed; renaming is not supported for pre-existing objects uploaded before this feature was enabled. (This constraint does not apply to layered buckets).
  • Files of type archive storage, cold archive storage, and deep cold archive storage can only be renamed using the RenameObject feature after they are restored. For detailed operations, see [Restore files](https://www.volcengine.com/docs/6349/302315
  • Concurrent renaming of the same object using the RenameObject feature is not supported.
  • * RenameObject supports renaming objects created by all types, including those created by Put, Multi-Upload, Append, Copy, Rename, etc. After renaming, the Appendable object still retains the same ability to append as the original object.

Request syntax 

PUT /objectName?name=Name&rename HTTP/1.1 
Host: bucketname.tos-cn-beijing.volces.com 
Date: GMT Date 
Authorization: authorization string

Request parameters and headers

This request uses common request headers. See Common parameters.

NameLocationTypeRequiredSample ValueDescription
renameQueryStringYes-Setting the parameter name alone suffices; no need to set the parameter value. This indicates a special identifier for the RenameObject request.
nameQueryStringYesdst-objectThe name after renaming the object.

x-tos-forbid-overwrite

Header

String

No

false

Whether to allow overwriting objects with the same name, the values are explained as follows:

  • false: Allows overwriting objects with the same name.
  • true: Prohibits overwriting objects with the same name.

The default is false, which means overwriting objects with the same name is allowed by default.

x-tos-recursive-mkdir

Header

String

No

true

This parameter applies only to hierarchical buckets, with the following values:

  • false: RenameObject is not allowed if the parent directory of the destination path does not exist.
  • true: Recursively create any missing directories if the parent directory of the destination path does not exist.

Default is false.

Request body elements

There is no request element in this request message.

Response headers

This request returns the common response message headers, please see Common parameters.

Response body elements

There is no message element in this request response.

Sample request 

PUT /src-object?name=dst-object&rename HTTP/1.1 
Host: bucketname.tos-cn-beijing.volces.com 
Date: GMT Date 
Authorization: authorization string

Sample response 

HTTP/1.1 204 No Content 
x-tos-id-2: 367be10900210004-a444ed0 
x-tos-request-id: 367be10900210004-a444ed0 
Date: Fri, 1 Jul 2022 01:00:36 GMT 
Server: TosServer
Last updated: 2025.06.30 17:27:07