Put Range From URL
The Put Range From URL operation creates a new range to be committed as part of a file where the contents are read from a URL. This operation is supported in version 2019-02-02 and later for File Shares with SMB protocol enabled, and supported in version 2025-05-05 and later for File Shares with NFS protocol enabled.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS | |
Request
The Put Range From URL request is 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
| 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 tables:
Common request headers
| Request header | Description |
|---|---|
Authorization |
Required. Specifies the authorization scheme, account name, and signature. See Authorize requests to Azure Storage for more information. |
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. This operation is supported in version 2019-02-02 and later for File Shares with SMB protocol enabled, and supported in version 2025-05-05 and later for File Shares with NFS protocol enabled. For more information, see Versioning for the Azure Storage services. |
x-ms-copy-source:name |
Required. Specifies the URL of the source file. The value may be a URL of up to 2 KiB in length that specifies a file. The value should be URL-encoded as it would appear in a request URI. The source file must either be public or must be authorized via a shared access signature. If the source file is public, no authorization is required to perform the operation. Here are some examples of source object URLs:
|
x-ms-copy-source-authorization: <scheme> <signature> |
Optional. Specifies the authorization scheme and signature for the copy source. For more information, see Authorize requests to Azure Storage. Only the scheme bearer is supported for Microsoft Entra. This header is supported in version 2020-10-02 and later. |
x-ms-write: { update } |
Required. You must specify only update. The request fails if it's called with clear. The update value writes the bytes that are specified by the request body into the specified ranges. |
Range or x-ms-range |
Required. 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. Azure Files 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 Azure Files operations. |
x-ms-source-range |
Required. Specifies the range of bytes to be read from the source. Both the start and end of the range must be specified. Azure Files 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.The source range can be up to 4 MiB in size. If the source range size exceeds 4 MiB, Azure Files returns status code 413 (Request Entity Too Large). If the source range size doesn't match range (target range) size, the service returns status code 400 (Bad Request). |
Content-Length |
Required. Specifies the number of bytes being transmitted in the request body. The value of this header must be set to 0. When the length isn't 0, the operation fails with the status code 400 (Bad Request). |
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-source-content-crc64 |
Optional. A CRC64 hash of the specified range from the URI. This hash is used to verify the integrity of the range during transport of the data from the URI. When this header is specified, Azure Files compares the hash of the content that has arrived from the copy-source with this header value. Note: This CRC64 hash isn't stored with the file. If the two hashes don't match, the operation fails with error code 400 (Bad Request). |
x-ms-source-if-match-crc64 |
Optional. A CRC64 checksum value. Specify this header to perform the operation only if the checksum of the given range read from source matches from the provided checksum. If the specified condition isn't met, Azure Files returns status code 412 (Precondition Failed). |
x-ms-source-if-none-match-crc64 |
Optional. A CRC64 checksum value. Specify this header to perform the operation only if the checksum of the given range read from source is different from the provided checksum. If the specified condition isn't met, Azure Files returns status code 412 (Precondition Failed). |
x-ms-lease-id: <ID> |
Required if the file has an active lease. Available for version 2019-02-02 and later. This header is ignored if the file is located on a File Share with NFS protocol enabled, which does not support file leases. |
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 Blob Storage. |
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. This header is ignored if the target is located on a File Share with NFS protocol enabled, which supports trailing dot by default. For more information, see Naming and referencing shares, directories, files, and metadata. |
x-ms-source-allow-trailing-dot: { <Boolean> } |
Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in source url should be trimmed or not. This header should be specified only if copy source is located on an Azure File Share. This header is not supported for any other copy source type. This header is ignored if the copy source is located on a File Share with NFS protocol enabled, which supports trailing dot by default. For more information, see Naming and referencing shares, directories, files, and metadata. |
SMB only request headers
None.
NFS only request headers
None.
Request body
No request body.
Sample request
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-page-write: update
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT
x-ms-version: 2019-02-02
x-ms-range: bytes=100-1023
x-ms-source-range: bytes=200-1123
x-ms-source-content-crc64: 3bedb8b3730fc205
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 0
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 headers in the following tables. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
Common response headers
| Response header | Description |
|---|---|
ETag |
Contains a value that you can use to perform operations conditionally. The value is enclosed in quotation marks. |
Last-Modified |
The date and time that the file was last modified. The date format follows RFC 1123. For more information, see Representation of Date/Time Values in headers. Any write operation on the file, including updates to the file's metadata or properties, changes the last modified time of the file. |
x-ms-request-id |
Uniquely identifies the request that was made, and you can use it to troubleshoot the request. For more information, see Troubleshoot API operations. |
x-ms-version |
Indicates the FileREST API 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-content-crc64 |
Returned so that the client can check for message content integrity. The value of this header is computed by Azure Files. It isn't necessarily the same as the value that's specified in the request headers. |
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. |
x-ms-file-last-write-time |
Version 2021-06-08 and later. The last write time for the file, in ISO 8601 format (for example, 2017-05-10T17:52:33.9551861Z). |
SMB only response headers
None.
NFS only response headers
None.
Response body
None.
Sample response
Response Status:
HTTP/1.1 201 Created
Response Headers:
Date: Sun, 22 Aug 2020 01:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205
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 From URL operation writes a range of data to a file, and is similar in behavior to the Put Range operation. It uses the Get File operation on the specified source to read data, metadata, and other properties of the source file. In version 2020-10-02 and later, Microsoft Entra authorization is supported for the source of the copy operation.
The Put Range From URL operation returns success 201 (Created) only if the specified range is written to the file.