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 |  |
| NFS |  |
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).