Lease Share
The Lease Share operation establishes and manages a lock on an Azure file share or a share snapshot. This API is fully supported, but it's a legacy management API. Instead, use File Shares - Lease, provided by the storage resource provider (Microsoft.Storage). To learn more about programmatically interacting with FileShare resources by using the storage resource provider, see Operations on FileShares.
The lock duration can be 15 to 60 seconds, or can be infinite. You can call the Lease Share operation in one of the following modes:
Acquire: To request a new lease.Renew: To renew an existing 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 share.Break: To end the lease, but ensure that another client can't acquire a new lease until the current lease period has expired.
Note
The Lease Share operation is available in version 2020-02-10 and later.
Protocol availability
| Enabled file share protocol | Available |
|---|---|
| SMB |  |
| NFS | |
Request
You can construct the Lease Share request as follows. HTTPS is recommended. Replace myaccount with the name of your storage account.
| Method | Request URI | HTTP version |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare?comp=lease&restype=share |
HTTP/1.1 |
PUT |
https://myaccount.file.core.windows.net/myshare?comp=lease&sharesnapshot=<DateTime>&restype=share |
HTTP/1.1 |
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: <action> |
acquire: Requests a new lease. If the file share doesn't have an active lease, Azure Files creates a lease on the file share and returns a new lease ID. If the file share has an active lease, you can only request a new lease by using the active lease ID. You can, however, specify a new x-ms-lease duration, including negative one (-1) for a lease that never expires.renew: Renews the lease. You can renew the lease if the lease ID specified on the request matches that associated with the file share. Note that you can renew the lease even if it has expired, as long as the file share hasn't been leased again since the expiration of that lease. When you renew a lease, the lease duration clock resets.change: Change 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: Release the lease. You can release the lease if the lease ID specified on the request matches that associated with the file share. Releasing the lease allows another client to immediately acquire the lease for the file share, as soon as the release is complete.break: Break the lease, if the file share has an active lease. After a lease is broken, it can't be renewed. Any authorized request can break the lease. The request isn't required to specify a matching lease ID. When a lease is broken, the lease break period is allowed to elapse, and break and release are the only operations you can perform on the file share during this time. When a lease is successfully broken, the response indicates the interval in seconds until a new lease can be acquired.A lease that has been broken can also be released. A client can immediately acquire a file share lease that has been released. |
x-ms-lease-break-period: N |
Optional. For a break operation, this is the proposed duration the lease should continue before it's broken, in seconds, between 0 and 60. This break period is only used if it's shorter than the time remaining on the lease. If longer, the time remaining on the lease is used. A new lease isn't available before the break period has expired, but the lease can be held for longer than the break period. If this header doesn't appear with a break operation, a fixed-duration lease breaks after the remaining lease period elapses, and an infinite lease breaks immediately. |
x-ms-lease-duration: -1 |
Required for acquire. Specifies the duration of the lease, in seconds, or negative one (-1) for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. A lease duration can't be changed by using renew or change. |
x-ms-proposed-lease-id: <ID> |
Optional for acquire, and required for change. Proposed lease ID, in a GUID string format. Azure Blob Storage 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. |
Origin |
Optional. Specifies the origin from which the request is issued. The presence of this header results in cross-origin resource sharing (CORS) headers on the response. See CORS support for the Storage services for details. |
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. |
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?restype=share&comp=lease HTTP/1.1
Request Headers:
x-ms-version: 2020-02-10
x-ms-lease-action: acquire
x-ms-lease-duration: -1
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-date: Thu, 26 Jan 2012 23:30:18 GMT
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).Renew: A successful operation returns status code 200 (OK).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 |
The ETag for the file share. |
Last-Modified |
Returns the date and time the file share was last modified. For more information, see Representation of date-time values in headers. Any operation that modifies the file share, or its properties or metadata, updates the last-modified time. This includes setting the file share's permissions. Operations on blobs don't affect the last-modified time of the file share. |
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 delete the file share, or to renew, change, or release the lease. A successful renew operation also returns the lease ID for the active lease. |
x-ms-lease-time: seconds |
Approximate time remaining in the lease period, in seconds. This header is returned only for a successful request to break the lease. If the break is immediate, 0 is returned. |
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 the FileREST API 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. |
Access-Control-Allow-Origin |
Returned if the request includes an Origin header, and CORS is enabled with a matching rule. This header returns the value of the origin request header in case of a match. |
Access-Control-Expose-Headers |
Returned if the request includes an Origin header, and CORS is enabled with a matching rule. Returns the list of response headers that are to be exposed to the client or issuer of the request. |
Access-Control-Allow-Credentials |
Returned if the request includes an Origin header, and CORS is enabled with a matching rule that doesn't allow all origins. This header is set to true. |
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: 2020-02-10
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5
Date: Thu, 26 Jan 2012 23:30:18 GMT
Authorization
Only the account owner can call this operation.
Remarks
A lease on a file share provides exclusive delete access to the file share. Get file share operations will succeed on a leased file share, without including the lease ID. Set file share operations will require the file share lease ID. If the lease ID isn't included on set file share operations, the operation fails with 412 (Precondition failed). The lease is granted for the duration specified when the lease is acquired, which can be from 15 to 60 seconds, or 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 renew the lease, change its lease ID, or release the lease. The following diagram shows the five states of a lease, and the commands or events that cause lease state changes.
A lease can be in any of these 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.
| Renewal status | Locked lease | Unlocked lease |
|---|---|---|
| Renewable lease | Leased | Expired |
| Non-renewable lease | Breaking | Broken, Available |
Available, the lease is unlocked and can be acquired. Allowed action:acquire.Leased, the lease is locked. Allowed actions:acquire(same lease ID only),renew,change,release, andbreak.Expired, the lease duration has expired. Allowed actions:acquire,renew,release, andbreak.Breaking, the lease has been broken, but the lease will continue to be locked until the break period has expired. Allowed actions:releaseandbreak.Broken, the lease has been broken, and the break period has expired. Allowed actions:acquire,release, andbreak.
Azure Files maintains the lease ID after a file share lease has expired. A client can renew or release the lease by using their expired lease ID. If the client attempts to renew or release an expired lease with their previous lease ID, and the request fails, that means that the file share was leased again or deleted since their lease was last active. If a lease expires rather than being explicitly released, a client might need to wait up to one minute before a new lease can be acquired for the file share. However, the client can renew the lease with the expired lease ID immediately.
The file share's Last-Modified-Time property isn't updated by calls to Lease Share.
The following tables show outcomes of actions on containers 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 shares by lease state
| Action | Available | Leased (A) | Breaking (A) | Broken (A) | Expired (A) |
|---|---|---|---|---|---|
| Delete with (A) | Fails (412) | Leased (A), delete succeeds | Breaking (A), delete succeeds | Fails (412) | Fails (412) |
| Delete with (B) | Fails (412) | Fails (409) | Fails (412) | Fails (412) | Fails (412) |
| Delete, no lease specified | Available, delete succeeds | Fails (412) | Fails (412) | Available, delete succeeds | Available, delete succeeds |
| Other operations with (A) | Fails (412) | Leased (A), operation succeeds | Breaking (A), operation succeeds | Fails (412) | Fails (412) |
| Other operations with (B) | Fails (412) | Fails (409) | Fails (409) | Fails (412) | Fails (412) |
| Operations, no lease specified | Available, operation succeeds | Leased (A), operation succeeds | Breaking (A), operation succeeds | Broken (A), operation succeeds | Expired (A), operation succeeds |
Outcomes of lease operations on shares by lease state
| Action | Available | Leased (A) | Breaking (A) | Broken (A) | Expired (A) |
|---|---|---|---|---|---|
Acquire, no proposed lease ID |
Leased (X) | Fails (409) | Fails (409) | Leased (X) | Leased (X) |
Acquire (A) |
Leased (A) | Leased (A), new duration | Fails (409) | Leased (A) | Leased (A) |
Acquire (B) |
Leased (B) | Fails (409) | Fails (409) | Leased (B) | Leased (B) |
Break, period=0 |
Fails (409) | Broken (A) | Broken (A) | Broken (A) | Broken (A) |
Break, period>0 |
Fails (409) | Breaking (A) | Breaking (A) | Broken (A) | Broken (A) |
Change, (A) to (B) |
Fails (409) | Leased (B) | Fails (409) | Fails (409) | Fails (409) |
Change, (B) to (A) |
Fails (409) | Leased (A) | Fails (409) | Fails (409) | Fails (409) |
Change, (B) to (C) |
Fails (409) | Fails (409) | Fails (409) | Fails (409) | Fails (409) |
Renew (A) |
Fails (409) | Leased (A), expiration clock reset | Fails (409) | Fails (409) | Leased (A) |
Renew (B) |
Fails (409) | Fails (409) | Fails (409) | Fails (409) | Fails (409) |
Release (A) |
Fails (409) | Available | Available | Available | Available |
Release (B) |
Fails (409) | Fails (409) | Fails (409) | Fails (409) | Fails (409) |
| Duration expires | Available | Expired (A) | Broken (A) | Broken (A) | Expired (A) |