Set File Properties

The Set File Properties operation sets system properties on the file.

Protocol availability

Enabled file share protocol Available
SMB Yes
NFS No

Request

The Set File 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/myfile?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.
myfile 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-cache-control Optional. Modifies the cache control string for the file.

If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties will not return this property, unless it is explicitly set on the file again.
x-ms-content-type Optional. Sets the file's content type.

If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties will not return this property, unless it is explicitly set on the file again.
x-ms-content-md5 Optional. Sets the file's MD5 hash.

If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties will not return this property, unless it is explicitly set on the file again.
x-ms-content-encoding Optional. Sets the file's content encoding.

If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties will not return this property, unless it is explicitly set on the file again.
x-ms-content-language Optional. Sets the file's content language.

If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties will not return this property, unless it is explicitly set on the file again.
x-ms-content-disposition Optional. Sets the file's Content-Disposition header.

If this property isn't specified on the request, the property is cleared for the file. Subsequent calls to Get File Properties will not return this property, unless it is explicitly set on the file again.
x-ms-content-length: bytes Optional. Resizes a file to the specified size. If the specified byte value is less than the current size of the file, all ranges above the specified byte value are cleared.
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 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, it must have an owner, group, and discretionary access control list (DACL). A value of preserve may be passed to keep an existing value unchanged.

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.
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, version 2019-02-02 to 2021-04-10. Optional, 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, version 2019-02-02 to 2021-04-10. Optional, version 2021-06-08 and later. The Coordinated Universal Time (UTC) creation time property for a file. 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, version 2019-02-02 to 2021-04-10. Optional, version 2021-06-08 and later. The Coordinated Universal Time (UTC) last write property for a file. A value of preserve may be passed to keep an existing value unchanged. If preserve is specified and the size of the file is changed, the last write time is updated to the current time. If the size of the file is changed, but an explicit timestamp is provided, the explicit timestamp is used. The default value is preserve.
x-ms-lease-id: <ID> Required if the file has an active lease. Available for version 2019-02-02 and later.
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 file, 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 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 file 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 can be used to troubleshoot the request. For more information, see Troubleshoot API operations.
x-ms-version Indicates the version of the File service 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 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 file.
x-ms-file-attributes Version 2019-02-02 and later. The file system attributes on the file. 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 file.
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 file.
x-ms-file-change-time Version 2019-02-02 and later. The UTC date/time value that represents the change time property for 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 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 file that's 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 it's used alone.
Archive FILE_ATTRIBUTE_ARCHIVE A file that's an archive file. Applications ordinarily use this attribute to mark files for backup or removal.
Temporary FILE_ATTRIBUTE_TEMPORARY A file that's 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 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 semantics for updating a file's properties are as follows:

  • A file's size is modified only if the request specifies a value for the x-ms-content-length header.

  • If a request sets only x-ms-content-length and no other properties, no other properties of the file are modified.

  • If any one or more of the following properties is set in the request, all these properties are set together. If a value isn't provided for a specified property when at least one of the following properties is set, that property is cleared for the file.

    • x-ms-cache-control
    • x-ms-content-type
    • x-ms-content-md5
    • x-ms-content-encoding
    • x-ms-content-language

Note

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

Set File 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).

If the file has an active lease, the client must specify a valid lease ID on the request to write properties to the file. If the client doesn't specify a lease ID or it specifies an invalid lease ID, the File service returns status code 412 (Precondition Failed). If the client specifies a lease ID but the file doesn't have an active lease, the File service also returns status code 412 (Precondition Failed).

See also

Operations on Azure Files