Set File Properties

Artikel
08/06/2024

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

Protocol availability

Enabled file share protocol	Available
SMB
NFS

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

Kongsi melalui