Put Page (Вставка страницы)

Операция Put Page записывает диапазон страниц в страничный большой двоичный объект.

Запрос

Запрос можно создать Put Page следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS. Замените myaccount именем своей учетной записи хранения:

URI запроса метода PUT параметр "Версия HTTP"
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1

Запрос службы эмулированного хранилища

При выполнении запроса к эмулированной службе хранилища укажите имя узла эмулятора и порт службы BLOB-объектов как 127.0.0.1:10000, а затем имя эмулированной учетной записи хранения:

URI запроса метода PUT параметр "Версия HTTP"
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page HTTP/1.1

Дополнительные сведения см. в статье Использование эмулятора Azurite для разработки и тестирования службы хранилища Azure.

Параметры универсального кода ресурса (URI)

В запросе URI можно указать следующие дополнительные параметры.

Параметр Описание
timeout Необязательный элемент. Параметр timeout указывается в секундах. Дополнительные сведения см. в статье Настройка времени ожидания для операций службы BLOB-объектов.

Заголовки запросов

Обязательные и необязательные заголовки запросов описаны в следующей таблице:

Заголовок запроса Описание
Authorization Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
Date или x-ms-date Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
x-ms-version Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
Range Требуется Range или x-ms-range.

Указывает диапазон байтов, записываемых как одна страница. Следует указать начало и конец диапазона. Этот заголовок определяется спецификацией протокола HTTP/1.1.

Для операции обновления страницы диапазон страниц может составлять до 4 МиБ. Для операции очистки страниц диапазон страниц может быть таким же, как и значение полного размера большого двоичного объекта.

Так как страницы должны быть выровнены по 512-байтовой границе, начальное смещение должно быть модулю 512, а конечное смещение — модулю 512–1. Примерами допустимых диапазонов байтов являются 0–511, 512–1023 и т. д.

Хранилище BLOB-объектов принимает только один байтовый диапазон для заголовка Range , а диапазон байтов должен быть указан в следующем формате: bytes=startByte-endByte.

Если заданы оба параметра, Range и x-ms-range, то служба использует значение x-ms-range. Дополнительные сведения см . в разделе Указание заголовка диапазона для операций службы BLOB-объектов.
x-ms-range Требуется Range или x-ms-range.

Указывает диапазон байтов, записываемых как одна страница. Следует указать начало и конец диапазона. Этот заголовок определяется спецификацией протокола HTTP/1.1.

Для операции обновления страницы диапазон страниц может быть размером до 4 МиБ. Для операции очистки страницы диапазон страниц не может превышать полный размер большого двоичного объекта.

Так как страницы должны быть выровнены по 512-байтовой границе, начальное смещение должно быть модулю 512, а конечное смещение должно быть модулю 512–1. Примеры допустимых диапазонов байтов: 0–511, 512–1023 и т. д.

Хранилище BLOB-объектов принимает только один байтовый диапазон для заголовка x-ms-range , а диапазон байтов должен быть указан в следующем формате: bytes=startByte-endByte.

Если заданы оба параметра, Range и x-ms-range, то служба использует значение x-ms-range. Дополнительные сведения см . в разделе Указание заголовка диапазона для операций службы BLOB-объектов .
Content-Length Обязательный. Указывает число байтов, передаваемых в тексте запроса. Если для заголовка x-ms-page-write задано значение clear, значение этого заголовка должно быть равно 0.
Content-MD5 Необязательный элемент. Хэш MD5 содержимого страницы. Этот хэш используется для проверки целостности страницы в течение транспорта. Если указан этот заголовок, то служба хранилища сравнивает хэш полученного содержимого со значением, полученным в этом заголовке.
<br / >Примечание. Этот хэш MD5 не хранится в большом двоичном объекте.

Если два хэша не совпадают, операция завершается ошибкой с кодом 400 (недопустимый запрос).
x-ms-content-crc64 Необязательный элемент. Хэш CRC64 содержимого страницы. Этот хэш используется для проверки целостности страницы в течение транспорта. Если указан этот заголовок, то служба хранилища сравнивает хэш полученного содержимого со значением, полученным в этом заголовке.

Примечание. Этот хэш CRC64 не хранится в большом двоичном объекте.

Если два хэша не совпадают, операция завершается ошибкой с кодом 400 (недопустимый запрос).

Если присутствуют оба заголовка Content-MD5 и x-ms-content-crc64 , запрос завершается ошибкой 400 (недопустимый запрос).

Этот заголовок поддерживается в версии 2019-02-02 и более поздних версиях.
x-ms-page-write: {update ¦ clear} Обязательный. Можно указать один из следующих параметров.

- Update: записывает байты, указанные текстом запроса, в указанный диапазон. Для выполнения обновления заголовки Range и Content-Length должны совпадать.
- Clear: очищает указанный диапазон и освобождает пространство, используемое в хранилище для этого диапазона. Чтобы очистить диапазон, задайте для заголовка Content-Length0значение , а для заголовка Range — значение, указывающее диапазон, который нужно очистить, вплоть до максимального размера большого двоичного объекта.
x-ms-encryption-scope Необязательный элемент. Указывает область шифрования для шифрования содержимого запроса. Этот заголовок поддерживается в версии 2019-02-02 и более поздних версиях.
x-ms-lease-id:<ID> Требуется, если у большого двоичного объекта имеется активная аренда. Для выполнения этой операции в большом двоичном объекте с активной арендой укажите допустимый идентификатор аренды для этого заголовка.
x-ms-if-sequence-number-le: <num> Необязательный элемент. Если порядковый номер большого двоичного объекта меньше или равен указанному значению, запрос продолжается. В противном случае происходит сбой с ошибкой SequenceNumberConditionNotMet (код состояния HTTP 412 — сбой предварительного условия).
x-ms-if-sequence-number-lt: <num> Необязательный элемент. Если порядковый номер большого двоичного объекта меньше указанного значения, запрос продолжается. В противном случае происходит сбой с ошибкой SequenceNumberConditionNotMet (код состояния HTTP 412 — сбой предварительного условия).
x-ms-if-sequence-number-eq: <num> Необязательный элемент. Если порядковый номер большого двоичного объекта равен указанному значению, запрос продолжается. В противном случае происходит сбой с ошибкой SequenceNumberConditionNotMet (код состояния HTTP 412 — сбой предварительного условия).
If-Modified-Since Необязательный элемент. Значение DateTime. Укажите этот условный заголовок для записи страницы только в том случае, если большой двоичный заголовок был изменен с указанных даты и времени. Если большой двоичный объект не был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
If-Unmodified-Since Необязательный элемент. Значение DateTime. Укажите этот условный заголовок для записи страницы, только если большой двоичный объект не был изменен с указанной даты и времени. Если большой двоичный объект был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
If-Match Необязательный элемент. Значение ETag. Укажите значение ETag, чтобы этот условный заголовок записал страницу, если значение ETag большого двоичного объекта совпадает с указанным значением. Если значения не совпадают, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
If-None-Match Необязательный элемент. Значение ETag.

Укажите значение ETag для этого условного заголовка, чтобы записать страницу, только если значение ETag большого двоичного объекта не соответствует указанному значению. Если значения идентичны, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
x-ms-client-request-id Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Хранилище BLOB-объектов Azure.

Эта операция также поддерживает использование условных заголовков для выполнения операции при выполнении определенного условия. Дополнительные сведения см . в разделе Указание условных заголовков для операций службы BLOB-объектов.

Заголовки запросов (ключи шифрования, предоставленные клиентом)

Начиная с версии 2019-02-02 в запросе можно указать следующие заголовки для шифрования BLOB-объекта с помощью ключа, предоставленного клиентом. Шифрование с помощью ключа, предоставленного клиентом (и соответствующего набора заголовков), является необязательным.

Заголовок запроса Описание
x-ms-encryption-key Обязательный. Ключ шифрования AES-256 в кодировке Base64.
x-ms-encryption-key-sha256 Обязательный. Хэш SHA256 в кодировке Base64 ключа шифрования.
x-ms-encryption-algorithm: AES256 Обязательный. Указывает алгоритм, используемый для шифрования. Для этого заголовка должно быть установлено значение AES256.

Текст запроса

Текст запроса содержит страницу.

Пример запроса: обновление диапазона байтов

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2011-08-18  
x-ms-range: bytes=0-65535  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536  
  

Пример запроса: очистка диапазона байтов

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-page-write: clear  
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT  
x-ms-version: 2011-08-18  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
  

Ответ

Ответ включает код состояния HTTP и набор заголовков ответа.

Код состояния

Успешная операция возвращает код состояния 201 (создано).

Дополнительные сведения о кодах состояния см. в разделе Коды состояния и ошибок.

Заголовки ответов

Ответ для этой операции включает следующие заголовки. Ответ может также включать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.

Синтаксис Описание
ETag ETag BLOB-объекта. Если версия запроса — 18.08.2011 и выше, значение ETag заключено в кавычки. ETag можно использовать для выполнения условной операции Put Page путем указания значения в заголовке запроса If-Match или If-None-Match.
Last-Modified Дата и время последнего изменения большого двоичного объекта. Дата в формате согласно RFC 1123. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках.

Любая операция записи в большой двоичный объект, включая обновления метаданных или свойств, изменяет время последнего изменения большого двоичного объекта.
Content-MD5 Этот заголовок возвращается для того, чтобы клиент мог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется хранилищем BLOB-объектов. Оно не обязательно совпадает со значением, указанным в заголовках запроса. Для версии 2019-02-02 и более поздних этот заголовок возвращается только в том случае, если запрос содержит этот заголовок.
x-ms-content-crc64 Для версии 2019-02-02 или более поздней этот заголовок возвращается, чтобы клиент проверка для целостности содержимого сообщения. Значение этого заголовка вычисляется хранилищем BLOB-объектов. Оно не обязательно совпадает со значением, указанным в заголовках запроса.

Этот заголовок возвращается, если Content-MD5 заголовок отсутствует в запросе.
x-ms-blob-sequence-number Текущий порядковый номер для страничного большого двоичного объекта.
x-ms-request-id Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок с запросом. Дополнительные сведения см. в статье Устранение неполадок с операциями API.
x-ms-version Указывает версию службы BLOB-объектов, которая использовалась для выполнения запроса. Этот заголовок возвращается для запросов, выполненных в отношении версии 2009-09-19 и более поздних версий.
Date Значение даты и времени в формате UTC, созданное службой, которое указывает время инициации ответа.
x-ms-request-server-encrypted: true/false Версия 11.12.2015 и более поздняя. Значение этого заголовка устанавливается в , true если содержимое запроса успешно зашифровано с помощью указанного алгоритма. В противном случае задается значение false.
x-ms-encryption-key-sha256 Версия 2019-02-02 и более поздние версии. Возвращается, если в запросе используется предоставленный клиентом ключ для шифрования, поэтому клиент может убедиться, что содержимое запроса успешно зашифровано с помощью предоставленного ключа.
x-ms-encryption-scope Версия 2019-02-02 и более поздние версии. Возвращается, если запрос использовал область шифрования, чтобы клиент смог убедиться, что содержимое запроса успешно зашифровано с помощью область шифрования.
x-ms-client-request-id Может использоваться для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению заголовка x-ms-client-request-id , если он присутствует в запросе и содержит не более 1024 видимых символов ASCII. Если заголовок x-ms-client-request-id отсутствует в запросе, он не будет присутствовать в ответе.

Текст ответа

Нет.

Пример ответа

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

Авторизация

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

Важно!

Корпорация Майкрософт рекомендует использовать Microsoft Entra ID с управляемыми удостоверениями для авторизации запросов к службе хранилища Azure. Microsoft Entra ID обеспечивает более высокий уровень безопасности и простоту использования по сравнению с авторизацией с общим ключом.

Служба хранилища Azure поддерживает использование Microsoft Entra ID для авторизации запросов к данным BLOB-объектов. С помощью Microsoft Entra ID можно использовать управление доступом на основе ролей Azure (Azure RBAC) для предоставления разрешений субъекту безопасности. Субъектом безопасности может быть пользователь, группа, субъект-служба приложения или управляемое удостоверение Azure. Субъект безопасности проходит проверку подлинности Microsoft Entra ID для возврата маркера OAuth 2.0. Затем маркер можно использовать для авторизации запроса к службе BLOB-объектов.

Дополнительные сведения об авторизации с помощью Microsoft Entra ID см. в статье Авторизация доступа к BLOB-объектам с помощью Microsoft Entra ID.

Разрешения

Ниже перечислены действия RBAC, необходимые Microsoft Entra пользователю, группе, управляемому удостоверению или субъекту-службе для вызова Put Page операции, а также встроенная роль Azure RBAC с минимальными привилегиями, которая включает это действие.

Дополнительные сведения о назначении ролей с помощью Azure RBAC см. в статье Назначение роли Azure для доступа к данным BLOB-объектов.

Комментарии

Операция Put Page записывает диапазон страниц в страничный большой двоичный объект. Эта операция может вызываться только для существующего страничного BLOB-объекта. Его нельзя вызвать для создания страничного BLOB-объекта, а также для блочного BLOB-объекта. Вызов Put Page с именем большого двоичного объекта, который в настоящее время не существует, возвращает код состояния HTTP 404 (не найдено).

Чтобы создать страничный BLOB-объект, вызовите метод Put BLOB-объект и укажите тип большого двоичного объекта для создания в виде страничного BLOB-объекта. Размер страничного BLOB-объекта может составлять до 8 ТиБ.

Если большой двоичный объект имеет активную аренду, клиент должен указать действительный идентификатор аренды в запросе на запись страницы.

Операции обновления страниц

Вызов метода Put Page с параметром Update выполняет локальную запись в указанный страничный большой двоичный объект. Содержимое на указанной странице будет перезаписано в результате обновления.

Важно!

Если время ожидания сервера истекает или подключение закрыто во время Put Page операции, страница может быть обновлена или не обновлена. Поэтому следует продолжать повторять обновление, пока не получите ответ, указывающий на успешное выполнение.

Каждый диапазон страниц, отправляемых с Put Page для операции обновления, может иметь размер до 4 МиБ. Начальный и конечный диапазон страницы не должны превышать ограничение в 512 байт. При попытке отправить диапазон страниц размером более 4 МиБ служба возвращает код состояния 413 (слишком большой объект запроса).

Операции очистки страниц

Вызов Put Page с параметром Clear освобождает дисковое пространство, используемое указанной страницей. Очищенные страницы больше не отслеживаются как часть страничного большого двоичного объекта.

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

Управление проблемами с параллелизмом

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

  • Можно проверить значение заголовка ответа Last-Modified для каждого успешного вызова Put Page. Порядок ответов, возвращаемых из Хранилища BLOB-объектов, не обязательно соответствует порядку их выполнения службой. Однако значение Last-Modified всегда указывает порядок, в котором служба обрабатывала запросы.

  • Обновления можно выполнять условно, исходя из значения ETag большого двоичного объекта или времени последнего изменения, опираясь на оптимистичный параллелизм. Этот подход хорошо работает для относительно небольшого числа параллельных операций записи. Для этой цели нужно использовать условные заголовки If-Match, If-None-Match, If-Modified-Since и If-Unmodified-Since.

  • Вы можете вызвать blob-объект аренды , чтобы заблокировать большой двоичный объект для других операций записи на одну минуту или дольше, если аренда продлена.

  • Вы можете использовать порядковый номер большого двоичного объекта, чтобы убедиться, что повторная попытка запроса, для которого не было ответа, не приведет к параллельным обновлениям. Этот подход лучше всего подходит для клиентов, которым требуется высокая пропускная способность для записи страниц. Это подробно описано в следующем разделе.

Использование порядкового номера страничного BLOB-объекта для повторных запросов

Если время ожидания вызова Put Page истекает или не возвращает ответ, невозможно точно узнать, успешно ли выполнен запрос. Поэтому необходимо повторить запрос, но из-за распределенного характера служб хранилища Azure исходный запрос может быть обработан после успешного выполнения повторного запроса. Отложенный первоначальный запрос может перезаписать другие обновления и привести к непредвиденному результату. В следующей последовательности показано, как это может произойти:

  1. Запрос Put Page на запись значения "X" на страницу 0 истекает или не возвращает ответ.

  2. Повторный запрос на запись значения X в страницу 0 завершается успешно.

  3. Запрос на запись значения Y в страницу 0 завершается успешно.

  4. Первоначальный запрос завершается успешно и записывает значение X в страницу 0.

  5. Операция чтения страницы 0 возвращает значение X, тогда как клиент ожидал получить значение Y.

Такой конфликт может возникать, если исходный запрос не возвращает код состояния от 100 до 499 или 503 (занят сервер). Если возвращается один из этих кодов, то можно быть уверенным, завершился ли запрос успешно. Однако если служба возвращает код состояния за пределами этого диапазона, то нет возможности узнать состояние первоначального запроса.

Чтобы избежать такого рода конфликтов, можно использовать порядковый номер страничного BLOB-объекта, чтобы убедиться, что при повторной попытке запроса исходный запрос не будет выполнен. Для этого, прежде чем повторять первоначальный запрос, необходимо увеличить порядковый номер. Затем можно использовать заголовки условного порядкового номера, чтобы убедиться, что запрос завершится ошибкой, если его порядковый номер не соответствует ожидаемому порядкового номера. Этот подход показан на следующей схеме.

  1. Клиент создает страничный BLOB-объект с помощью Put BLOB-объект и задает его порядковый номер 0.

  2. Запрос Put Page на запись значения "X" на страницу 0 с заголовком if-sequence-number-lt , равным 1 времени ожидания, или не возвращает ответ.

  3. Клиент вызывает Set Blob Properties , чтобы обновить порядковый номер на 1.

  4. Повторный запрос на запись значения "X" на страницу 0 с if-sequence-number-lt параметром " 2 Успешно".

  5. Запрос на запись значения "Y" на страницу 0 с if-sequence-number-lt заданным значением 2 выполняется успешно.

  6. Исходный запрос, наконец, обрабатывается, но он завершается сбоем, так как указывает условие, что порядковый номер должен быть меньше 1 (то есть if-sequence-num-lt заголовок имеет значение 1). Возникает ошибка SequenceNumberConditionNotMet (код состояния HTTP 412 — не выполнено предварительное условие).

  7. Чтение страницы 0 возвращает ожидаемое значение Y.

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

Авторизация запросов к службе хранилища Azure
Коды состояний и ошибок
Настройка времени ожидания для операций службы BLOB-объектов