Put Range From URL

Article
03/28/2023

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 API is available as of version 2019-02-02.

Protocol availability

Enabled file share protocol	Available
SMB
NFS

Request

The Put Range From URL request may be constructed as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account:

Method	Request URI	HTTP version
`PUT`	`https://myaccount.file.core.windows.net/myshare/myfile?comp=range`	HTTP/1.1

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 table:

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. For more information, see Versioning for the Azure Storage services. For `Put Range From URL`, the version must be 2019-02-02 or later.
`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: `https://myaccount.file.core.windows.net/myshare/mydir/myfile` `https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>`
`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 Azure Active Directory. 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. To perform this operation on a file with an active lease, specify the valid lease ID for this header.
`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: `now`: Default value. Updates the last write time timestamp to the time of the request. `preserve`: Keeps the existing last write timestamp unchanged.
`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.
`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 an Azure File. This header is not supported for any other copy source type. For more information, see Naming and referencing shares, directories, files, and metadata.

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

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

This operation can be called by the account owner and by anyone with a shared access signature with permissions to write to this file or the Azure file share.

Remarks

The Put Range From URL operation writes a range of data to a file. If the API is called on a non-existent file on target, the API returns HTTP status code 404 (Not Found).

In version 2020-10-02 and later, Azure Active Directory authorization is supported for the source of the copy operation.

To create a new file, call Create File.

Put Range From URL operation returns success 201 (Created) only if the specified range is written to the file.

File read operation
Put Range From URL uses Get File to read data and metadata, attributes, and ACLs from the source.

File update operation
Calling Put Range From URL with the "update" option performs an in-place write on the specified file. Any content in the specified file is overwritten with the update.  

The range size in the Put Range From URL operation for an update operation can be up to 4 MiB in size. If you attempt to upload a range that's larger than 4 MiB, Azure Files returns status code 413 (RequestEntityTooLarge).