Put Range
The Put Range operation writes a range of bytes to a file.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS |  |
Request
The Put Range 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=range |
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
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 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. |
Range or x-ms-range |
Either Range or x-ms-range is required.Specifies the range of bytes to be written. Both the start and end of the range must be specified. This header is defined by the HTTP/1.1 protocol specification. For an update operation, the range can be up to 4 MiB in size. For a clear operation, the range can be up to the value of the file's full size. The File service accepts only a single byte range for the Range and x-ms-range headers, and the byte range must be specified in the following format: bytes=startByte-endByte.If both Range and x-ms-range are specified, the service uses the value of x-ms-range. For more information, see Specify the range header for File service operations. |
Content-Length |
Required. Specifies the number of bytes being transmitted in the request body. When the x-ms-write header is set to clear, the value of this header must be set to 0. |
Content-MD5 |
Optional. An MD5 hash of the content. This hash is used to verify the integrity of the data during transport. When the Content-MD5 header is specified, Azure Files compares the hash of the content that has arrived with the header value that was sent. If the two hashes don't match, the operation fails with error code 400 (Bad Request).The Content-MD5 header isn't permitted when the x-ms-write header is set to clear. If it's included with the request, the File service returns status code 400 (Bad Request). |
x-ms-write: { update ¦ clear } |
Required. You must specify one of the following options:
|
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-last-write-time: { now ¦ preserve } |
Optional. Version 2021-06-08 and later. You may specify one of the following options:
|
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
The data representing the range to be uploaded.
Sample request: Update byte range
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Sample request: Clear byte range
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Response
The response includes an HTTP status code and a set of response headers.
Status code
A successful operation returns status code 201 (Created).
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 |
The ETag contains a value which represents the version of the file. The value is enclosed in quotation marks. |
Last-Modified |
Returns the date and time 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 share or its properties or metadata updates the last modified time. Operations on files don't affect the last modified time of the share. |
Content-MD5 |
This header is returned so that the client can check for message content integrity. The value of this header is computed by the File service. It isn't necessarily the same as the value that's specified in the request headers. |
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 |
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-client-request-id |
This header 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. |
x-ms-file-last-write-time |
Version 2021-06-08 and later. The last write time for the file, in the ISO 8601 format. Example: 2017-05-10T17:52:33.9551861Z. |
Response body
None.
Sample response
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Authorization
Only the account owner may call this operation.
Remarks
The Put Range operation writes a range of bytes to a file. This operation can be called on an existing file only. It can't be called to create a new file. Calling Put Range with a file name that doesn't currently exist returns status code 404 (Not Found).
To create a new file, call Create File. A file can be up to 4 TiB in size.
A Put Range operation is permitted 10 minutes per MiB to complete. If the operation is taking longer than 10 minutes per MiB on average, it times out.
If the file has an active lease, the client must specify a valid lease ID on the request to write a range.
Range update operations
Calling Put Range with the Update option performs an in-place write on the specified file. Any content in the specified range is overwritten with the update. Each range that's submitted with Put Range for an update operation may be up to 4 MiB in size. If you attempt to upload a range that's larger than 4 MiB, the service returns status code 413 (Request Entity Too Large).
Range clear operations
Calling Put Range with the Clear option releases the space in storage as long as the specified range is 512-byte aligned. Ranges that have been cleared are no longer tracked as part of the file and aren't returned in the List Range response. If the specified range isn't 512-byte aligned, the operation writes zeros to the start or end of the range that isn't 512-byte aligned and frees the rest of the range inside that's 512-byte aligned.
Any ranges that haven't been cleared are returned in the List Ranges response. For an example, see the "Sample unaligned clear range" section that follows.
File lease
You can call Lease File to obtain an exclusive write lock to the file against other writes for an infinite duration.
SMB client byte range locks
The SMB protocol allows byte range locks to manage read and write access to regions of a file. This means that Put Range fails if an SMB client has a lock that overlaps with the range specified by the Put Range operation using x-ms-range. For more information, see Manage file locks.
SMB client directory change notifications
The SMB protocol supports the FindFirstChangeNotification API function that allows applications to detect when changes occur in the file system. It can detect when a file or directory is added, changed, or deleted, and when a file's size, attributes, or security descriptors change. SMB clients that use this API won't receive notifications when a file or directory change happens via the Azure Files REST API. However, changes caused by other SMB clients propagate notifications.
Sample unaligned clear range
Suppose that a file is created with Create File and a single range is written with Put Range, as follows:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Performing a List Ranges operation on the file returns the following response body:
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Now suppose that an unaligned clear range byte range operation is performed:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
A subsequent List Ranges operation on the file returns the following response body:
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
Note that zeros have been written to the unaligned space from 768-1024 and 2048-2304.
Put Range 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).