你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure 存储的版本控制
Azure 存储支持多个版本。 若要针对存储服务发出请求，必须指定要用于该操作的版本，除非请求是匿名的。
Azure 存储服务的当前版本为 2024-11-04，建议尽可能使用它。 有关所有其他受支持版本的列表以及有关使用每个版本的信息，请参阅 以前的 Azure 存储服务版本。
2024-11-04 服务版本包含以下功能：
- 支持对文件服务中的所有数据平面 API 进行基于令牌的身份验证。 有关详细信息，请参阅 使用 Microsoft Entra ID授权。
- 支持高级文件共享帐户的付费突发。 可以使用 创建共享 和 设置共享属性 API 来启用此功能。
- 在文件服务中获取和设置文件权限时支持二进制格式。 有关详细信息，请参阅 创建权限 和 获取权限
在请求中指定服务版本
如何指定要用于请求的存储服务版本与请求的授权方式相关。 以下各节介绍了授权选项以及如何为每个选项指定服务版本。
使用来自 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 协议。
| api 版本 参数的值 | 用于授权的版本 | 用于协议行为的版本 |
|---|---|---|
| 未指定 |
sv 参数中指定的版本 |
sv 参数中指定的版本 |
格式为 XXXX-XX-XX 的任何有效存储服务版本 |
sv 参数中指定的版本 |
有效的存储服务版本 XXXX-XX-XX |
示例 1
以下示例请求使用 sv=2015-04-05调用 列出 blob，而不调用 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
以下示例请求调用 使用 sv=2015-04-05 和 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 运行该操作。
注意
.NET 存储客户端库始终将 REST 协议版本（在 api-version 参数中）设置为它所基于的版本。
通过匿名访问的请求
通过匿名访问发出的请求的处理方式不同，具体取决于它们针对的存储帐户的类型。
用于常规用途存储帐户
如果对常规用途存储帐户的匿名请求未指定 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 版本来查看问题是否得到解决。 如果问题仍然存在，或者建议不可行，请 开具支持票证 讨论其他选项。