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

  • Статья

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

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

Версия службы 2023-11-03 включает следующие функции:

  • Нет.

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

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

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

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

  • Запросы, использующие подписанный URL-адрес (SAS): вы можете указать два параметра управления версиями для подписанного URL-адреса. Необязательный 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 необходимо указывать в формате ГГГГ-ММ-ДД. Пример:

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 запроса определяет версию протокола REST, используемую для обработки запроса, выполненного с помощью SAS.

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

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

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

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

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

Значение параметра api-version Версия, используемая для авторизации Версия, используемая для поведения протокола
Не указано Версия, указанная в параметре sv Версия, указанная в параметре sv
Любая допустимая версия служб хранилища в формате XXXX-XX-XX Версия, указанная в параметре sv Допустимая версия служб хранилища XXXX-XX-XX

Пример 1

В следующем примере запроса вызывается перечисление BLOB-объектов с 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

Следующий пример запроса вызывает перечисление BLOB-объектов с 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.

Примечание

Клиентская библиотека хранилища .NET всегда задает версию протокола REST (в параметре api-version ) версию, на основе которую она основана.

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

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

Для учетных записей хранения общего назначения

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

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

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

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

В этом разделе описаны известные проблемы с 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, чтобы узнать, устранена ли проблема. Если проблема не исчезнет или рекомендация не представляется возможной, отправьте запрос в службу поддержки , чтобы обсудить дополнительные варианты.

См. также раздел