Get File
The Get File operation reads or downloads a file from the system, including its metadata and properties.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS |  |
Request
The Get File request may be constructed as follows. We recommend that you use HTTPS.
| Method | Request URI | HTTP version |
|---|---|---|
GET |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
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 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 |
|---|---|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs 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. |
Range |
Optional. Returns file data only from the specified byte range. |
x-ms-range |
Optional. Returns file data only from the specified byte range. If both Range and x-ms-range are specified, the service uses the value of x-ms-range. If neither is specified, the entire file contents are returned. See Specify the range header for Azure Files operations for more information. |
x-ms-range-get-content-md5: true |
Optional. When this header is set to true and it's specified together with the Range header, the service returns the MD5 hash for the range, as long as the range is less than or equal to 4 mebibytes (MiB) in size.If this header is specified without the Range header, the service returns status code 400 (Bad Request).If this header is set to true when the range exceeds 4 MiB in size, the service returns status code 400 (Bad Request). |
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 that's specified in the request matches the lease ID of the file. Otherwise, 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 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-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, a set of response headers, and the response body, which contains the contents of the file.
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 might 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 associated with this file as user-defined metadata. |
Content-Length |
The number of bytes present in the response body. |
Content-Type |
The content type specified for the file. The default content type is application/octet-stream. |
Content-Range |
The range of bytes returned if the client requested a subset of the file by setting the Range request header. |
ETag |
Contains a value that you can use to perform operations conditionally. The value is enclosed in quotation marks. |
Content-MD5 |
If the file has an MD5 hash and the request is to read the full file, this response header is returned so that the client can check for message content integrity. If the request is to read a specified range and the x-ms-range-get-content-md5 is set to true, the request returns an MD5 hash for the range, as long as the range size is less than or equal to 4 MiB.If neither of these sets of conditions is true, no value is returned for the Content-MD5 header.If x-ms-range-get-content-md5 is specified without the range header, the service returns status code 400 (Bad Request).If x-ms-range-get-content-md5 is set to true when the range exceeds 4 MiB, the service returns status code 400 (Bad Request). |
Content-Encoding |
Returns the value that was specified for the Content-Encoding request header. |
Content-Language |
Returns the value that was specified for the Content-Language request header. |
Cache-Control |
Is returned if it was previously specified for the file. |
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 it can also be used 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, instead, should display a Save As window. |
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 |
The service version that was used to execute the request. |
Accept-Ranges: bytes |
Indicates that the service supports requests for partial file content. |
Date |
Date |
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 that used 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. Describes the cause of a fatal or non-fatal copy operation failure. 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 that used 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 the file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation that used 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 that were copied and the total bytes in the source in the last attempted Copy File operation where this file was the destination file. Can show from 0 to the number of copied Content-Length bytes. 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 that used Set File Properties or Create File. |
x-ms-copy-source: url |
Version 2015-02-21 and later. A URL of up to 2 KB in length 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 that used 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:- pending: Copy is in progress. Check x-ms-copy-status-description if intermittent, non-fatal errors impede copy progress but don't cause failure.- success: Copy was completed successfully.- 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 completed Copy File operation that used Set File Properties or Create File. |
x-ms-content-md5 |
As of version 2016-05-31, if the file has an MD5 hash, and if the request contains a range header (range or x-ms-range), this response header is returned with the value of the whole file's MD5 value. This value might or might not be equal to the value that's returned in the Content-MD5 header, which is calculated from the requested range. |
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. If the file is unencrypted, or if only parts of the file/application metadata are encrypted, the value is set to false. |
x-ms-file-permission-key |
The key of the permission of the file. |
x-ms-file-attributes |
The file system attributes on the file. For more information, see the list of available attributes. |
x-ms-file-creation-time |
The UTC date/time value that represents the creation time property for the file. |
x-ms-file-last-write-time |
The UTC date/time value that represents the last write time property for the file. |
x-ms-file-change-time |
The UTC date/time that value that represents the change time property for the file. |
x-ms-file-file-id |
The file ID of the file. |
x-ms-file-parent-id |
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 their 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
The response body contains the contents of the file.
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.
Remarks
Calling Get File over a range that doesn't yet have content or that has been cleared returns 0 for those bytes.
If you call Get File with no range specified, the service returns the range of bytes up to the value that's specified for the x-ms-content-length header. For any ranges that lack content, the service returns 0 for those bytes.
A Get File operation is allowed two minutes per MiB to be completed. Operations that take longer than two minutes per MiB on average will time out.