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 Yes
NFS No

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.

See also

Operations on Directories