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

Put Block (Вставка блокировки)

  • Статья

Операция Put Block создает новую блокировку, которую следует зафиксировать в составе большого двоичного объекта.

Запрос

Запрос можно создать 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)

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

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

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

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

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

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

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

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

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

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

Если два хэша не совпадают, операция завершается ошибкой с кодом 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 в запросе на шифрование большого двоичного объекта с помощью ключа, предоставленного клиентом, могут быть указаны следующие заголовки. Шифрование с помощью ключа, предоставленного клиентом (и соответствующего набора заголовков), является необязательным.

Заголовок запроса Описание
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=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.

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

Этот заголовок возвращается, если Content-md5 заголовок отсутствует в запросе.
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 отсутствует в запросе, он отсутствует в ответе.

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

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

Авторизация

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

Важно!

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

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

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

Разрешения

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

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

Комментарии

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

В следующей таблице описаны максимальные допустимые размеры блоков и BLOB-объектов по версии службы.

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

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

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

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

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

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

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

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

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

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

Вызов Put Block не обновляет время последнего изменения существующего BLOB-объекта.

При вызове Put Block для страничного большого двоичного объекта возвращается ошибка.

Вызов Put Block архивного BLOB-объекта возвращает ошибку, а его hot вызов для blob-объекта или cool не изменяет уровень BLOB-объекта.

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

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

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

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

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

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

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