Поделиться через

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

  • Статья

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

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

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

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

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

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

  • Запросы, использующие общий ключ или общий ключ Lite: чтобы авторизовать запрос с помощью общего ключа или общего ключа 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, общего ключа или общего ключа 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, но владелец учетной записи установил версию по умолчанию с помощью операции Set Blob Service Properties, указанная версия по умолчанию используется в качестве версии запроса.

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

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

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

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

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

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

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

Пример 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

В следующем примере запроса вызовы списков БОЛЬШИХ двоичных объектов с 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-объектов самая ранняя версия — 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, чтобы узнать, устранена ли проблема. Если проблема сохраняется или если рекомендация не подходит, откройте запрос в службу поддержки, чтобы обсудить дополнительные варианты.

См. также