Lease File
The Lease File operation creates and manages a lock on a file for write and delete operations. Lease File is supported for version 2019-02-02 and later.
You can call the Lease File operation in one of the following modes:
Acquire, to request a new lease.Change, to change the ID of an existing lease.Release, to free the lease if it's no longer needed, so that another client can immediately acquire a lease against the file.Break, to forcibly end the lease, but ensure that another client can't acquire a new lease until the current lease period has expired.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS |  |
Request
You can construct the Lease File request as follows. HTTPS is recommended.
| Method | Request URI | HTTP version |
|---|---|---|
Put |
https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease |
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 directory. |
myfile |
The name of the file. |
URI parameters
You can specify the following additional parameter on the request URI.
| Parameter | Description |
|---|---|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Setting timeouts for Azure Files operations. |
Request headers
The following table describes required and optional request headers.
| 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 |
Optional. 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> |
Required to renew, change, or release the lease. You can specify the value of x-ms-lease-id in any valid, GUID string format. See Guid Constructor (String) for a list of valid formats. |
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break> |
acquire: Requests a new lease. If the file doesn't have an active lease, Azure Files creates a lease on the file, and returns a new lease ID. If the file has an active lease, you can only request a new lease by using the active lease ID.change: Changes the lease ID of an active lease. A change must include the current lease ID in x-ms-lease-id, and a new lease ID in x-ms-proposed-lease-id.release: Releases the lease. You can release the lease if the lease ID specified on the request matches that associated with the file. Releasing the lease allows another client to immediately acquire the lease for the file, as soon as the release is complete.break: Breaks the lease, if the file has an active lease. Any authorized request can break the lease. The request isn't required to specify a matching lease ID. An infinite lease is broken immediately. |
x-ms-lease-duration: -1 |
Allowed and required only on an acquire operation. Required to be -1, to indicate a lease that never expires. |
x-ms-proposed-lease-id: <ID> |
Optional for acquire, and required for change. Proposed lease ID, in a GUID string format. Azure Files returns 400 (Invalid request) if the proposed lease ID isn't in the correct format. See Guid Constructor (String) for a list of valid formats. |
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.
Sample request
The following sample request shows how to acquire a lease:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1
Request Headers:
x-ms-version: 2019-07-07
x-ms-lease-action: acquire
x-ms-lease-duration: -1
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-date: <date>
Authorization: SharedKey testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=
Response
The response includes an HTTP status code and a set of response headers.
Status code
The success status codes returned for lease operations are the following:
Acquire: A successful operation returns status code 201 (Created).Change: A successful operation returns status code 200 (OK).Release: A successful operation returns status code 200 (OK).Break: A successful operation returns status code 202 (Accepted).
For information about status codes, see Status and error codes.
Response headers
The response for this operation includes the following headers. The response can also include additional, standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
| Syntax | Description |
|---|---|
ETag |
Contains a value that you can use to perform operations conditionally, in quotes. The Lease File operation doesn't modify this property. |
Last-Modified |
The date/time that the file was last modified. For more information, see Representation of date-time values in headers. Any write operation on the file, including updates on the file's metadata or properties, changes the last-modified time of the file. The Lease File operation doesn't modify this property. |
x-ms-lease-id: <id> |
When you request a lease, Azure Files returns a unique lease ID. While the lease is active, you must include the lease ID with any request to write to the file, or to change, or release the lease. A successful renew operation also returns the lease ID for the active lease. |
x-ms-lease-time: seconds |
Returned only for a successful request to break the lease. 0 is returned for immediate breaks. |
x-ms-request-id |
Uniquely identifies the request that was made, and can be used for troubleshooting the request. For more information, see Troubleshooting API operations. |
x-ms-version |
Indicates the version of Azure Files used to run the request. |
Date |
A UTC date/time value that indicates the time at which the response was initiated. The service generates this value. |
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. The value is at most 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. |
Response body
None.
Sample response
The following is a sample response for a request to acquire a lease:
Response Status:
HTTP/1.1 201 Created
Response Headers:
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2019-07-07
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5
Date: <date>
Authorization
The account owner can call this operation. Additionally, any client with a shared access signature that has permission to write to this file or its share can do so.
Remarks
A lease on a file provides exclusive write and delete access to the file. To write to a file with an active lease, a client must include the active lease ID with the write request. The lease is granted for an infinite duration.
When a client acquires a lease, a lease ID is returned. Azure Files generates a lease ID if one isn't specified in the acquire request. The client can use this lease ID to change its lease ID or release the lease.
When a lease is active, the lease ID must be included in the request for any of the following operations:
- Create File
- Set File Metadata
- Set File Properties
- Delete File
- Put Range
- Copy File (Lease ID needed for destination file.)
If the lease ID isn't included, these operations fail on a leased file, with 412 – Precondition failed.
The following operations succeed on a leased file, without including the lease ID:
- Get File
- Get File Metadata
- Get File Properties
- List Ranges
- List Directories and Files
- Copy File (No lease ID needed for source file.)
- Lease File (REST API) (No lease ID needed for
x-ms-lease-action: break.)
It's not necessary to include the lease ID for GET operations on a file that has an active lease. However, all GET operations support a conditional lease parameter. In this type of parameter, the operation only proceeds if the lease ID included with the request is valid.
All share operations are permitted on a share that includes files with an active lease, including Delete Share. Therefore, you can delete a share even if files within it have active leases.
Lease states
The following diagram shows the three states of a lease, and the commands or events that cause lease state changes.
A lease can be in three states, based on whether the lease is locked or unlocked, and whether the lease is renewable in that state. The lease actions shown in the preceding diagram cause state transitions.
Available: The lease is unlocked and can be acquired. Allowed action:acquire.Leased: The lease is locked. Allowed actions:acquire(same lease ID only),change,release, andbreak.Broken: The lease has been broken. Allowed actions:acquire,release, andbreak.
Note that a lease can't be granted for a file in a share snapshot, because snapshots are read-only. Requesting a lease against a file in a share snapshot results in status code 400 (Bad Request).
If a file lease is in the Broken state and a Put Range operation writes to the file, the lease state will change to Available. However, if the file has the read-only attribute set, the server will return conflict 409.
The file's Last-Modified-Time property isn't updated by calls to Lease File.
The following tables show outcomes of actions on files with leases in various lease states. Letters (A), (B), and (C) represent lease IDs, and (X) represents a lease ID generated by Azure Files.
Outcomes of use attempts on files by lease state
| Action | Available | Leased (A) | Broken (A) |
|---|---|---|---|
| Write by using (A) | Fails (412) | Leased (A), write succeeds | Fails (412) |
| Write by using (B) | Fails (412) | Fails (409) | Fails (412) |
| Write, no lease specified | Available, write succeeds | Fails (412) | Available, write succeeds |
| Read by using (A) | Fails (412) | Leased (A), read succeeds | Fails (412) |
| Read by using (B) | Fails (412) | Fails (409) | Fails (412) |
| Read, no lease specified | Available, read succeeds | Leased (A), read succeeds | Broken (A), read succeeds |
Outcomes of lease operations on files by lease state
| Action | Available | Leased (A) | Broken (A) |
|---|---|---|---|
Acquire, no proposed lease ID |
Leased (X) | Fails (409) | Leased (X) |
Acquire (A) |
Leased (A) | Leased (A) | Leased (A) |
Acquire (B) |
Leased (B) | Fails (409) | Leased (B) |
Break |
Fails (409) | Broken (A) | Broken (A) |
Change, (A) to (B) |
Fails (409) | Leased (B) | Fails (409) |
Change, (B) to (A) |
Fails (409) | Leased (A) | Fails (409) |
Change, (B) to (C) |
Fails (409) | Fails (409) | Fails (409) |
Release (A) |
Fails (409) | Available | Available |
Release (B) |
Fails (409) | Fails (409) | Fails (409) |