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


Поставить страницу

Операция 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 запроса:

Параметр Description
timeout Необязательно. Параметр timeout выражается в секундах. Для получения дополнительной информации см. раздел «Установка тайм-аутов для операций сервиса Blob».

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

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

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

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

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

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

Blob Storage принимает только один байтовый диапазон для 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 Storage принимает только один байтовый диапазон для 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 не хранится вместе с blob.

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

Примечание: этот хэш CRC64 не хранится вместе с blob.

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

Если оба Content-MD5x-ms-content-crc64 заголовка и присутствуют, запрос проваливается с 400 (плохой запрос).

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

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

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

Эта операция также поддерживает использование условных заголовков для выполнения операции только при выполнении заданного условия. Для получения дополнительной информации см. раздел «Указать условные заголовки для операций сервиса Blob».

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

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

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

Заголовки запросов (структурированное тело)

По состоянию на версию 2025-01-05 в запросе могут быть указаны следующие заголовки для использования формата структурированного тела.

Заголовок запроса Description
Content-Length Обязательное. Должна быть длина закодированного запроса (а не только длина содержимого страницы).

Если значение заголовка не совпадает с ожидаемой длиной закодированного запроса, операция неудачна с кодом ошибки 400 (Плохой запрос).
x-ms-structured-body Обязательное. Необходимо включить, если формат сообщения структурирован. Значение этого заголовка содержит версию схемы сообщений и свойства.

В настоящее время единственное поддерживаемое значение — XSM/1.0; properties=crc64, указывающее, что запрос использует сегменты контрольной суммы crc64 в закодированном сообщении. Если значение не совпадает с этим, операция заканчивается с кодом ошибки 400 (Плохой запрос). Запрос также будет неудачным, если содержание, предоставленное в запросе, не совпадает с предоставленной контрольной суммой для данного сегмента с кодом ошибки 400 (Плохой запрос).
x-ms-structured-content-length Обязательное. Необходимо включить, если формат сообщения структурирован. Значение этого заголовка — это длина содержимого страницы и всегда будет меньше Content-Length значения заголовка из-за кодирования сообщений. Если значение заголовка не совпадает с длиной блока, указанного в запросе, операция заканчивается с ошибкой 400 (Плохой запрос).

Основное содержание запроса

Тело запроса содержит содержание страницы.

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

  
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.

Синтаксис Description
ETag ETag для blob-а. Если запросная версия — 2011-08-18 и выше, значение ETag прилагается в кавычки. ETag может использоваться для выполнения условной Put Page операции с указанием её значения для If-Match заголовка или If-None-Match запроса.
Last-Modified Дата и время последней модификации этого комка. Формат даты соответствует RFC 1123. Для получения дополнительной информации см. Представление значений даты/времени в заголовках.

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

Этот заголовок возвращается, когда 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 Версия 2015-12-11 и более поздняя. Значение этого заголовка задаётся равным 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, он не будет присутствовать в ответе.
x-ms-structured-body Возвращается, если запрос был обработан как структурированный запрос. Значение этого заголовка равно значению, отправленному в запросе, которое в настоящее время должно быть XSM/1.0; properties=crc64.

Основная часть ответа

Нет.

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

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  
  

Authorization

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

Это важно

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

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

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

Permissions

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

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

Замечания

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

Чтобы создать новый блоб страницы, вызовите Put Blob и укажите тип blob для создания в виде блоба страницы. Пятно страницы может достигать размера до 8 TiB.

Если у blob активный договор аренды, клиент должен указать действительный идентификатор аренды в запросе для написания страницы.

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

Вызов Put Page с Update помощью опции выполняет запись на месте на указанной блобе страницы. Любой контент на указанной странице перезаписывается обновлением.

Это важно

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

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

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

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

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

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

Blob Storage обрабатывает параллельные записи на перекрывающиеся страницы последовательно. То есть последняя страница, обработанная сервисом, определяет содержимое blob. Поэтому для обеспечения целостности содержимого blob клиент должен выполнять записи на перекрывающиеся страницы с помощью одного или нескольких следующих подходов:

  • Вы можете проверить значение Last-Modified заголовка ответа для каждого успешного вызова в Put Page. Порядок возврата ответов из Blob Storage не обязательно соответствует порядку их выполнения сервисом. Но значение всегда Last-Modified указывает на порядок, в котором сервис обработал запросы.

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

  • Вы можете позвонить в Lease Blob , чтобы заблокировать 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 (Сервер занят). Если один из этих кодов статуса возвращается, вы можете быть уверены, выполнен ли запрос успешным или неуспешным. Но если сервис возвращает статус за пределами этого диапазона, невозможно узнать статус исходного запроса.

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

  1. Клиент создаёт блоб страницы с помощью 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