Lease Container

The Lease Container operation establishes and manages a lock on a container for delete operations. The lock duration can be 15 to 60 seconds, or can be infinite.

You can call the Lease Container 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 container.

• 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 Container operation is available in version 2012-02-12 and later.

Request

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

Method	Request URI	HTTP version
PUT	https://myaccount.blob.core.windows.net/mycontainer?comp=lease&restype=container	HTTP/1.1

To specify the root container, enter $root as the container name.

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.

Method	Request URI	HTTP version
PUT	http://127.0.0.1:10000/mycontainer?comp=lease&restype=container	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 container doesn't have an active lease, Blob Storage creates a lease on the container, and returns a new lease ID. If the container 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 container. Note that the lease can be renewed even if it has expired, as long as the container 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 container. Releasing the lease allows another client to immediately acquire the lease for the container, as soon as the release is complete. break: Break the lease, if the container 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. You can only perform break and release lease operations on the container 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 container lease that has been released.
x-ms-lease-break-period: N	Optional. For a break operation, this header is the proposed duration that the lease should continue before it's 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 won't 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	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. 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?restype=container&comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2012-02-12  
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 container. This header is returned for requests made against version 2013-08-15 and later, and the ETag value is in quotes. Lease Container operations made against version 2013-08-15 and later don't modify this property, but prior versions do.
Last-Modified	Returned for requests made against version 2013-08-15 and later. Returns the date and time the container was last modified. For more information, see Representation of date-time values in headers. Any operation that modifies the container, or its properties or metadata, updates the last-modified time. This includes setting the container's permissions. Operations on blobs don't affect the last-modified time of the container. Lease Container operations made against version 2013-08-15 and later don't modify this property, but prior versions do.
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 delete the container, 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 will be 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: 2012-02-12  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: Thu, 26 Jan 2012 23:30:18 GMT  
  

Authorization

Authorization is required when you're calling any data access operation in Azure Storage. You can authorize the Lease Container operation as described in the following sections.

Important

Microsoft recommends using Microsoft Entra ID with managed identities to authorize requests to Azure Storage. Microsoft Entra ID provides superior security and ease of use compared to Shared Key authorization.

Microsoft Entra ID (recommended)

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 can 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 Blob Storage.

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

Permissions

The following RBAC actions are necessary for a Microsoft Entra user, group, managed identity, or service principal to call the Lease Container operation, and the least privileged built-in Azure RBAC role that includes this action:

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

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

Shared access signatures

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 can access, what permissions they have to those resources, and how long the SAS is valid.

The Lease Container operation supports authorization using an account SAS.

When Shared Key access is disallowed for the storage account, 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.

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 you're delegating access:

Operation	Signed service	Signed resource type	Signed permission
Lease Container	Blob (b)	Container (c)	Write (w) or Delete (d)*

Note that the Delete permission allows breaking a lease on a blob or container with version 2017-07-29 and later.

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

Shared key

The Lease Container operation supports Shared Key authorization. We don't recommend authorizing with account keys for most scenarios, because it's less secure.

We recommend disallowing Shared Key authorization for the storage account when possible. For more information, see Prevent authorization with Shared Key.

Remarks

A lease on a container provides exclusive delete access to the container. A container lease only controls the ability to delete the container by using the Delete Container operation. To delete a container with an active lease, a client must include the active lease ID with the delete request. If the lease ID isn't included, the operation fails with 412 (Precondition failed). All other container operations succeed on a leased container, without including the lease ID. The lease is granted for the duration specified when the lease is acquired, which 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. The following diagram shows the possible states of a lease, and the commands or events that cause lease state changes.

A lease can be in one of five 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.

Blob Storage maintains the lease ID after a container 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, then the container was leased again or deleted since the client's 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 container. However, the client can renew the lease with the expired lease ID immediately.

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

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 Blob Storage.

Outcomes of use attempts on containers 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 containers 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)

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 Container requests based on the storage account type:

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

To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.

See also

Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes
Lease Blob