Home Library Learn Downloads Support Community
Sign in | United States - English | |
1 out of 2 rated this helpful Rate this topic

Lease Blob (REST API)

The Lease Blob operation establishes and manages a one-minute lock on a blob for write operations.

The Lease Blob operation can be called in one of four modes:

  • Acquire, to request a new lease.

  • Renew, to renew an existing lease.

  • Release, to free the lease if it is no longer needed so that another client may immediately acquire a lease against the blob.

  • Break, to end the lease but ensure that another client cannot acquire a new lease until the current lease period has expired.

The Lease Blob request may be constructed as follows. Replace myaccount with the name of your storage account:

 

Method Request URI HTTP Version

PUT

http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease

HTTP/1.1

When making a request against the local storage service, specify the local hostname and Blob service port as 127.0.0.1:10000, followed by the local storage account name:

 

Method Request URI HTTP Version

PUT

http://127.0.0.1:10000/mycontainer/myblob?comp=lease

HTTP/1.0

HTTP/1.1

For more information, see Overview of Running a Windows Azure Application with Local Storage and Differences Between the Storage Emulator and Windows Azure Storage Services.

The following table describes required and optional request headers.

 

Request Header Description

Authorization

Required. Specifies the authentication scheme, account name, and signature. For more information, see Authentication Schemes.

Date or x-ms-date

Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authentication Schemes.

x-ms-version

Optional. Specifies the version of the operation to use for this request. For more information, see Storage Services Versioning.

x-ms-lease-id: <ID>

Required to renew the lease or to release the lease.

The value of x-ms-lease-id can be specified in any valid GUID string format. See Guid Constructor (String) for a list of valid GUID string formats.

x-ms-lease-action: <acquire | renew | release | break>

Acquire: Requests a new lease. If the blob does not have an active lease, the Blob service creates a lease on the blob and returns a new lease ID. You may request a new lease only for a blob without an active lease.

Renew: Renews the lease. The lease can be renewed if the lease ID specified on the request matches that associated with the blob. Note that the lease may be renewed even if it has expired or been released as long as the blob has not been modified since the expiration or release of that lease.

Release: Release the lease. The lease may be released 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: Break the lease, if the blob has an active lease. Once a lease is broken, it cannot be renewed. Any authorized request can break the lease; the request is not required to specify a matching lease ID. When a lease is broken, the remaining time on the lease is allowed to elapse, during which time no lease operation may be performed on the blob. When a lease is successfully broken, the response indicates the interval in seconds until a new lease may be acquired.

A lease that has been broken but has not yet expired can also be released, in which case another client may immediately acquire the lease on the blob.

The following sample request shows how to acquire a lease:

Copy 

Request Syntax:
PUT http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease HTTP/1.1

Request Headers:
x-ms-lease-action: acquire
x-ms-date: Sun, 25 Sep 2011 13:37:35 GMT
x-ms-version: 2011-08-18
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=

The response includes an HTTP status code and a set of response headers.

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

  • 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.

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.

 

Syntax Description

x-ms-lease-id: <id>

When you request a lease, the Blob service 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 or release the lease.

A successful renew operation also returns the lease ID for the active lease.

x-ms-lease-time: seconds

Time remaining in the lease period, in seconds. This header is returned only for a successful request to break the lease. It provides an approximation as to when the lease period will expire.

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 the Blob service used to execute the request. This header is returned for requests made against version 2009-09-19 and later.

Date

A UTC date/time value generated by the service that indicates the time at which the response was initiated.

The following is a sample response for a request to acquire a lease:

Copy 
Response Status:
HTTP/1.1 201 Created

Response Headers:
x-ms-lease-id: 75e6aea1-25f8-4178-869f-21addc220660
Date: Sun, 25 Sep 2011 22:33:35 GMT
Last-Modified: Sun, 25 Sep 2011 21:44:25 GMT
x-ms-version: 2011-08-18
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Only the account owner may call this operation.

A lease on a blob provides exclusive write 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 a period of one minute.

When a client acquires a lease, a lease ID is returned. The client may use this lease ID to renew the lease or to release the lease.

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

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, so that the operation proceeds only if a valid lease ID is included with the request.

All container operations are permitted on a container that includes blobs with an active lease, including Delete Container (REST API). Therefore a container may be deleted even if blobs within it have active leases.

Once a lease has expired or been released, the lease ID is maintained by the Blob service, unless the blob is modified. A client may attempt to renew or release their lease using their previous lease ID and know that if the operation is successful, the blob has not been updated 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, the client then knows that the blob was modified since their 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 may 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 if the blob has not been modified.

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

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

The following error scenarios can occur with a Lease Blob operation. Each returns status code 409 (Conflict):

  • Acquiring a lease on a blob that already has an active lease.

  • Breaking a lease that has already been broken.

  • Renewing a lease that has been broken but has not yet expired.

  • Renewing, releasing, or breaking a lease on a blob that has no associated lease ID (and thus no active lease).

  • Renewing or releasing a lease on a blob when the specified lease ID does not match the blob’s lease ID.

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ