Указание условных заголовков для операций службы BLOB-объектов
Несколько операций в службе BLOB-объектов поддерживают использование условных заголовков. Условные заголовки можно указывать для выполнения операции только при указанном условии.
Служба BLOB-объектов соответствует спецификации протокола HTTP/1.1 для условных заголовков.
Поддерживаемые условные заголовки
Поддерживаемые условные заголовки описаны в следующей таблице.
| Условный заголовок | Описание |
|---|---|
If-Modified-Since |
Значение DateTime. Дата в формате согласно RFC 1123. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Укажите этот заголовок для выполнения операции только в том случае, если ресурс был изменен в указанное время. |
If-Unmodified-Since |
Значение DateTime. Дата в формате согласно RFC 1123. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Укажите этот заголовок для выполнения операции только в том случае, если ресурс не был изменен в указанные дату и время. |
If-Match |
Значение ETag. Укажите этот заголовок для выполнения операции только в том случае, если ETag ресурса соответствует указанному значению. В версии 2011-08-18 и более новой ETag можно указывать в кавычках. |
If-None-Match |
Значение ETag или подстановочный знак (*). Укажите этот заголовок для выполнения операции только в том случае, если ETag ресурса не соответствует указанному значению. В версии 2011-08-18 и более новой ETag можно указывать в кавычках. Укажите символ-шаблон (*) для выполнения операции только в том случае, если ресурс не существует, и отказа от операции, если он существует. |
Указание условных заголовков для операций чтения службы BLOB-объектов в версии 2013-08-15 или более поздней версии
Начиная с версии 2013-08-15 операции Get Blob и Get Blob Properties поддерживают несколько условных заголовков. Можно указать любое сочетание поддерживаемых условных заголовков. Служба BLOB-объектов будет оценивать эти условия в соответствии со следующим выражением:
If-Match && If-Unmodified-Since && (If-None-Match || If-Modified-Since)
Можно также указать несколько значений с разделителями-запятыми для условий If-Match и If-None-Match. Если будет указано несколько значений для условия If-Match, то перед оценкой всего выражения служба BLOB-объектов выполнит логическую операцию OR для всех предоставленных значений. Если будет указано несколько значений для условия if-None-Match, то перед оценкой всего выражения служба выполнит логическую операцию AND. Указание нескольких значений для условий If-Modified-Since и If-Unmodified-Since не поддерживается и ведет к получению ошибки 400 (Bad Request).
Эта функция включена для соответствия спецификации HTTP/1.1 и для сценариев, в которых сеть доставки содержимого (CDN) или прокси-сервер добавляют дополнительные условные заголовки в запрос на выполнение. Ниже приведены некоторые примеры различных сочетаний условных заголовков.
Пример 1.
Рассмотрим запрос get BLOB-объекта , содержащий заголовки If-Match и If-Modified-Since . В следующей таблице показан результаты, которые формируются при вычислении заголовков по отдельности и при их совокупном вычислении.
| Условные заголовки | Результат при вычислении по отдельности | Результат при вычислении в сочетании |
|---|---|---|
If-Match |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Match |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
304 (Не изменено) | 412 (Необходимое условие не выполнено) |
If-Match |
200 OK; | 200 OK; |
If-Modified-Since |
200 OK; | 200 OK; |
If-Match |
200 OK; | 304 (Не изменено) |
If-Modified-Since |
304 (Не изменено) | 304 (Не изменено) |
Пример 2.
Рассмотрим запрос, содержащий заголовки If-None-Match и If-Modified-Since.
| Условные заголовки | Результат при вычислении по отдельности | Результат при вычислении в сочетании |
|---|---|---|
If-None-Match |
304 (Не изменено) | 200 OK; |
If-Modified-Since |
200 OK; | 200 OK; |
If-None-Match |
200 OK; | 200 OK; |
If-Modified-Since |
200 OK; | 200 OK; |
If-None-Match |
200 OK; | 200 OK; |
If-Modified-Since |
304 (Не изменено) | 200 OK; |
If-None-Match |
304 (Не изменено) | 304 (Не изменено) |
If-Modified-Since |
304 (Не изменено) | 304 (Не изменено) |
Пример 3:
Рассмотрим запрос, содержащий заголовки If-Modified-Since, If-Match и If-Unmodified-Since.
| Условные заголовки | Результат при вычислении по отдельности | Результат при вычислении в сочетании |
|---|---|---|
If-Modified-Since |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Match |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Unmodified-Since |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Match |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Unmodified-Since |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
304 (Не изменено) | 412 (Необходимое условие не выполнено) |
If-Match |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Unmodified-Since |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
304 (Не изменено) | 304 (Не изменено) |
If-Match |
200 OK; | 304 (Не изменено) |
If-Unmodified-Since |
200 OK; | 304 (Не изменено) |
Пример 4:
Рассмотрим запрос, содержащий заголовки If-Modified-Since, If-None-Match, If-Unmodified-Since и If-Match.
| Сочетание | Отдельный код состояния HTTP | Получение результата состояния большого двоичного объекта |
|---|---|---|
If-Modified-Since |
200 OK; | 200 OK; |
If-None-Match |
200 OK; | 200 OK; |
If-Unmodified-Since |
200 OK; | 200 OK; |
If-Match |
200 OK; | 200 OK; |
If-Modified-Since |
200 OK; | 412 (Необходимое условие не выполнено) |
If-None-Match |
304 (Не изменено) | 412 (Необходимое условие не выполнено) |
If-Unmodified-Since |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Match |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
200 OK; | 200 OK; |
If-None-Match |
304 (Не изменено) | 200 OK; |
If-Unmodified-Since |
200 OK; | 200 OK; |
If-Match |
200 OK; | 200 OK; |
If-Modified-Since |
304 (Не изменено) | 412 (Необходимое условие не выполнено) |
If-None-Match |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Unmodified-Since |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Match |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
304 (Не изменено) | 412 (Необходимое условие не выполнено) |
If-None-Match |
200 OK; | 412 (Необходимое условие не выполнено) |
If-Unmodified-Since |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Match |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Modified-Since |
304 (Не изменено) | 200 OK; |
If-None-Match |
200 OK; | 200 OK; |
If-Unmodified-Since |
200 OK; | 200 OK; |
If-Match |
200 OK; | 200 OK; |
If-Modified-Since |
304 (Не изменено) | 412 (Необходимое условие не выполнено) |
If-None-Match |
304 (Не изменено) | 412 (Необходимое условие не выполнено) |
If-Unmodified-Since |
412 (Необходимое условие не выполнено) | 412 (Необходимое условие не выполнено) |
If-Match |
200 OK; | 412 (Необходимое условие не выполнено) |
Указание условных заголовков для операций чтения в версиях, предшествующих 2013-08-15, и для операций записи (все версии)
При вызове операций чтения службы BLOB-объектов (получение иполучение свойств BLOB-объектов) с версиями до 15-08-2013 и при вызове любой операции записи независимо от версии учитывайте следующее:
Если в запросе указаны заголовки
If-None-MatchиIf-Modified-Since, то запрос оценивается по критериям, указанным вIf-None-Match.Если в запросе указаны заголовки
If-MatchиIf-Unmodified-Since, то запрос оценивается по критериям, указанным вIf-Match.За исключением двух сочетаний условных заголовков, приведенных выше, запрос может содержать только один условный заголовок. Указание более одного условного заголовка приведет к коду состояния 400 (
Bad Request).Если ответ включает ETag, проверьте версию запроса и ответа перед обработкой ETag. Например, версия 2011-08-18 и более поздние версии возвращают ETag в кавычках, а более старые — не возвращают. Убедитесь, что приложение может обрабатывать оба формата ETag, прежде чем их оценивать.
RFC 2616 допускает несколько значений ETag в одном заголовке, но запросы к службе BLOB-объектов могут включать только одно значение ETag. Указание нескольких значений ETag приведет к получению кода состояния 400 (
Bad Request).
Операции, поддерживающие условные заголовки
Операции, поддерживающие условные заголовки, описаны в следующей таблице.
| Операция REST | Operation type (Тип операции) | Поддерживаемые условные заголовки |
|---|---|---|
| Append Block (версия 21.02.2015 и более поздние версии) |
Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Добавление блока из URL-адреса (версия 2018-11-09 и более поздние версии) |
Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Копирование BLOB-объекта | Чтение и запись | Для условий в целевом BLOB-объекте: - If-Modified-Since - If-Unmodified-Since - If-Match - If-None-Match - x-ms-if-tags Для условий в BLOB-объекте источника: - x-ms-source-if-modified-since - x-ms-source-if-unmodified-since - x-ms-source-if-match - x-ms-source-if-none-match - x-ms-source-if-tags |
| Удаление BLOB-объекта | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Delete Container (Удаление контейнера) | Write | If-Modified-Since If-Unmodified-Since |
| Get BLOB (Получение BLOB-объекта) | Read | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Get BLOB Metadata (Получение метаданных BLOB-объекта) | Read | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Получение свойств большого двоичного объекта | Read | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Получение тегов BLOB-объектов (версия 2019-12-12 и более поздние версии) |
Read | x-ms-if-tags |
| Get Block List (Получение списка блокировки) | Read | x-ms-if-tags |
| Get Page Ranges (получение диапазона страницы); | Read | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Lease Blob (Аренда большого двоичного объекта) | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Аренда контейнера | Write | If-Modified-Since If-Unmodified-Since |
| Поместить BLOB-объект из URL-адреса | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match Для условий в BLOB-объекте источника: - x-ms-source-If-Modified-Since - x-ms-source-if-Unmodified-Since - x-ms-source-If-Match - x-ms-source-If-None-Match |
| Put BLOB (Вставка BLOB-объекта) | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Вставка блока из URL-адреса (версия 28.03.2018 и более поздние) |
Write | x-ms-source-If-Modified-Since x-ms-source-If-Unmodified-Since x-ms-source-If-Match x-ms-source-If-None-Match |
| Put Block List (Вставка списка блокировки) | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Put Page | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Вставка страницы из URL-адреса (версия 2018-11-09 и более поздние версии) |
Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set BLOB Metadata (Задание метаданных BLOB-объекта) | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set BLOB Properties (Задание свойств службы BLOB-объекта) | Write | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Set Container ACL | Write | If-Modified-Since If-Unmodified-Since |
| Настройка метаданных контейнера | Write | If-Modified-Since |
| Установка тегов BLOB-объектов (версия 2019-12-12 и более поздние версии) |
Write | x-ms-if-tags |
| Установка уровня большого двоичного объекта | Чтение или запись | x-ms-if-tags |
| Создание моментального снимка большого двоичного объекта | Read | If-Modified-Since If-Unmodified-Since If-Match If-None-Match x-ms-if-tags |
| Настройка политики неизменяемости BLOB-объектов | Write | If-Unmodified-Since |
Следующие операции с данными службы BLOB-объектов в настоящее время не поддерживают условные заголовки:
Коды ответа HTTP для операций, поддерживающих условные заголовки
Если запрос включает условный заголовок и запрошенный ресурс не удовлетворяет указанному условию, то служба BLOB-объектов возвращает код ответа HTTP. Возвращаемые коды ответа соответствуют спецификации протокола HTTP/1.1 (RFC 2616).
Методы в клиентской библиотеке Azure .NET преобразуют эти коды ответа на ошибки в объект StorageException.
Операции чтения
В следующей таблице показаны коды ответа, возвращенные при несоблюдении условия для каждого условного заголовка в случае, если операция является операцией чтения. В операциях чтения используются команды GET или HEAD.
| Условный заголовок | Код ответа при невыполнении условия |
|---|---|
If-Modified-Since |
Не изменено (304 (Не изменено)) |
If-Unmodified-Since |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-Match |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-None-Match |
Не изменено (304 (Не изменено)) |
См. в приведенных выше примерах результаты, получаемые при использовании нескольких заголовков с версиями 2013-08-15 или более поздними версиями.
Операции записи
В следующей таблице показаны коды ответа, возвращаемые при несоблюдении условия для каждого условного заголовка в случае, если операцией является операция записи. В операциях записи используются команды PUT или DELETE.
| Условный заголовок | Код ответа при невыполнении условия |
|---|---|
If-Modified-Since |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-Unmodified-Since |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-Match |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-None-Match |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
Операции копирования
В следующей таблице показаны коды ответа, возвращаемые при несоблюдении условия для каждого условного заголовка в случае, если операцией является операция копирования. Операция копирования BLOB-объекта использует команды PUT.
| Условный заголовок | Код ответа при невыполнении условия |
|---|---|
If-Modified-Since |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-Unmodified-Since |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-Match |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
If-None-Match |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
x-ms-source-if-modified-since |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
x-ms-source-if-unmodified-since |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
x-ms-source-if-match |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
x-ms-source-if-none-match |
Необходимое условие не выполнено (412 (Необходимое условие не выполнено)) |
Условные операции тегов
Помимо стандартных условных заголовков HTTP, поддерживаемых службой BLOB-объектов, несколько операций также поддерживают условия для тегов в ресурсе BLOB-объекта.
| Условный заголовок | Описание |
|---|---|
x-ms-if-tags |
Версия 2019-12-12 и более поздние версии. Значение TagsPredicate. Укажите этот заголовок для выполнения операции только в том случае, если предикат имеет значение для true тегов большого двоичного объекта. |
x-ms-source-if-tags |
Версия 2019-12-12 и более поздние версии. Применяется только к копированию BLOB-объекта. Значение TagsPredicate. Укажите этот заголовок, чтобы выполнить операцию только в том случае, если предикат имеет значение для true тегов исходного BLOB-объекта. |
Если условный x-ms-if-tags заголовок или x-ms-source-if-tags присутствует в запросе TagsPredicate и имеет значение false, служба BLOB-объектов вернет код ошибки 412 (сбой предварительного условия) для операции.
Вызывающий объект должен иметь разрешение на чтение тегов в большом двоичном объекте, чтобы использовать условные x-ms-if-tags заголовки или x-ms-source-if-tags .
Синтаксис предиката тегов
Служба BLOB-объектов поддерживает подмножество грамматики предложения ANSI SQL WHERE для значения заголовка TagsPredicate . Поддерживаются следующие операторы:
| Оператор | Описание | Пример |
|---|---|---|
= |
Равно | Status = 'In Progress' |
<> |
Не равно | Status <> 'Done' |
> |
Больше чем | LastModified > '2018-06-18 20:51:26Z' |
>= |
Больше или равно | Priority >= '05' |
< |
Меньше чем | Age < '032' |
<= |
Меньше или равно | Reviewer <= 'Smith' |
AND |
Логическое И | Name > 'C' AND Name < 'D'Age > '032' AND Age < '100' |
OR |
Логическое ИЛИ | Status = 'Done' or LastModified > '2018-06-18 20:51:26Z' |
Все значения тегов являются строками, а поддерживаемые бинарные реляционные операторы используют лексикографическую сортировку значений тегов. Для поддержки нестроковых типов данных, включая числа и даты, необходимо использовать соответствующее заполнение и сортируемое форматирование. Значения тегов должны быть заключены в одинарные кавычки.
Если имена тегов являются обычными идентификаторами SQL, они могут присутствовать без экранирования; Если они содержат специальные символы, они должны быть разделены двойными кавычками (например, "TagName" = 'TagValue').
Выражения могут включать сравнения для нескольких имен и значений тегов. Круглые скобки (( и )) можно использовать для группировки логических выражений и управления каноническим порядком операций. Может TagsPredicate включать не более десяти (10) логических операций.
Служба хранилища отклоняет любой запрос, содержащий недопустимое выражение с кодом ошибки 400 (недопустимый запрос).