Versioning for the Azure Storage Services
Updated: October 13, 2015
The Microsoft Azure storage services support multiple versions. To make a request against the storage services, you must specify the version that you want to use for that operation, unless the request is anonymous.
The current version of the Azure storage services is 2015-04-05, and using that version is recommended where possible. For a list of all other supported versions, and for information about using each version, see Azure Storage Services Versions 2015-02-21 and Earlier.
Version 2015-04-05 includes these changes:
The Azure File service is now generally available. The File services now supports SMB 3.0 as well as SMB 2.1. All new and existing storage accounts include a File service endpoint.
For an overview of using the File service with Windows, see How to use Azure File storage with Windows. For an overview of using the File service with Linux, see How to use Azure File storage with Linux.
The Azure File service now supports Storage Analytics metrics. You can configure metrics for the File service from the Azure preview portal, from PowerShell, from the storage client library for .NET or for Java, or from the REST API. Use the Set File Service Properties operation to configure metrics for the File service. Use Get File Service Properties to retrieve metrics settings. For information about File service metrics, see Storage Analytics.
Account SAS is a new type of shared access signature at the level of the storage account. An account SAS enables you to:
Delegate access to service-level operations that are not currently available with a service-specific SAS, such as the Get/Set Service Properties and Get Service Stats operations.
Delegate access to more than one service in a storage account at a time. For example, you can delegate access to resources in both the Blob and File services with an account SAS.
Delegate access to write and delete operations for containers, queues, tables, and file shares, which are not available with an object-specific SAS.
Specify an IP address or range of IP addresses from which to accept requests.
Specify the HTTP protocol from which to accept requests (either HTTPS or HTTP/HTTPS).
For details about account SAS, see Constructing an Account SAS.
Currently account SAS is supported only for the Blob and File services. It will be supported for the Table and Queue services in the near future.
Both account SAS and service SAS include two new optional fields on the SAS token:
The signed IP (sip) field specifies an IP address or range of IP addresses from which to accept requests.
The signed protocol (spr) field specifies the HTTP protocol from which to accept requests (either HTTPS or HTTP/HTTPS).
When constructing the string-to-sign for an account SAS or a service SAS in version 2015-04-05, you must include the signed IP and signed protocol in the signature string. See Constructing an Account SAS and Constructing a Service SAS for more information.
How you specify the version of the storage services to use for a request relates to how that request is authenticated. The following sections describe authentication options and how the service version is specified for each:
Requests using Shared Key or Shared Key Lite. To authenticate a request with Shared Key/Shared Key Lite, you must pass the x-ms-version header on the request. In the case of the Blob service, you can specify the default version for all requests by calling Set Blob Service Properties.
Requests using a Shared Access Signature (SAS). You can specify two versioning options on a shared access signature. If specified, the optional api-version header indicates which service version to use to execute the API operation. The SignedVersion (sv) parameter specifies the service version to use to authorize and authenticate the request made with the SAS. If the api-version header is not specified, then the value of the SignedVersion (sv) parameter also indicates the version to use to execute the API operation.
Requests using anonymous access. In the case of anonymous access against the Blob service, no version is passed in; the heuristics for which version is used for the request are described below.
To authenticate a request with Shared Key/Shared Key Lite, specify the x-ms-version header on the request. The x-ms-version request header value must be specified in the format YYYY-MM-DD. For example:
Request Headers: x-ms-version: 2015-04-05
The following rules indicates how requests using Shared Key/Shared Key Lite are evaluated to determine the version to use in processing the request.
If a request has a valid x-ms-version header, the storage service uses the specified version. All requests to the Table and Queue services that do not use a shared access signature must specify an x-ms-version header. All requests to the Blob service that do not use a shared access signature must specify an x-ms-version header unless the default version has been set, as described below.
If a request to the Blob service does not have an x-ms-version header, but the account owner has set a default version using Set Blob Service Properties, then the specified default version is used as the version for the request.
A shared access signature (SAS) generated using version 2015-04-05 or later supports two versioning options:
The api-version query parameter defines the REST protocol version to use for processing a request made using the SAS.
The SignedVersion (sv) query parameter defines the SAS version to use for authentication and authorization.
The SignedVersion query parameter is used for authentication and authorization when a client makes a request using the SAS. Authentication and authorization parameters such as si, sr, sp, sig, st, se, tn, spk, srk, epk, and erk are all interpreted using version 2014-02-14.
REST protocol parameters such as rscc, rscd, rsce, rscl, and rsct are enforced using the version provided in the api-version parameter header. If the api-version header is not specified, then the service version provided for SignedVersion is used.
Note that the api-version parameter is not part of the string-to-sign in the authentication as described in Constructing a Service SAS.
The following table explains the versioning scheme used by the service for authentication and authorization and for calling the REST protocol when the SignedVersion parameter is set to version 2014-02-14 or later.
Value of api-version parameter
Version used for authentication and authorization
Version used for protocol behavior
Version specified in the sv parameter
Version specified in the sv parameter
Any valid storage services version in format XXXX-XX-XX
Version specified in the sv parameter
Valid storage services version XXXX-XX-XX
The following sample request calls List Blobs with sv=2015-04-05, and without the api-version parameter.
In this case, the service authenticates and authorizes the request using version 2015-04-05 and also executes the operation using version 2015-04-05.
The following sample request calls List Blobs with sv=2015-04-05 and with the api-version parameter.
Here, the service authenticates and authorizes the request using version 2015-04-05 and executes the operation using version 2012-02-12.
The .NET Storage Client Library will always set the REST protocol version (in the api-version parameter) to the version that it is based on.
If a request to the Blob service does not specify the x-ms-version header, and the default version for the service has not been set using Set Blob Service Properties, then the earliest version of the Blob service is used to process the request. However, if the container was made public with a Set Container ACL operation performed using version 2009-09-19 or newer, then the request is processed using version 2009-09-19.