Rename File

The Rename File operation renames a file, and can optionally set system properties for the file. This API is available in version 2021-04-10 and later.

Protocol availability

Enabled file share protocol Available
SMB Yes
NFS No

Request

You can construct the Rename File request as follows. HTTPS is recommended.

Method Request URI HTTP version
PUT https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rename HTTP/1.1

Replace the path components shown in the request URI with your own, as follows:

Path component Description
myaccount The name of your storage account.
myshare The name of your file share.
mydirectorypath Optional. The path to the parent target directory.
myfile The name of the target file.

For details on path naming restrictions, see Naming and referencing shares, directories, files, and metadata.

URI parameters

You can specify the following additional parameter on the request URI.

Parameter Description
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Setting timeouts for Azure Files operations.

Request headers

The following table describes required and optional request headers.

Request header Description
Authorization Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.
Date or x-ms-date Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
x-ms-version Required for all authorized requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.
x-ms-file-rename-source:name Required. Full URI of the file to be renamed.
x-ms-file-rename-replace-if-exists Optional. If the destination file already exists, overwrite the file.
x-ms-file-rename-ignore-readonly Optional. If the destination file exists with the readonly attribute, overwrite the file.

If true, x-ms-file-rename-replace-if-exists must also be true.
x-ms-content-Type Optional. Sets the file's content type.

If this property isn't specified on the request, then the property will be preserved for the file.
x-ms-file-permission: { preserve ¦ <SDDL> ¦ <binary> } Optional if x-ms-file-permission-key isn't specified. This permission is the security descriptor for the file specified in the Security Descriptor Definition Language (SDDL) or (version 2024-11-04 or later) in base64-encoded binary security descriptor format. You can specify which format to use with the x-ms-file-permission-format header. You can use this header if the permissions size is 8 kibibytes (KiB) or less. Otherwise, you can use x-ms-file-permission-key. If specified, this permission must have an owner, group, and discretionary access control list. You can pass a value of preserve if you want to keep an existing value unchanged.

Note that you can specify either x-ms-file-permission or x-ms-file-permission-key, not both.
x-ms-file-permission-format: { sddl ¦ binary } Optional. Version 2024-11-04 or later. Specifies whether the value passed in x-ms-file-permission is in SDDL or in binary format. If x-ms-file-permission-key is set to preserve, this header should not be set. If x-ms-file-permission-key is set to any other value than preserve, and if this header is not set, the default value of sddl is used.
x-ms-file-permission-key Optional if x-ms-file-permission isn't specified. The key of the permission to be set for the file. You can create this by using the Create-Permission API.

Note that you can specify either x-ms-file-permission or x-ms-file-permission-key, not both.
x-ms-file-attributes Optional. The file system attributes to be set on the file. See the list of available attributes. You can pass a value of preserve if you want to keep an existing value unchanged. If you don't specify this property on the request, then the property will be preserved for the file.
x-ms-file-creation-time Optional. The UTC creation time property for a file. You can pass a value of preserve if you want to keep an existing value unchanged. If you don't specify this property on the request, then the property will be preserved for the file.
x-ms-file-last-write-time Optional. The UTC last write property for a file. You can pass a value of preserve if you want to keep an existing value unchanged. If you don't specify this property on the request, then the property will be preserved for the file.
x-ms-source-lease-id:<ID> Required if the source file has an active lease.
x-ms-destination-lease-id:<ID> Required if the destination file has an active lease.
x-ms-client-request-id Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.
x-ms-meta-name:value Optional. Sets a name-value pair for the file.

Each call to this operation replaces all existing metadata attached to the file.

Metadata names must adhere to the naming rules for C# identifiers.
x-ms-file-request-intent Required if Authorization header specifies an OAuth token. Acceptable value is backup. This header specifies that the Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action or Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action should be granted if they are included in the RBAC policy assigned to the identity that is authorized using the Authorization header. Available for version 2022-11-02 and later.
x-ms-allow-trailing-dot: { <Boolean> } Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in request url should be trimmed or not. For more information, see Naming and referencing shares, directories, files, and metadata.
x-ms-source-allow-trailing-dot: { <Boolean> } Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in source url should be trimmed or not. This header should be specified only if copy source is an Azure File. This header is not supported for any other copy source type. For more information, see Naming and referencing shares, directories, files, and metadata.

Request body

None.

Response

The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 200 (OK). For information about status codes, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response can also include additional, standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header Description
ETag Contains a value that represents the version of the file, in quotes.
Last-Modified Returns the date and time the file was last modified. For more information, see Representation of date-time values in headers. Any operation that modifies the directory, or its properties, updates the last modified time. Operations on files don't affect the last modified time of the directory.
x-ms-request-id Uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API operations.
x-ms-version Indicates the version of Azure Files used to run the request.
Date or x-ms-date A UTC date/time value that indicates the time at which the response was initiated. The service generates this value.
x-ms-request-server-encrypted: true/false The value of this header is set to true if the contents of the request are successfully encrypted by using the specified algorithm. Otherwise, the value is set to false.
x-ms-file-permission-key The key of the permission of the file.
x-ms-file-attributes The file system attributes on the file. See the list of available attributes.
x-ms-file-creation-time The UTC date/time value that represents the creation time property for the file.
x-ms-file-last-write-time The UTC date/time value that represents the last write time property for the file.
x-ms-file-change-time The UTC date/time that value that represents the change time property for the file.
x-ms-file-file-id The file ID of the file.
x-ms-file-parent-id The parent file ID of the file.
x-ms-client-request-id Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header, if it's present in the request. The value is at most 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it won't be present in the response.

Response body

None.

Authorization

Only the account owner can call this operation.

File system attributes

Attribute Win32 file attribute Definition
ReadOnly FILE_ATTRIBUTE_READONLY A file that is read-only. Applications can read the file, but can't write to it or delete it.
Hidden FILE_ATTRIBUTE_HIDDEN The file is hidden. It isn't included in an ordinary directory listing.
System FILE_ATTRIBUTE_SYSTEM A file that the operating system uses a part of, or uses exclusively.
None FILE_ATTRIBUTE_NORMAL A file that doesn't have other attributes set. This attribute is valid only when used alone.
Archive FILE_ATTRIBUTE_ARCHIVE A file that is an archive file. Applications typically use this attribute to mark files for backup or removal.
Temporary FILE_ATTRIBUTE_TEMPORARY A file that is being used for temporary storage.
Offline FILE_ATTRIBUTE_OFFLINE The data of a file isn't available immediately. This file system attribute is presented primarily to provide compatibility with Windows. Azure Files doesn't support with offline storage options.
NotContentIndexed FILE_ATTRIBUTE_NOT_CONTENT_INDEXED The file isn't to be indexed by the content indexing service.
NoScrubData FILE_ATTRIBUTE_NO_SCRUB_DATA The user data stream isn't to be read by the background data integrity scanner. This file system attribute is presented primarily to provide compatibility with Windows.

Remarks

The target can't be an existing directory.

If you don't specify properties, the default behavior of preserve or now will be set.

Note

The preceding file properties are discrete from the file system properties available to SMB clients. SMB clients can't read, write, or modify these property values.

Rename File isn't supported on a share snapshot, which is a read-only copy of a share. If you attempt to perform this operation on a share snapshot, the service returns error status 400 (Invalid Query Parameter Value).

If the file has an active lease, the client must specify a valid lease ID on the request in order to rename the file. If the client doesn't specify a lease ID, or specifies an invalid lease ID, Azure Files returns status code 412 (Precondition Failed). If the client specifies a lease ID, but the file doesn't have an active lease, Azure Files also returns status code 412 (Precondition Failed).

See also

Operations on files