你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure 存储支持多个版本。 若要针对存储服务发出请求，必须指定要用于该操作的版本，除非请求是匿名的。
截至 2025 年 7 月 14 日，Azure 存储服务的最新完全部署版本为 2025-05-05。
2025-07-05 也得到了广泛部署，如下表所示。 所有版本均为 GA 质量。
如果表指示在某个区域中启用了 ， x-ms-version 则所有先前 x-ms-versions 的 也会启用。 尝试使用未在存储帐户区域中完全部署的服务版本可能会生成 x-ms-version 不匹配错误。
x-ms-version |
Region Availability | SDK Support |
|---|---|---|
2025-07-05 |
asiaeast asiasoutheast australiac australiac2 australiaeast australiasoutheast austriae belgiumc brazilse brazilsouth canadacentral canadaeast chilec denmarke europenorth europewest francec frances germanyn germanywc indiacentral indiasouth indiawest indonesiac israelc israelnw italyn japaneast japanwest jioinc jioinw koreacentral koreasouth malaysias malaysiaw mexicoc newzealandn norwaye norwayw polandc qatarc southafrican southafricaw spainc swedenc swedens switzerlandn switzerlandw taiwann taiwannw uaec uaen uksouth ukwest uscentral uscentraleuap useast useast2 useast2euap useast3 usnorth ussouth ussouth2 ussoutheast ussoutheast3 ussoutheast5 ussouthwest uswest uswest2 uswest3 uswestcentral |
GA |
2025-11-05 |
asiaeast australiac australiac2 australiaeast australiasoutheast austriae belgiumc brazilse brazilsouth canadacentral canadaeast chilec denmarke europenorth francec frances germanywc indiacentral indiasouth indiawest indonesiac israelc israelnw italyn japaneast japanwest jioinc jioinw koreacentral koreasouth malaysias malaysiaw mexicoc newzealandn norwaye norwayw polandc qatarc southafrican southafricaw spainc swedenc swedens switzerlandn switzerlandw taiwann taiwannw uaec uaen ukwest useast3 usnorth ussouth2 ussoutheast ussoutheast3 ussoutheast5 ussouthwest uswest uswest2 uswest3 uswestcentral |
Beta |
可以在下表的更改日志中找到 Azure 存储数据平面 SDK 使用的默认值 x-ms-version ：
数据层面存储 SDK 不会对其他官方软件包源执行 GA 版本，直到相关版本的默认值 x-ms-version 在所有区域完全推出。 因此，官方包管理器提供的最新 GA SDK 版本可以在任何区域安全使用。
Azure 存储服务的最新版本是 2025-11-05，建议尽可能使用它。 有关所有其他受支持版本的列表以及有关使用每个版本的信息，请参阅 以前的 Azure 存储服务版本。
2025-11-05 服务版本包含如下功能：
- 以下 API 现在返回
x-ms-copy-source-status-code和x-ms-copy-source-error-code. 有关更多信息，请参阅 状态和错误代码。
在请求中指定服务版本
如何指定要用于请求的存储服务版本与请求的授权方式相关。 以下各节介绍了授权选项以及如何为每个选项指定服务版本。
使用来自 Microsoft Entra的 OAuth 2.0 令牌的请求：若要使用 Microsoft Entra ID 授权请求，请使用服务版本 2017-11-09 或更高版本在请求上传递
x-ms-version标头。 有关详细信息，请参阅 使用 OAuth 令牌 调用存储作，使用 Microsoft Entra ID授权。使用共享密钥或共享密钥 Lite 的请求：若要使用共享密钥或共享密钥 Lite 授权请求，请在请求中传递
x-ms-version标头。 使用 Azure Blob 存储时，可以通过调用 Set Blob Service Properties 来指定所有请求的默认版本。使用共享访问签名（SAS）的请求：可以在共享访问签名上指定两个版本控制选项。 可选的
api-version标头指示用于执行 API作的服务版本。 必需的SignedVersion (sv)参数指定用于授权使用 SAS 发出的请求的服务版本。 如果未指定api-version标头，则SignedVersion (sv)参数的值也指示用于执行 API作的版本。使用匿名访问的请求：对 Blob 存储使用匿名访问时，不会传入任何版本。 下一节介绍了确定要用于请求的版本的启发式。
使用 Microsoft Entra ID、共享密钥或共享密钥 Lite 授权请求
若要使用 Microsoft Entra ID、共享密钥或共享密钥 Lite 授权请求，请在请求上指定 x-ms-version 标头。
x-ms-version 请求标头值必须采用 YYYY-MM-DD 格式指定。 For example:
Request Headers:
x-ms-version: 2020-04-08
以下规则描述如何评估这些请求，以确定用于处理请求的版本。
如果请求具有有效的
x-ms-version标头，则存储服务使用指定的版本。 对不使用共享访问签名的 Azure 表存储和 Azure 队列存储的所有请求都必须指定x-ms-version标头。 所有不使用共享访问签名的 Blob 存储请求都必须指定标头，x-ms-version除非设置了默认版本，如下一段所述。如果对 Blob 存储的请求不包含
x-ms-version标头，但帐户所有者使用 “设置 Blob 服务属性 ”作设置了默认版本，则指定的默认版本将用作请求的版本。
使用共享访问签名授权请求
使用版本 2014-02-14 或更高版本生成的共享访问签名（SAS）支持两种版本控制选项：
api-version查询参数定义用于处理使用 SAS 发出的请求的 REST 协议版本。SignedVersion (sv)查询参数定义用于授权的 SAS 版本。
当客户端使用 SAS 发出请求时，SignedVersion 查询参数用于授权。 授权参数（如 si、sr、sp、sig、st、se、tn、spk、srk、epk和 erk）均使用指定版本进行解释。
REST 协议参数（如 rscc、 、 rscdrscerscl、 和 rsct ）通过使用参数标头中提供的api-version版本来实施。 如果未指定标头， api-version 则使用 for SignedVersion 提供的服务版本。
api-version 参数不是授权标头字符串登录的一部分，如 创建服务 SAS中所述。
下表说明了服务用于授权的版本控制方案，并将 SignedVersion 参数设置为版本 2014-02-14 或更高版本时调用 REST 协议。
| Value of api-version parameter | 用于授权的版本 | 用于协议行为的版本 |
|---|---|---|
| Not specified |
sv 参数中指定的版本 |
sv 参数中指定的版本 |
格式为 XXXX-XX-XX 的任何有效存储服务版本 |
sv 参数中指定的版本 |
有效的存储服务版本 XXXX-XX-XX |
Example 1
The following sample request calls List Blobs with sv=2015-04-05, and without the api-version parameter.
https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d
在这种情况下，服务使用版本 2015-04-05 对请求进行身份验证和授权，并使用版本 2015-04-05 运行该操作。
Example 2
The following sample request calls List Blobs with sv=2015-04-05 and with the api-version parameter.
https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d&api-version=2012-02-12
在这里，服务使用版本 2015-04-05 授权请求，并使用版本 2012-02-12 运行该操作。
Note
.NET 存储客户端库始终将 REST 协议版本（在参数中 api-version ）设置为基本版本。
通过匿名访问的请求
通过匿名访问发出的请求的处理方式不同，具体取决于它们针对的存储帐户的类型。
常规用途存储帐户
如果对常规用途存储帐户的匿名请求未指定 x-ms-version 标头，并且未使用 设置 Blob 服务属性设置服务的默认版本，则服务将使用尽可能早的版本来处理请求。 如果容器是使用版本 2009-09-19 或更高版本的 Set Container ACL 作公开的，则使用版本 2009-09-19 处理请求。
对于 Blob 存储帐户
如果对 Blob 存储帐户的匿名请求未指定 x-ms-version 标头，并且未使用 “设置 Blob 服务属性”设置服务的默认版本，则服务将使用尽可能早的版本来处理请求。 对于 Blob 存储帐户，最早的版本为 2014-02-14。
Known issues
本部分详细介绍了 Azure 存储 REST API 的已知问题。
InvalidHeaderValue 错误消息
在极少数情况下，进行直接 REST API 调用的应用程序可能会收到 InvalidHeaderValue 错误消息。 此错误类似于以下示例：
HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>
建议使用早期的 REST API 版本尝试解决此问题。 如果问题仍然存在，或者建议不可行，请 打开支持票证 以讨论更多选项。