Set Directory Properties
The Set Directory Properties operation sets system properties for the specified directory. This API is available as of version 2019-02-02.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS |  |
Request
The Set Directory Properties request may be constructed as follows. We recommend that you use HTTPS.
| Method | Request URI | HTTP version |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/mydirectory?restype=directory&comp=properties |
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 file. |
For information about path naming restrictions, see Name and reference shares, directories, files, and metadata.
URI parameters
You can specify the following additional parameters in the request URI:
| Parameter | Description |
|---|---|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for File service operations. |
Request headers
The required and optional request headers are described in the following table:
| 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-permission: { preserve ¦ <SDDL> ¦ <binary> } |
In versions 2019-02-02 to 2021-04-10, this header is required if x-ms-file-permission-key isn't specified. As of version 2021-06-08, both headers are optional. This permission is the security descriptor for the directory that's 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 it's specified, it must have an owner, group, and discretionary access control list (DACL). To keep an existing value unchanged, you can pass a value of preserve.Note: You can specify either x-ms-file-permission or x-ms-file-permission-key. If neither header is specified, the default value of preserve is used for the x-ms-file-permission header. |
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: <PermissionKey> |
In versions 2019-02-02 to 2021-04-10, this header is required if x-ms-file-permission isn't specified. As of version 2021-06-08, both headers are optional. The key of the permission to be set for the file. This can be created using the Create-Permission API.Note: You can specify either x-ms-file-permission or x-ms-file-permission-key. If neither header is specified, the default value of preserve is used for the x-ms-file-permission header. |
x-ms-file-attributes: { preserve ¦ <FileAttributeList> } |
Required for versions 2019-02-02 to 2021-04-10. Optional for version 2021-06-08 and later. The file system attributes to be set on the file. See the list of available attributes. A value of preserve may be passed to keep an existing value unchanged. The default value is preserve. |
x-ms-file-creation-time: { preserve ¦ <DateTime> } |
Required for versions 2019-02-02 to 2021-04-10. Optional for version 2021-06-08 and later. The Coordinated Universal Time (UTC) creation time property for a directory. A value of preserve may be passed to keep an existing value unchanged. The default value is preserve. |
x-ms-file-last-write-time: { preserve ¦ <DateTime> } |
Required for versions 2019-02-02 to 2021-04-10. Optional for version 2021-06-08 and later. The Coordinated Universal Time (UTC) last write property for a directory. A value of preserve may be passed to keep an existing value unchanged. The default value is preserve. |
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 Files. |
x-ms-file-change-time: { now ¦ <DateTime> } |
Optional. Version 2021-06-08 and later. The Coordinated Universal Time (UTC) change time property for the directory, formatted in the ISO 8601 format. You can use a value of now to indicate the time of the request. The default value is now. |
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. |
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 more information about status codes, see Status and error codes.
Response headers
The response for this operation includes the following headers. The response may 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. The value is enclosed in quotation marks. |
Last-Modified |
Returns the date and time when the directory was last modified. The date format follows RFC 1123. For more information, see Represent 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 it can be used to troubleshoot the request. For more information, see Troubleshoot API operations. |
x-ms-version |
Indicates the File service version that was used to execute the request. |
Date or x-ms-date |
A UTC date/time value that's generated by the service, which indicates the time when the response was initiated. |
x-ms-request-server-encrypted: true/false |
Version 2017-04-17 and later. 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 |
Version 2019-02-02 and later. The key of the permission of the directory. |
x-ms-file-attributes |
Version 2019-02-02 and later. The file system attributes on the directory. For more information, see the list of available attributes. |
x-ms-file-creation-time |
Version 2019-02-02 and later. The UTC date/time value that represents the creation time property for the directory. |
x-ms-file-last-write-time |
Version 2019-02-02 and later. The UTC date/time value that represents the last write time property for the directory. |
x-ms-file-change-time |
Version 2019-02-02 and later. The UTC date/time value that represents the change time property for the directory. |
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 and the value contains no more than 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 may call this operation.
File system attributes
| Attribute | Win32 file attribute | Definition |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | A directory that's 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 it's used alone. |
| Directory | FILE_ATTRIBUTE_DIRECTORY | The handle that identifies a directory. |
| Archive | FILE_ATTRIBUTE_ARCHIVE | A directory that's 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 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
Set Directory Properties isn't supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot fails with 400 (InvalidQueryParameterValue).
Properties that are set on a directory with Set Directory Properties don't propagate to any subdirectories beneath that directory. You must call Set Directory Properties for each directory for which you want to update properties.