Get File Properties
The Get File Properties operation returns all user-defined metadata, standard HTTP properties, and system properties for the file. It doesn't return the content of the file.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS |  |
Request
The Get File Properties request may be constructed as follows. We recommend that you use HTTPS.
| Method | Request URI | HTTP version |
|---|---|---|
HEAD |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
HEAD |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime> |
HTTP/1.1 |
Replace the path components that are 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
The following additional parameters may be specified on the request URI:
| Parameter | Description |
|---|---|
sharesnapshot |
Optional. Version 2017-04-17 and later. The sharesnapshot parameter is an opaque DateTime value that, when present, specifies the share snapshot to query for the file properties. |
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set timeouts for Azure Files 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-lease-id:<ID> |
Optional. Version 2019-02-02 and later. If the header is specified, the operation is performed only if the file's lease is currently active and the lease ID specified in the request matches the lease ID of the file. If it doesn't match, the operation fails with status code 412 (Precondition Failed). |
x-ms-client-request-id |
Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit, which is recorded in the analytics logs when Azure Storage Analytics logging is enabled. We highly recommend that you use this header when you're correlating client-side activities with requests that are received by the server. For more information, see Monitor Azure Blob Storage. |
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 |
|---|---|
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 file or its properties updates the last modified time. |
x-ms-meta-name:value |
A set of name-value pairs that are associated with this file as user-defined metadata. |
x-ms-type: <File> |
Returns the type File. Reserved for future use. |
Content-Length |
The size of the file in bytes. This header returns the value of the x-ms-content-length header that's stored with the file. |
Content-Type |
The content type that's specified for the file. If no content type is specified, the default content type is application/octet-stream. |
ETag |
The ETag contains a value that you can use to perform operations conditionally. The value is enclosed in quotation marks. |
Content-MD5 |
If the Content-MD5 header has been set for the file, the Content-MD5 response header is returned so that the client can check for message content integrity. |
Content-Encoding |
If the Content-Encoding request header has previously been set for the file, the Content-Encoding value is returned in this header. |
Content-Language |
If the Content-Language request header has previously been set for the file, the Content-Language value is returned in this header. |
Cache-Control |
If the Cache-Control request header has previously been set for the file, the Cache-Control value is returned in this header. |
Content-Disposition |
Returns the value that was specified for the x-ms-content-disposition header and specifies how to process the response.The Content-Disposition response header field conveys additional information about how to process the response payload, and you can use it to attach additional metadata. For example, if it's set to attachment, Content-Disposition indicates that the user-agent shouldn't display the response, but it should display a Save As window instead. |
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 service version that was used to execute the request. |
Date |
A UTC date/time value that's generated by the service, which indicates the time when the response was initiated. |
x-ms-copy-completion-time:<datetime> |
Version 2015-02-21 and later. The conclusion time of the last attempted Copy File operation where this file was the destination file. This value can specify the time of a completed, aborted, or failed copy attempt. This header doesn't appear if a copy is pending, if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File. |
x-ms-copy-status-description: <error string> |
Version 2015-02-21 and later. Appears only when x-ms-copy-status is failed or pending. It describes the cause of fatal or non-fatal copy operation failure. This header doesn't appear if a copy is pending, if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File. |
x-ms-copy-id: <id> |
Version 2015-02-21 and later. The string identifier for the last attempted Copy File operation where this file was the destination file. This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File. |
x-ms-copy-progress: <bytes copied/bytes total> |
Version 2015-02-21 and later. Contains the number of bytes copied and the total bytes in the source in the last attempted Copy File operation where this file was the destination file. Can show between 0 and the number of Content-Length bytes copied. This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File. |
x-ms-copy-source: url |
Version 2015-02-21 and later. A URL of up to 2 KB characters that specifies the source file that was used in the last attempted Copy File operation where this file was the destination file. This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File. |
x-ms-copy-status: <pending ¦ success ¦ aborted ¦ failed> |
Version 2015-02-21 and later. The state of the copy operation that's identified by x-ms-copy-id, with these values:- success: Copy completed successfully. - pending: Copy is in progress. Check x-ms-copy-status-description if intermittent, non-fatal errors impede copy progress but don't cause failure.- aborted: Copy was ended by Abort Copy File. - failed: Copy failed. See x-ms-copy-status-description for failure details.This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File. |
x-ms-server-encrypted: true/false |
Version 2017-04-17 and later. The value of this header is set to true if the file data and application metadata are completely encrypted by using the specified algorithm. The value is set to false if the file is unencrypted, or if only parts of the file or application metadata are encrypted. |
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 of 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 a 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-file-file-id |
Version 2019-02-02 and later. The file ID of the file. |
x-ms-file-parent-id |
Version 2019-02-02 and later. The parent file ID of the file. |
x-ms-lease-duration:infinite |
Version 2019-02-02 and later. When a file is leased, specifies that the lease is of infinite duration. |
x-ms-lease-state:<available;leased;broken> |
Version 2019-02-02 and later. When a file is leased, specifies the lease state of the file. |
x-ms-lease-status:<locked;unlocked> |
Version 2019-02-02 and later. When a file is leased, specifies the lease status 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 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 isn't present in the response. |
Response body
None.
Sample response
Response Status:
HTTP/1.1 200 OK
Response Headers:
x-ms-type: File
x-ms-meta-m1: v1
x-ms-meta-m2: v2
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Date: <date>
ETag: "0x8CB171DBEAD6A6B"
Last-Modified: <date>
x-ms-version: 2019-02-02
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
x-ms-copy-id: 36650d67-05c9-4a24-9a7d-a2213e53caf6
x-ms-copy-source: <url>
x-ms-copy-status: success
x-ms-copy-progress: 11/11
x-ms-copy-completion-time: <date>
x-ms-lease-duration: infinite
x-ms-lease-state: leased
x-ms-lease-status: locked
Authorization
Only the account owner may call this operation.