你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 存储的版本控制

  • 项目

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

Azure 存储服务的当前版本为 2023-11-03，建议尽可能使用它。 有关所有其他受支持版本的列表，以及有关使用每个版本的信息，请参阅 以前的 Azure 存储服务版本。

2023-11-03 服务版本包含以下功能：

  • 无。

在请求中指定服务版本

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

  • 从 Microsoft Entra 使用 OAuth 2.0 令牌的请求：若要使用 Microsoft Entra ID 授权请求，请使用 2017-11-09 或更高版本的服务版本在请求上传递x-ms-version标头。 有关详细信息，请参阅使用 Microsoft Entra ID 授权中的使用 OAuth 令牌调用存储操作。

  • 使用共享密钥或共享密钥精简版的请求：若要使用共享密钥或共享密钥精简版授权请求，请在请求中传递 x-ms-version 标头。 在Azure Blob 存储的情况下，可以通过调用 Set Blob 服务属性为所有请求指定默认版本。

  • 使用共享访问签名的请求 (SAS) ：可以在共享访问签名上指定两个版本控制选项。 可选 api-version 标头指示用于执行 API 操作的服务版本。 required SignedVersion (sv) 参数指定用于授权使用 SAS 发出的请求的服务版本。 api-version如果未指定标头，则 参数的值SignedVersion (sv)还会指示用于执行 API 操作的版本。

  • 使用匿名访问的请求：在对 Blob 存储进行匿名访问的情况下，不会传入任何版本。 后续部分将介绍用于确定请求使用哪个版本的启发式方法。

使用Microsoft Entra ID、共享密钥或共享密钥 Lite 授权请求

若要使用 Microsoft Entra ID、共享密钥或共享密钥 Lite 授权请求，请在x-ms-version请求上指定标头。 必须以 YYYY-MM-DD 的格式来指定 x-ms-version 请求标头值。 例如：

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 参数定义 REST 协议版本，用于处理使用 SAS 发出的请求。

  • 查询 SignedVersion (sv) 参数定义用于授权的 SAS 版本。

当 SignedVersion 客户端使用 SAS 发出请求时，查询参数用于授权。 授权参数（如 si、sr、、sp、stsig、setnspk、、srk、epk、 和erk）都使用指定的版本进行解释。

REST 协议参数（如 rscc、rscd、rscerscl、 和 rsct ）通过使用参数标头中api-version提供的版本强制执行。 api-version如果未指定标头，则使用为其提供SignedVersion的服务版本。

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

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

api-version 参数的值 用于授权的版本 用于协议行为的版本
未指定 sv 参数中指定的版本 sv 参数中指定的版本
任何有效的存储服务版本，格式为 XXXX-XX-XX sv 参数中指定的版本 有效的存储服务版本 XXXX-XX-XX

示例 1

以下示例请求调用使用 和 不带 sv=2015-04-05api-version 参数的列表 Blob。

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

以下示例请求使用 sv=2015-04-05 和 api-version 参数调用 List 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 运行操作。

注意

.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。

已知问题

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

另请参阅