Lease Blob

Article
04/04/2023

The Lease Blob operation creates and manages a lock on a blob for write and delete operations. The lock duration can be 15 to 60 seconds, or can be infinite. In versions prior to 2012-02-12, the lock duration is 60 seconds.

Important

Starting in version 2012-02-12, some behaviors of the Lease Blob operation differ from previous versions. For example, in previous versions, you could renew a lease after releasing it. Starting in version 2012-02-12, this lease request fails, but calls that use older versions of Lease Blob still succeed. For a list of changes to the behavior of this operation, see the "Remarks" section later in this article.

You can call the Lease Blob 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 blob.
Break, to end the lease, but ensure that another client can't acquire a new lease until the current lease period has expired.

Request

You can construct the Lease Blob request as follows. HTTPS is recommended. Replace myaccount with the name of your storage account.

PUT method request URI	HTTP version
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease`	HTTP/1.1

Emulated storage service URI

When you make a request against the emulated storage service, specify the emulator hostname and Azure Blob Storage port as 127.0.0.1:10000, followed by the emulated storage account name.

PUT method request URI	HTTP version
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=lease`	HTTP/1.0 HTTP/1.1

For more information, see Use Azurite emulator for local Azure Storage development.

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 Blob Storage 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 ¦ renew ¦ change ¦ release ¦ break>`	`acquire`: Requests a new lease. If the blob doesn't have an active lease, Blob Storage creates a lease on the blob, and returns a new lease ID. If the blob 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 blob. Note that the lease can be renewed even if it has expired, as long as the blob hasn't been modified or leased again since the expiration of that lease. When you renew a lease, the lease duration clock resets. `change`: Version 2012-02-12 and later. 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 blob. Releasing the lease allows another client to immediately acquire the lease for the blob, as soon as the release is complete. `break`: Breaks the lease, if the blob 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, during which time `break` and `release` are the only lease operations you can perform on the blob. 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, in which case another client can immediately acquire the lease on the blob.
`x-ms-lease-break-period: N`	Optional. Version 2012-02-12 and later. For a `break` operation, this is the proposed duration of seconds that the lease should continue before it is broken, between 0 and 60 seconds. 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 will not be 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 ¦ n seconds`	Version 2012-02-12 and later. Only allowed and required on an `acquire` operation. 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>`	Version 2012-02-12 and later. Optional for `acquire`, and required for `change`. Proposed lease ID, in a GUID string format. 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 Blob Storage.

This operation also supports the use of conditional headers to run the operation, only if a specified condition is met. For more information, see Specifying conditional headers for Blob Storage operations.

Request body

None.

Sample request

The following sample request shows how to acquire a lease:

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
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).
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`	Contains a value that you can use to perform operations conditionally. See Specifying conditional headers for Blob Storage operations for more information. This header is returned for requests made against version 2013-08-15 and later, and the `ETag` value is in quotes. The `Lease Blob` operation doesn't modify this property.
`Last-Modified`	The date/time that the blob was last modified. For more information, see Representation of date-time values in headers. Any write operation on the blob, including updates on the blob's metadata or properties, changes the last-modified time of the blob. The `Lease Blob` operation doesn't modify this property.
`x-ms-lease-id: <id>`	When you request a lease, Blob Storage returns a unique lease ID. While the lease is active, you must include the lease ID with any request to write to the blob, 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`	This header 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 Blob Storage used to run the request. This header is returned for requests made against version 2009-09-19 and later.
`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`	You can use this header 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-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2015-02-21  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: <date>

Authorization

Authorization is required when calling any data access operation in Azure Storage. You can authorize the Lease Blob operation as described below.

Azure Storage supports using Microsoft Entra ID to authorize requests to blob data. With Microsoft Entra ID, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. The security principal may be a user, group, application service principal, or Azure managed identity. The security principal is authenticated by Microsoft Entra ID to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.

To learn more about authorization using Microsoft Entra ID, see Authorize access to blobs using Microsoft Entra ID.

Permissions

Listed below are the RBAC action necessary for a Microsoft Entra user, group, or service principal to call the Lease Blob operation, and the least privileged built-in Azure RBAC role that includes this action:

Azure RBAC action: Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Least privileged built-in role: Storage Blob Data Contributor

To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.

A shared access signature (SAS) provides secure delegated access to resources in a storage account. With a SAS, you have granular control over how a client can access data. You can specify what resource the client may access, what permissions they have to those resources, and how long the SAS is valid.

The Lease Blob operation supports three types of shared access signatures: user delegation SAS, service SAS, and account SAS.

As a security best practice, we recommend that you use Microsoft Entra credentials rather than the storage account key, which can be more easily compromised. If your application design requires shared access signatures, use Microsoft Entra credentials to create a user delegation SAS, when possible.

When Shared Key access is disallowed for the storage account, a service SAS token or an account SAS token will not be permitted on a request to Blob Storage. To learn more, see Understand how disallowing Shared Key affects SAS tokens.

User delegation SAS

A user delegation SAS is secured with Microsoft Entra credentials and also by the permissions specified for the SAS.

Calling the Lease Blob operation using a SAS token delegated to a container or blob resource requires the Write (w) permission as part of the user delegation SAS token.

To learn more about the user delegation SAS, see Create a user delegation SAS.

Service SAS

A service SAS is secured with the storage account key. A service SAS delegates access to a resource in a single Azure Storage service, such as blob storage.

Calling the Lease Blob operation using a SAS token delegated to a container or blob resource requires the Write (w) permission as part of the service SAS token.

To learn more about the service SAS, see Create a service SAS.

Account SAS

An account SAS is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a service or user delegation SAS are also available via an account SAS.

The following table indicates the signed resource type and signed permissions to specify when delegating access:

Operation	Signed service	Signed resource type	Signed permission
Lease Blob	Blob (b)	Object (o)	Write (w)

To learn more about the account SAS, see Create an account SAS.

Remarks

A lease on a blob provides exclusive write and delete access to the blob. To write to a blob with an active lease, a client must include the active lease ID with the write request. The lease is granted for the duration specified when the lease is acquired. This duration can be between 15 and 60 seconds, or an infinite duration.

When a client acquires a lease, a lease ID is returned. Blob Storage 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.

When a lease is active, the lease ID must be included in the request for any of the following operations:

Put Blob
Set Blob Metadata
Set Blob Properties
Delete Blob
Put Block
Put Block List
Put Page
Append Block
Copy Blob (lease ID needed for destination blob)

If the lease ID isn't included, these operations fail on a leased blob, with 412 – Precondition failed.

The following operations succeed on a leased blob, without including the lease ID:

Get Blob
Get Blob Metadata
Get Blob Properties
Get Block List
Get Page Ranges
List Blobs
Copy Blob (No lease ID needed for source blob.)
Lease Blob (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 blob that has an active lease. However, all GET operations support a conditional lease parameter, where the operation only proceeds if the lease ID included with the request is valid.

All container operations are permitted on a container that includes blobs with an active lease, including Delete Container. Therefore, a container can be deleted even if blobs within it have active leases. Use the Lease Container operation to control rights to delete a container.

Lease states

The following diagram shows the five states of a lease, and the commands or events that cause lease state changes.

Diagram that shows blob lease states, and state change triggers.

A lease can be in one 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, and break.
Expired: The lease duration has expired. Allowed actions: acquire, renew, release, and break.
Breaking: The lease has been broken, but the lease will continue to be locked until the break period has expired. Allowed actions: release and break.
Broken: The lease has been broken, and the break period has expired. Allowed actions: acquire, release, and break.

After a lease has expired, the lease ID is maintained by Blob Storage until the blob is modified or leased again. A client can attempt to renew or release the lease by using their expired lease ID. If the operation is successful, this means that the blob hasn't been changed since the lease ID was last valid.

If the client attempts to renew or release a lease with their previous lease ID, and the request fails, then the blob was modified or leased again since the client's lease was last active. The client must then acquire a new lease on the blob.

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 blob. However, the client can renew the lease with their lease ID immediately, if the blob hasn't been modified.

Note that a lease can't be granted for a blob snapshot, because snapshots are read-only. Requesting a lease against a snapshot results in status code 400 (Bad Request).

The blob's Last-Modified-Time property isn't updated by calls to Lease Blob.

The following tables show outcomes of actions on blobs with leases in various lease states. Letters (A), (B), and (C) represent lease IDs, and (X) represents a lease ID generated by Blob Storage.

Outcomes of use attempts on blobs by lease state

Action	Available	Leased (A)	Breaking (A)	Broken (A)	Expired (A)
Write with (A)	Fails (412)	Leased (A), write succeeds	Breaking (A), write succeeds	Fails (412)	Fails (412)
Write with (B)	Fails (412)	Fails (409)	Fails (412)	Fails (412)	Fails (412)
Write, no lease specified	Available, write succeeds	Fails (412)	Fails (412)	Available, write succeeds	Available, write succeeds
Read with (A)	Fails (412)	Leased (A), read succeeds	Breaking (A), read succeeds	Fails (412)	Fails (412)
Read with (B)	Fails (412)	Fails (409)	Fails (409)	Fails (412)	Fails (412)
Read, no lease specified	Available, read succeeds	Leased (A), read succeeds	Breaking (A), read succeeds	Broken (A), read succeeds	Expired (A), read succeeds

Outcomes of lease operations on blobs 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), if blob hasn't been modified. Fails (409) if blob has been modified.
`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)

Changes to Lease Blob introduced in version 2012-02-12

The following list specifies changes to Lease Blob behavior introduced in version 2012-02-12.

A call to Lease Blob to acquire a lease now must include a lease duration header. If you try to acquire a lease without specifying a lease duration, the service returns 400 Bad Request – Missing required header.
You can no longer renew a lease after releasing it. If you try to do so, the service returns 409 Conflict – The lease ID specified did not match the lease ID for the blob. Applications that called release, and then called renew, must now save the ETag from the release call. Then applications must call acquire, with an If-Match conditional header, to acquire the lease only when the blob is unchanged.
You can no longer break a lease after releasing it. If you try to do so, the service returns 409 Conflict – There is currently no lease on the blob.
You can now break a breaking or broken lease, making break operations idempotent. In previous versions, this failed with 409 Conflict – The lease has already been broken and cannot be broken again. This change allows you to shorten the duration of a break. If you break a lease that is in the breaking state, and include a shorter duration than the remaining break period, your shorter duration is used.

Billing

Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for Lease Blob requests based on the storage account type:

Operation	Storage account type	Billing category
Lease Blob (acquire, release, renew)	Premium block blob Standard general-purpose v2	Other operations
Lease Blob (acquire, release, renew)	Standard general-purpose v1	Read operations
Lease Blob (break, change)	Premium block blob Standard general-purpose v2	Other operations
Lease Blob (break, change)	Standard general-purpose v1	Write operations