Поставить блок

Операция Put Block создаёт новый блок, который нужно фиксировать в составе blob-а.

Просьба

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

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

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

Когда вы отправляете запрос к эмулируемому сервису хранения, укажите имя хоста эмулятора и порт Blob как 127.0.0.1:10000, а затем имя эмулируемой записи хранения:

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

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

Параметры URI

Параметр Description
blockid Обязательное. Допустимое строковое значение Base64, идентифицирующее блок. Перед закодированием строка должна иметь размер меньше или равен 64 байтам.

Для определённого blob длина значения blockid параметра должна быть одинаковой для каждого блока.

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

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

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

Заголовок запроса Description
Authorization Обязательное. Указывает схему авторизации, имя учетной записи и подпись. См. раздел «Авторизировать запросы на Azure Storage » для получения дополнительной информации.
Date или x-ms-date Обязательное. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
x-ms-version Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Для получения дополнительной информации см. раздел Versioning for the Azure Storage Services.
Content-Length Обязательное. Длина содержания блока в байтах. Размер блока должен быть меньше или равен 4 000 мебибайт (МиБ) для версии 2019-12-12 и более поздней. См. раздел Примечания для ограничений в старых версиях.

Если длина не указана, операция неудачна с кодом статуса 411 (Требуется длина).
Content-MD5 Необязательно. MD5-хэш содержимого блока. Этот хэш используется для проверки целостности блока во время транспортировки. Когда этот заголовок задаётся, служба хранения сравнивает хэш пришедшего содержимого с этим значением заголовка.

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

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

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

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

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

Этот заголовок поддерживается в версиях 2019-02-02 и позднее.
x-ms-encryption-scope Необязательно. Указывает область шифрования, используемую для шифрования содержимого запроса. Этот заголовок поддерживается в версиях 2019-02-02 и позднее.
x-ms-lease-id:<ID> Требуется, если большой двоичный объект имеет действующую аренду. Чтобы выполнить эту операцию с большим двоичным объектом с активной арендой, укажите допустимый идентификатор аренды для этого заголовка.
x-ms-client-request-id Необязательно. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Мониторинг хранилища BLOB-объектов Azure.

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

По состоянию на версию 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=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576

Ответ

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

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

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

Сведения о кодах состояния см. в коды состояния и коды ошибок.

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

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

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

Этот заголовок возвращается, когда Content-md5 заголовок отсутствует в запросе.
x-ms-request-id Уникально идентифицирует выполненный запрос, и его можно использовать для устранения неполадок запроса. Дополнительные сведения см. в статье Устранение неполадок с операциями API.
x-ms-version Указывает версию Blob Storage, использовавшуюся для выполнения запроса. Этот заголовок возвращается для запросов, сделанных по версии 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:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Authorization

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

Это важно

Корпорация Майкрософт рекомендует использовать идентификатор 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 Block и минимально привилегированной встроенной роли Azure RBAC, которая включает в себя следующее:

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

Замечания

Put Block загружает блок для будущего включения в блоб. Каждый блок в блобе может быть разного размера. Блок-блоб может включать максимум 50 000 завершённых блоков.

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

Версия службы Максимальный размер блока (через Put Block) Максимальный размер капли (через Put Block List) Максимальный размер капли с помощью одной операции записи (через Put Blob)
Версия 2019-12-12 и более поздние 4 000 MiB Примерно 190,7 тебибайт (TiB) (4 000 МиБ × 50 000 блоков) 5 000 MiB
Версии 2016-05-31 по 2019-07-07 100 МиБ Примерно 4,75 TiB (100 MiB × 50 000 блоков) 256 МиБ
Версии, ранее 31.05.2016 4 МиБ Примерно 195 гибибайт (ГиБ) (4 МиБ × 50 000 блоков) 64 МиБ

Максимальное количество незакреплённых блоков, связанных с blob, составляет 100 000. Если это число превышается, сервис возвращает статус 409 (RequestEntityTooLargeBlockCountExceedsLimit).

После загрузки набора блоков вы можете создать или обновить blob на сервере из этого набора, вызвав операцию Put Block List . Каждый блок в наборе идентифицируется уникальным внутри этого blob блока ID. Идентификаторы блоков ограничены на определённый blob, поэтому разные blob-ы могут иметь блоки с одинаковыми ID.

Если вы вызываете Put Block blob, который ещё не существует, создаётся новый blob с длиной контента 0. Этот blob перечисляется List Blobs операцией, если указана опция include=uncommittedblobs . Блокировки или блоки, которые вы загружаете, не фиксируются до тех пор, пока вы не вызовете Put Block List новый blob. Блоб, созданный таким образом, поддерживается на сервере в течение недели. Если за этот период вы не добавляли больше блоков или фиксированных блоков в blob, то blob — это мусор.

Блок, который был успешно загружен с операцией Put Block , не становится частью blob, пока не будет зафиксирован с Put Block List. Перед Put Block List вызовом для фиксации нового или обновлённого blob любые вызовы Get blob возвращают содержимое blob без включения незакреплённого блока.

Если вы загрузите блок с тем же ID блока, что и другой блок, который ещё не был зафиксирован, последний загруженный блок с этим ID будет зафиксирован при следующей успешной Put Block List операции.

После Put Block List вызова все незакреплённые блоки, указанные в списке блоков, фиксируются как часть нового blob. Любые незакреплённые блоки, не указанные в списке блоков для blob, считаются мусором, собранным и удалённым из хранилища blob. Любые незакреплённые блоки также считаются мусором, если в течение недели после последней успешной Put Block операции не было успешных вызовов Put Block List или Put Block на тот же blob. Если на блобе вызывается Put Blob , любые незакреплённые блоки считаются сбором мусора.

Если у blob есть активный договор аренды, клиент должен указать действительный идентификатор аренды в запросе для записи блока в blob. Если клиент либо не указывает идентификатор аренды, либо указывает недействительный идентификатор аренды, Blob Storage возвращает статус 412 (предварительное условие не выполнено). Если клиент указывает идентификатор аренды, но у blob нет активного договора аренды, Blob Storage также возвращает статус 412 (предварительное условие не выполнено).

Для определённого blob все идентификаторы блоков должны иметь одинаковую длину. Если блок загружен с идентификатором блока другой длины, чем у существующих незакреплённых блоков, сервис возвращает код ответа на ошибку 400 (Плохой запрос).

Если вы попытаетесь загрузить блок объемом более 4 000 МиБ для версии 2019-12-12 или новее, более 100 МиБ для версии 2016-05-31 и выше, или более 4 МиБ для старых версий, сервис возвращает статус 413 (Request Entity Too Large). Сервис также возвращает дополнительную информацию об ошибке в ответе, включая максимальный допустимый размер блока, в байтах.

Вызов Put Block не обновляет последний изменённый момент существующего blob-а.

Вызов Put Block блоба страницы возвращает ошибку.

Вызов Put Block From URL blob не меняет уровень blob, но вызов blob archive возвращает ошибку.

Выставление счетов

Запросы на оплату могут исходить от клиентов, использующих API хранилища BLOB-объектов, либо непосредственно через REST API хранилища BLOB-объектов, либо из клиентской библиотеки службы хранилища Azure. За эти запросы взимается плата за каждую транзакцию. Тип транзакции влияет на то, как будет взиматься плата со счета. Например, транзакции чтения относятся к другой категории выставления счетов, чем транзакции записи. В следующей таблице показана категория выставления счетов для Put Block запросов в зависимости от типа учетной записи хранения:

Операция Тип учетной записи хранения Категория биллинга
Поставить блок Блочный BLOB-объект категории "Премиум".
Стандартная версия общего назначения v2
Стандартный общего назначения версии 1		 Операциизаписи 1

Операции 1Put Block записывают блоки в временное хранилище, используя стандартный уровень доступа для аккаунта хранения. Например, если вы загружаете blob на архивный уровень, любые Put Block операции, входящие в состав загрузки, оплачиваются как операции записи в зависимости от стандартного уровня доступа для аккаунта хранения, а не на уровне назначения. Put Block List а Put Blob операции, однако, оплачиваются как операции записи, исходя из целевого уровня blob.

Сведения о ценах для указанной категории выставления счетов см. в статье Цены на хранилище BLOB-объектов Azure.

См. также

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

  • Last updated on