2 out of 3 rated this helpful - Rate this topic

Versioning for the Blob, Queue, and Table services in Windows Azure

Updated: June 12, 2012

Storage services accept requests that specify different versions of each operation. You can specify which version of an operation you want to use by setting the x-ms-version request header. Your code can call an older version of an operation, or you can modify your code to call a newer version. The documentation for each operation specifies behavior differences between different versions of the operation.

The x-ms-version request header value must be specified in the format YYYY-MM-DD. For example:

Request Headers:
x-ms-version: 2011-08-18

Versioning best practices

For requests that do not use a shared access signature, the Windows Azure storage services do not require the x-ms-version header to be specified on the request. However, we recommend that you include this header on every request, especially authenticated requests. In addition, we recommend that you set a default version for the Blob service using the Set Blob Service Properties (REST API) operation.

Client software that uses a shared access signature URL could experience unexpected behavior when the SAS URL specifies a storage service version that is newer than the client software. Code that prepares and distributes shared access signature URLs should specify versions that are understood by client software that makes storage service requests.

How versions are evaluated in requests that do not use a shared access signature

Anonymous requests to the Blob service and authenticated requests to all services may or may not have a version specified. The following list indicates how these requests are evaluated and how the request is processed.

If a request has a valid x-ms-version header, the storage service uses the specified version. All requests to Table and Queue services that do not use a shared access signature must specify an x-ms-version header.
If a request to the Blob service does not have an x-ms-version header, but the owner has set a default version using Set Blob Service Properties (REST API), then the owner-specified default version is used.
If a request to the Blob service does not have an x-ms-version header and no default version has been set using Set Blob Service Properties (REST API), the earliest version of the Blob service is used, except when the container was last set to public with a Set Container ACL (REST API) operation performed using version 2009-09-19 or newer. In that case, the request uses version 2009-09-19.

How versions are evaluated in requests that use a shared access signature

The Blob service introduced shared access signatures in version 2009-07-17. The Table and Queue services introduced shared access signatures in version 2012-02-12. Prior to version 2012-02-12, the Table and Queue services only authenticated requests using SharedKey and SharedKeyLite.

Versioning impacts handling of shared access signature requests in two ways.

A version is determined for interpreting the parameters and behavior of the shared access signature.
A version is determined for performing the storage operation. For example, in versions before 2011-08-18, the Get Blob (REST API) operation does not return the Accept-Ranges header.

In version 2012-02-12 and newer, shared access signatures require a signedversion parameter, and this parameter cannot appear in requests that use earlier versions. When a shared access signature includes a signedversion parameter, the version it specifies is used both to interpret the SAS parameters and perform the storage operation. When possible, we recommend using version 2012-02-12 or newer with a signedversion parameter. For more information about signedversion and other SAS parameters, see Create a Shared Access Signature.

Advanced versioning scenarios when a shared access signature uses older versions of the Blob service

Shared access signatures to Table and Queue services always include the signedversion parameter. This section describes how the Blob service uses the x-ms-version request header when a shared access signature does not include a signedversion parameter. When a request to the Blob service omits the signedversion parameter, the request must use a version older than 2012-02-12, and version 2009-07-17 is used to interpret SAS parameters for the request.

When a SAS request does not include a signedversion parameter, the Blob service uses the following rules to determine the version used to interpret SAS parameters and behavior, and also determine the version used to perform the storage operation:

If the Blob service SAS request has a valid x-ms-version header and does not have a signedversion field, version 2009-07-17 is used to interpret the SAS parameters, and the version specified by x-ms-version is used to perform the Blob service storage operation.
If the Blob service SAS request does not have an x-ms-version header and does not contain a signedversion parameter, and the owner has set the default version for this storage service type using Set Blob Service Properties (REST API), version 2009-07-17 is used to interpret the SAS parameters and the owner-specified default version is used to perform the Blob service storage operation.
If a Blob service SAS request does not have an x-ms-version header and does not have a signedversion parameter, and the owner has not set a default version, the Blob service uses version 2009-07-17 to interpret the SAS parameters. If the container is public and its access restrictions were set with a Set Container ACL (REST API) operation that used version 2009-09-19 or newer, version 2009-09-19 is used to perform the Blob service storage operation.
If a Blob service SAS request does not have an x-ms-version header and does not have a signedversion parameter, and the owner has not set a default version, the storage service uses version 2009-07-17 to interpret the SAS parameters. If the container access restrictions were not set with a Set Container ACL (REST API) operation that used version 2009-09-19 or newer, the storage operation is performed using the earliest version of the Blob service.

The following table applies the above rules to various scenarios.

Value of x-ms-version header	Value of signedversion parameter	Version used to interpret SAS parameters and behavior	Version used to perform storage operation
None	None	For Blob service resources, earliest SAS version (2009-07-17). Error for Table and Queue services.	For Blob service resources, 2009-09-19 is used if the container was set to public by Set Container ACL (REST API) using version 2009-09-19 or newer, else earliest version of Blob service is used. Error for Table and Queue services.
2011-08-18	None	For Blob service resources, earliest SAS version (2009-07-17). Error for Table and Queue services.	For Blob service resources, 2011-08-18. Error for Table and Queue services.
2012-02-12	None	For Blob service resources, earliest SAS version (2009-07-17). Error for Table and Queue services.	For Blob service resources, 2012-02-12. Error for Table and Queue services.
None	2012-02-12	2012-02-12	2012-02-12
2012-02-12	2012-02-12	2012-02-12	2012-02-12
2011-08-18	2012-02-12	2012-02-12	2012-02-12
Future version	2012-02-12	2012-02-12	2012-02-12
Future version A	Future version B	Future version B	Future version B

Supported versions

The following table shows which versions of the storage services are currently available:

Version	Description
2012-02-12	The 2012-02-12 version is the latest version of the Windows Azure storage services. This version includes these changes: Copy Blob (REST API) now works asynchronously, and can copy from any Windows Azure storage account. Now containers can be leased, and all leases support shorter or infinite durations. Now you must provide a lease duration. A released lease cannot be broken or renewed. Previously these operations were allowed. If you break a lease that is breaking or already broken, no error will occur. The lease ID of an active lease can be changed. A lease ID can be included on an operation to acquire a lease. When breaking a lease, you can specify a period during which the lease should remain active. Table and Queue services now support shared access signatures. A shared access signature can live longer than an hour, even with no stored access policy. The Blob service now provides MD5 hashes for the Put Blob (REST API) operation.
2011-08-18	The 2011-08-18 version includes these changes: Get Blob (REST API) returns an Accept-Ranges:bytes header in the response to indicate that the service supports range requests. Get Blob (REST API) supports a new Range header format that reads from the specified offset to the end of the blob. For more information, see Specifying the Range Header for Blob Service Operations. ETags returned by the Blob service are enclosed in quotes. In addition, the Blob service will accept quoted and unquoted ETags. Set Blob Service Properties (REST API) can specify a default version to use when an un-versioned request is received. If-Match GET and PUT operations against the Blob service will now return HTTP 404 (“Not Found) and HTTP 412 (“Precondition Failed”) if the blob doesn’t exist. This change applies to 2009-09-19 and newer versions. The Table service supports projections of selected properties by using the $select query option. For more information, see Query Entities (REST API) and Writing LINQ Queries. The Table service adds the Insert Or Replace Entity (REST API) and Insert Or Merge Entity (REST API) operations, which “upsert” an entity. The Queue service adds the Update Message operation, which can extend the invisibility time of a message or update the contents of the message. The Put Message operation adds the optional visibilitytimeout parameter which can extend the invisibility time of a new message. The visibilitytimeout parameter can now be set to a maximum of 7 days, up from the previous maximum of 2 hours. Queue messages can now be 64KB in size, up from the previous maximum size of 8KB.
2009-09-19	The 2009-09-19 version includes these changes: Enhancements to Shared Key authentication. See Authentication for the Windows Azure Storage Services for more information. The introduction of a new type of blob, the page blob, which is optimized for random read/write operations and provides the ability to write to a range of bytes in a blob. See Understanding Block Blobs and Page Blobs for more information. New naming rules for container, blob, and queue metadata. See Naming and Referencing Containers, Blobs, and Metadata and Naming Queues and Metadata for more information. Blob snapshots, which are read-only versions of a blob as it existed at the time the snapshot was taken. See HTTP Operations on Blob Service Resources (REST API) and Snapshot Blob (REST API) for more information. Blob leases, which ensure a one-minute exclusive write lock on a blob. See Lease Blob (REST API) for more information. Enhanced control over publicly accessible container and blob resources. See Restrict Access to Containers and Blobs for more information. Anonymous access to the root container. See Working with the Root Container (REST API) for more information. The x-ms-version response header, returned by all API operations. This header indicates which version of the API was used to make the request. Additional options for enumerating containers, blobs, and queues. These options permit you to return metadata in the enumeration, and in the case of blobs, to return snapshots and uncommitted blobs in the list. See List Containers (REST API), List Blobs (REST API), and List Queues for more information. Additional blob properties, which save values specified for standard HTTP headers. See Set Blob Properties (REST API) for more information. A DequeueCount property for messages, which indicates how many times a message has been dequeued. See Get Messages and Peek Messages for more information. A requirement that REST calls to the Table service include the DataServiceVersion and MaxDataServiceVersion headers on every request. See Setting Required WCF Headers for more information. New values are returned in the Server response header to identify the service that handled the request. These values are: Windows-Azure-Blob/1.0 Windows-Azure-Queue/1.0 Windows-Azure-Table/1.0
2009-07-17	The 2009-07-17 version includes these changes: A root or default container that permits blobs to reside at the top level of the storage account hierarchy. See Working with the Root Container (REST API) for more information. Enhancements to the Put Block List (REST API) operation for updating blobs. Granular control over user access to containers and blobs, via shared access signatures and container-level access policies. See Manage Access to Containers, Blobs, Tables, and Queues for more information. Thirty-second server timeouts for the List Containers (REST API), List Blobs (REST API), List Queues, Query Tables (REST API), and Query Entities (REST API) operations. A request against the Blob service may specify only a single conditional header. 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. See Specifying Conditional Headers for Blob Service Operations for more information.
2009-04-14	The 2009-04-14 version includes these changes: The Copy Blob (REST API) operation was introduced with the 2009-04-14 version. To call Copy Blob, you must specify the x-ms-version header. The Get Block List (REST API) operation offers new functionality with the 2009-04-14 version. You can now specify whether you wish to return the list of committed blocks, the list of uncommitted blocks, or both lists together. To use this new functionality, you must set the x-ms-version request header to 2009-04-14. Entity group transactions permit atomic batch operations for multiple insert, update, and delete operations against the 2009-04-14 version of the Table service. For more information, see Performing Entity Group Transactions. The Table service no longer supports property names, including the dash (-) character in the 2009-04-14 version. Beginning with the 2009-04-14 version, the Table service now supports naming properties with C# Unicode characters. For more information about naming properties, see Understanding the Table Service Data Model.