Управление версиями для службы хранилища Azure

Служба хранилища Azure поддерживает несколько версий. Чтобы запросить службы хранилища, необходимо указать версию, которую вы хотите использовать для этой операции, если запрос не является анонимным.

По состоянию на 8 января 2026 года последняя полностью развернутая версия сервиса Azure Storage — 2026-02-06, которая поддерживается последними пакетами Azure Storage SDK GA. 2026-04-06 также широко распространён и поддерживается последними бета-версиями Storage SDK.

Если в таблице указано, что an x-ms-version включен в регионе, все предыдущие x-ms-versions также включены. Попытка использовать версию службы, которая не полностью развернута в регионе учетной записи хранения, может привести к ошибке несоответствия x-ms-версии.

Значение по умолчанию x-ms-version , используемое пакетами SDK для плоскости данных службы хранилища Azure, можно найти в журналах изменений в следующей таблице:

Пакеты SDK для хранилища плоскости данных не выполняют общедоступные выпуски для других официальных каналов пакетов до тех пор, пока по умолчанию x-ms-version для рассматриваемого выпуска не будет полностью развернуто во всех регионах. Таким образом, последний релиз GA SDK от официальных пакетных менеджеров можно смело использовать в любом регионе.

Последняя версия сервисов хранения Azure — 2026-02-06, и мы рекомендуем использовать её, где это возможно. Список всех других поддерживаемых версий, а также сведения об использовании каждой версии см. в статье Предыдущие версии службы хранилища Azure.

Сервисная версия 2026-04-06 включает следующие функции:

• Поддержка динамической делегации пользователей SAS. Для получения дополнительной информации см. раздел Create User Delegation SAS.
• Поддержка Files Provisioned V2 Guardrails. Для получения дополнительной информации см. Коды ошибок сервиса файлов.

Указание версий служб в запросах

Как указать версию служб хранилища, используемых для запроса, относится к тому, как этот запрос авторизован. В следующих разделах описаны параметры авторизации и указание версии службы для каждого из них.

• Запросы, использующие маркер OAuth 2.0 от Microsoft Entra: чтобы авторизовать запрос с помощью идентификатора Microsoft Entra, передайте x-ms-version заголовок запроса с версией службы 2017-11-09 или более поздней. Дополнительные сведения см. в статье Операции хранилища вызовов с помощью маркеров OAuth в статье Авторизация с помощью идентификатора Microsoft Entra.

• Запросы, использующие Shared Key или Shared Key Lite: Чтобы авторизовать запрос с помощью Shared Key или Shared Key Lite, передайте x-ms-version заголовок запроса. При использовании хранилища BLOB-объектов Azure можно указать версию по умолчанию для всех запросов, вызвав команду Задать свойства службы BLOB-объектов.

• Запросы, использующие подписанный URL-адрес (SAS): вы можете указать два параметра управления версиями в подписанном URL-адресе. Необязательный api-version заголовок указывает, какую версию службы следует использовать для выполнения операции API. Обязательный SignedVersion (sv) параметр указывает версию службы, используемую для авторизации запроса, сделанного с помощью SAS. api-version Если заголовок не указан, значение параметра SignedVersion (sv) также указывает версию, используемую для выполнения операции API.

• Запросы, использующие анонимный доступ: при использовании анонимного доступа к хранилищу BLOB-объектов версия не передается. Эвристика для определения версии, используемой для запроса, описана в следующих разделах.

Авторизация запросов с помощью идентификатора Microsoft Entra, общего ключа или общего ключа Lite

Чтобы авторизовать запрос с помощью Microsoft Entra ID, Shared Key или Shared Key Lite, укажите заголовок x-ms-version в запросе. Значение x-ms-version заголовка запроса должно быть указано в формате ГГГГ-ММ-ДД. Рассмотрим пример.

Request Headers:  
x-ms-version: 2020-04-08

В следующих правилах описывается, как эти запросы оцениваются, чтобы определить, какая версия используется для обработки запроса.

• Если запрос имеет валидный x-ms-version заголовок, сервис хранилища использует указанную версию. Во всех запросах к Хранилищу таблиц Azure и Хранилищу очередей Azure, в которых не используется подписанный URL-адрес, должен быть указан заголовок x-ms-version . Во всех запросах к хранилищу BLOB-объектов, в которых не используется подписанный URL-адрес, должен быть указан x-ms-version заголовок, если не задана версия по умолчанию, как описано в следующем абзаце.

• Если запрос к хранилищу BLOB-объектов не содержит x-ms-version заголовка, но владелец учетной записи задает версию по умолчанию с помощью операции Задать свойства службы BLOB-объектов , указанная версия по умолчанию используется в качестве версии для запроса.

Авторизация запросов с помощью подписанного URL-адреса

Подписанный URL-адрес (SAS), созданный с помощью версии 2014-02-14 или более поздней, поддерживает два варианта управления версиями:

• Параметр api-version query определяет версию протокола REST, используемую для обработки запроса, выполненного с помощью SAS.

• Параметр SignedVersion (sv) запроса определяет версию SAS, используемую для авторизации.

Параметр SignedVersion query используется для авторизации, когда клиент делает запрос с помощью SAS. Параметры авторизации, такие как si, sr, sp, sigstsetnspksrkepkи erk все интерпретируются с использованием указанной версии.

Параметры протокола REST, такие как rscc, rscd, rscerscl, и rsct применяются с помощью версии, указанной в заголовке параметраapi-version. Если заголовок не указан, api-version используется предусмотренная SignedVersion версия службы.

Этот api-version параметр не является частью строки для подписи в заголовке авторизации, как описано в разделе Создание службы SAS.

В следующей таблице описана схема управления версиями, используемая службой для авторизации и вызова протокола REST, если для параметра SignedVersion задана версия 2014-02-14 или более поздняя.

Пример 1

В следующем примере запроса List Blobs вызывается с 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

В следующем примере запроса вызывается List Blobs с 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&api-version=2012-02-12

Здесь служба авторизует запрос с помощью версии 2015-04-05 и выполняет операцию с помощью версии 2012-02-12.

Запросы через анонимный доступ

Запросы, сделанные с помощью анонимного доступа, обрабатываются по-разному в зависимости от типа учетной записи хранения, которую они выполняют.

Учетные записи хранения общего назначения

Если в анонимном запросе к учетной записи хранения общего назначения не указан заголовок x-ms-version , а версия по умолчанию для службы не задается с помощью функции "Задать свойства службы BLOB-объектов", служба использует самую раннюю возможную версию для обработки запроса. Если контейнер был сделан общедоступным с помощью операции Set Container ACL версии 2009-09-19 или более поздней, запрос обрабатывается с использованием версии 2009-09-19.

Для учетных записей хранения BLOB-объектов

Если в анонимном запросе к учетной записи хранилища BLOB-объектов не указан заголовок x-ms-version и версия по умолчанию для службы не задается с помощью функции "Задать свойства службы BLOB-объектов", служба использует самую раннюю возможную версию для обработки запроса. Для учетной записи хранения BLOB-объектов самая ранняя версия — 2014-02-14.

Известные проблемы

В этом разделе описаны известные проблемы с REST API службы хранилища Azure.

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