Azure 存储的版本控制

Azure 存储支持多个版本。 若要针对存储服务发出请求，必须指定要用于该操作的版本，除非请求是匿名的。

截至 2025 年 4 月 30 日，Azure 存储服务的最新完全部署版本为 2025-05-05。 2025-07-05 也得到了广泛部署，如下表所示。 所有三个版本均为 GA 质量。

请注意，如果表指示在某个区域中启用了 ， x-ms-version 则所有先前 x-ms-versions 的 ID 也会启用。 如果尝试使用未在存储帐户所在区域中完全部署的服务版本，则可能会遇到 x-ms-version 不匹配错误。

Azure 存储数据平面 SDK 使用的默认值 x-ms-version 可在下表的更改日志中找到：

Azure 存储服务的最新版本是 2025-07-05，建议尽可能使用它。 有关所有其他受支持版本的列表以及有关使用每个版本的信息，请参阅 以前的 Azure 存储服务版本。

2025-07-05 服务版本包括以下功能：

• 新增对请求头的支持 x-ms-file-request-intent ： 从 URL 放置 Blob、 从 URL 复制 Blob、 从 URL 放置块、 从 URL 放置页面和 从 URL 附加块。
• 添加了对 Create Symbolic Link 和 Read Symbolic Link API 的支持。 请注意，这些 API 仅适用于高级文件存储帐户中的 NFS 共享。

在请求中指定服务版本

如何指定要用于请求的存储服务版本与请求的授权方式相关。 以下各节介绍了授权选项以及如何为每个选项指定服务版本。

• 使用来自 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 存储，可以通过调用 设置 Blob 服务属性为所有请求指定默认版本。

• 使用共享访问签名（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 格式指定。 例如：

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、rscd、rsce、rscl和 rsct）使用 api-version 参数标头中提供的版本强制执行。 如果未指定 api-version 标头，则使用为 SignedVersion 提供的服务版本。

api-version 参数不是授权标头字符串登录的一部分，如 创建服务 SAS中所述。

下表说明了服务用于授权的版本控制方案，并将 SignedVersion 参数设置为版本 2014-02-14 或更高版本时调用 REST 协议。

示例 1

以下示例请求使用 调用 sv=2015-04-05，而不调用 api-version 参数。

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 运行该操作。

示例 2

以下示例请求调用 api-version 列出 Blob。

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 运行该操作。

通过匿名访问的请求

通过匿名访问发出的请求的处理方式不同，具体取决于它们针对的存储帐户的类型。

用于常规用途存储帐户

如果对常规用途存储帐户的匿名请求未指定 x-ms-version 标头，并且尚未使用 设置 Blob 服务属性来设置该服务的默认版本，该服务将使用最早的版本来处理请求。 但是，如果使用版本 2009-09-19 或更高版本执行的 设置容器 ACL作公开容器，则使用版本 2009-09-19 处理请求。

对于 Blob 存储帐户

如果对 Blob 存储帐户的匿名请求未指定 x-ms-version 标头，并且尚未使用 设置 Blob 服务属性来设置该服务的默认版本，该服务将使用最早的版本来处理请求。 对于 Blob 存储帐户，最早的版本为 2014-02-14。

已知问题

本部分详细介绍了 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 版本来查看问题是否得到解决。 如果问题仍然存在，或者建议不可行，请 开具支持票证 讨论其他选项。

另请参阅

• 存储服务 REST
• 版本控制最佳做法
• .NET 客户端库版本的协议版本支持