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

Статья
03/16/2023

Операция 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-объектов.

Параметр	Описание
`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 операцию, как описано ниже.

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

Действие Azure RBAC:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Встроенная роль с минимальными привилегиями:Участник данных BLOB-объектов хранилища

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

Подписанный URL-адрес (SAS) обеспечивает безопасный делегированный доступ к ресурсам в учетной записи хранения. С помощью SAS вы можете детально контролировать, как клиент может получить доступ к данным. Вы можете указать, к какому ресурсу может обращаться клиент, какие разрешения у него есть для этих ресурсов, а также срок действия SAS.

Операция Put Block поддерживает три типа подписанных URL-адресов: SAS делегирования пользователей, SAS службы и SAS учетной записи.

Для обеспечения безопасности рекомендуется использовать Microsoft Entra учетные данные, а не ключ учетной записи хранения, который может быть проще скомпрометирован. Если для разработки приложения требуются подписанные URL-адреса, по возможности используйте учетные данные Microsoft Entra, чтобы создать SAS для делегирования пользователей.

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

SAS для делегирования пользователей

SAS для делегирования пользователей защищен с помощью учетных данных Microsoft Entra, а также разрешений, указанных для SAS.

Put Block Для вызова операции с помощью маркера SAS, делегированного контейнеру или ресурсу BLOB-объекта, требуется разрешение на запись (w) в составе маркера SAS делегирования пользователя.

Дополнительные сведения о SAS для делегирования пользователей см. в статье Создание SAS для делегирования пользователей.

SAS для службы

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

Put Block Для вызова операции с использованием маркера SAS, делегированного контейнеру или ресурсу BLOB-объекта, требуется разрешение на запись (w) в составе маркера SAS службы.

Дополнительные сведения о SAS службы см. в статье Создание SAS службы.

SAS для учетной записи

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

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

Операция	Подписанная служба	Подписанный тип ресурса	Подписанное разрешение
Put Block (Вставка блокировки)	Большой двоичный объект (b)	Объект (o)	Запись (w)

Дополнительные сведения о SAS учетной записи см. в статье Создание SAS учетной записи.

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

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

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

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

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

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