Rename Directory
The Rename Directory operation renames a directory, and can optionally set system properties for the directory. 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 Directory request as follows. HTTPS is recommended.
| Method | Request URI | HTTP version |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/mydirectory?restype=directory&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 directory. |
mydirectory |
The name of the target directory. |
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 directory to be renamed. |
x-ms-file-rename-ignore-readonly |
Optional. If destination directory exists with the readonly attribute, overwrite the directory.If true, x-ms-file-rename-replace-if-exists must also be true. |
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 directory 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 directory. 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 directory. See the list of available attributes. You can pass a value of preserve if you want to keep an existing value unchanged. If this property isn't specified on the request, then the property will be preserved. |
x-ms-file-creation-time |
Optional. The UTC creation time property for a directory. You can pass a value of preserve if you want to keep an existing value unchanged. If this property isn't specified on the request, then the property will be preserved. |
x-ms-file-last-write-time |
Optional. The UTC last write property for a directory. You can pass a value of preserve if you want to keep an existing value unchanged. If this property isn't specified on the request, then the property will be preserved. |
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 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 directory. Each call to this operation replaces all existing metadata attached to the directory. Metadata names must adhere to the naming rules for C# identifiers. If this property isn't specified on the request, then the property will be preserved. |
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 share. This header isn't 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 directory that is read-only. |
Hidden |
FILE_ATTRIBUTE_HIDDEN | The directory is hidden. It isn't included in an ordinary directory listing. |
System |
FILE_ATTRIBUTE_SYSTEM | A directory that the operating system uses a part of, or uses exclusively. |
None |
FILE_ATTRIBUTE_NORMAL | A directory that doesn't have other attributes set. This attribute is valid only when used alone. |
Directory |
FILE_ATTRIBUTE_DIRECTORY | The handle that identifies a directory. |
Archive |
FILE_ATTRIBUTE_ARCHIVE | A directory that is an archive directory. Applications typically use this attribute to mark files for backup or removal. |
Offline |
FILE_ATTRIBUTE_OFFLINE | The data of a directory 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 directory 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
If the target is a directory, then the directory must not exist.
Rename Directory 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 you don't specify properties, the default behavior of preserve or now will be set.
If the directory has an active lease, the client must specify a valid lease ID on the request in order to rename the directory. 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 directory doesn't have an active lease, Azure Files also returns status code 412 (Precondition Failed).