Specifying Conditional Headers for Blob Service Operations
Several Blob service operations support the use of conditional headers. You can specify conditional headers to carry out an operation only if a specified condition has been met.
The Blob service follows the HTTP/1.1 protocol specification for conditional headers.
This topic contains the following subtopics:
Operations Supporting Conditional Headers
HTTP Response Codes for Operations Supporting Conditional Headers
The supported conditional headers are described in the following table.
| Conditional header | Description |
|---|---|
|
If-Modified-Since |
A DateTime value. Specify this header to perform the operation only if the resource has been modified since the specified time. |
|
If-Unmodified-Since |
A DateTime value. Specify this header to perform the operation only if the resource has not been modified since the specified date/time. |
|
If-Match |
An ETag value. Specify this header to perform the operation only if the resource's ETag matches the value specified. For versions 2011-08-18 and newer, the ETag can be specified in quotes. |
|
If-None-Match |
An ETag value, or the wildcard character (*). Specify this header to perform the operation only if the resource's ETag does not match the value specified. For versions 2011-08-18 and newer, the ETag can be specified in quotes. Specify the wildcard character (*) to perform the operation only if the resource does not exist, and fail the operation if it does exist. |
When specifying conditional headers, keep in mind the following:
-
If a request specifies both the If-None-Match and If-Modified-Since headers, the request is evaluated based on the criteria specified in If-None-Match.
-
If a request specifies both the If-Match and If-Unmodified-Since headers, the request is evaluated based on the criteria specified in If-Match.
-
With the exception of the two combinations of conditional headers listed above, a request may specify only a single conditional header. Specifying more than one conditional header results in status code 400 (Bad Request).
-
If a response includes an ETag, verify the version of the request and response before processing the ETag. For example, version 2011-08-18 and newer return a quoted ETag, but older versions do not. Ensure that your application can process both ETag formats before they are evaluated.
The operations that support conditional headers are described in the following table. Methods in the Windows Azure .NET Libraries usually use the AccessCondition property to specify the conditions that must be met for the operation to be performed on the storage service.
| .NET Method | REST Operation | Operation type | Supported conditional headers |
|---|---|---|---|
|
UploadFromStream, UploadFile, UploadText, UploadByteArray, and others |
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
|
|
DownloadToStream and others |
Read |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
|
|
Read |
If-Modified-Since If-Unmodified-Since |
||
|
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
Read |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
Read |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
Read and Write |
For conditions on the destination blob:
For conditions on the source blob:
|
||
|
Read |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
PutPage with AddConditional |
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
|
|
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
||
|
Lease with AddConditional |
Write |
If-Modified-Since If-Unmodified-Since If-Match If-None-Match |
|
|
Write |
If-Modified-Since |
||
|
Write |
If-Modified-Since If-Unmodified-Since |
If the request includes a conditional header and the specified condition is not met by the resource being requested, the Blob service returns an HTTP response code. The response codes returned are in accordance with the HTTP/1.1 protocol specification (RFC 2616). Methods in the Windows Azure .NET Libraries convert these error response codes into a StorageClientException, and populate the StatusCode property with a value from the System.Net.HttpStatusCode enumeration. To see sample code that handles an exception caused by a conditional operation, see How to Conditionally Refresh a Local Copy of a Blob.
The following table indicates the response codes returned for an unmet condition for each conditional header when the operation is a read operation. Read operations use the verbs GET or HEAD.
| Conditional header | Response code if condition has not been met |
|---|---|
|
If-Modified-Since |
Not Modified (304) |
|
If-Unmodified-Since |
Precondition Failed (412) |
|
If-Match |
Precondition Failed (412) |
|
If-None-Match |
Not Modified (304) |
The following table indicates the response codes returned for an unmet condition for each conditional header when the operation is a write operation. Write operations use the verbs PUT or DELETE.
| Conditional header | Response code if condition has not been met |
|---|---|
|
If-Modified-Since |
Precondition Failed (412) |
|
If-Unmodified-Since |
Precondition Failed (412) |
|
If-Match |
Precondition Failed (412) |
|
If-None-Match |
Precondition Failed (412) |
The following table indicates the response codes returned for an unmet condition for each conditional header when the operation is a copy operation. The Copy Blob (REST API) operation uses the verbs PUT.
| Conditional header | Response code if condition has not been met |
|---|---|
|
If-Modified-Since |
Precondition Failed (412) |
|
If-Unmodified-Since |
Precondition Failed (412) |
|
If-Match |
Precondition Failed (412) |
|
If-None-Match |
Precondition Failed (412) |
|
x-ms-source-if-modified-since |
Precondition Failed (412) |
|
x-ms-source-if-unmodified-since |
Precondition Failed (412) |
|
x-ms-source-if-match |
Precondition Failed (412) |
|
x-ms-source-if-none-match |
Precondition Failed (412) |
See Also
A bit more details: http://abdullin.com/journal/2010/8/9/windows-azure-storage-can-be-confusing.html
- 8/10/2010
- Rinat Abdullin