Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Операция 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 action:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- Встроенная роль с наименьшими привилегиями:Участник данных BLOB-объектов хранилища
Дополнительные сведения о назначении ролей с помощью 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 хранилища возможно, что первоначальный запрос будет обработан после успешного выполнения. Отложенный первоначальный запрос может перезаписать другие обновления и привести к неожиданному результату. Следующая последовательность иллюстрирует, как это может произойти:
Запрос
Put Pageна запись значения «X» на странице 0 повторяется или не возвращает ответ.Повторная попытка записать значение «X» на страницу 0 успешно выполнена.
Запрос на запись значения «Y» на странице 0 успешно выполняется.
Первоначальный запрос выполнен успешно, записывая значение «X» на страницу 0.
Чтение страницы 0 возвращает значение «X», когда клиент в этот момент ожидал значение «Y».
Такой конфликт может возникать, если исходный запрос не возвращает статус с 100 по 499 или 503 (Сервер занят). Если один из этих кодов статуса возвращается, вы можете быть уверены, выполнен ли запрос успешным или неуспешным. Но если сервис возвращает статус за пределами этого диапазона, невозможно узнать статус исходного запроса.
Чтобы избежать такого конфликта, можно использовать номер последовательности страницы, чтобы при повторной попытке оригинальный запрос не был успешен. Для этого следует увеличить номер порядка перед повторной попыткой оригинального запроса. Затем можно использовать заголовки условного номера последовательности, чтобы убедиться, что запрос не соответствует ожидаемому. Следующая последовательность иллюстрирует этот подход:
Клиент создаёт блоб страницы с помощью Put Blob и устанавливает её номер последовательности в
0.Запрос
Put Pageна запись значения «X» на странице 0 сif-sequence-number-ltзаголовком на1тайм-аут или не возвращает ответ.Клиент вызывает
Set Blob Propertiesобновление последовательного номера до1.Повторный запрос на запись значения «X» на странице 0 с
if-sequence-number-ltустановкой2на успешный.Запрос на запись значения «Y» на странице 0 с
if-sequence-number-ltудалённым2результатом.Исходный запрос в конечном итоге обрабатывается, но не проходит, потому что задаётся условие, что номер порядка должен быть меньше 1 (то
if-sequence-num-ltесть заголовок установлен в1). Ошибка — SequenceNumberConditionNotMet (HTTP-код статуса 412 – предусловие невыполнено).Чтение страницы 0 возвращает ожидаемое значение «Y».
См. также
Авторизация запросов к службе хранилища Azure
Коды состояний и ошибок
Установка тайм-аутов для операций сервиса Blob