Поставить блокировку из URL

2025-05-11

Операция Put Block From URL создает новую блокировку, которая должна быть зафиксирована как часть большого двоичного объекта, содержимое которого считывается из URL-адреса. Этот API доступен с версии 2018-03-28.

Просьба

Можно создать запрос Put Block From URL следующим образом. Рекомендуется использовать ПРОТОКОЛ 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. Для `Put Block From URL`, версия должна быть 2018-03-28 или более поздней.
`Content-Length`	Обязательное. Указывает количество байтов, передаваемых в тексте запроса. Значение этого заголовка должно иметь значение 0. Если длина не равна 0, операция завершается ошибкой с кодом состояния 400 (недопустимый запрос).
`x-ms-copy-source:name`	Обязательное. Указывает URL-адрес исходного большого двоичного объекта. Значением может быть URL-адрес длиной до 2 кибибайт (КиБ), указывающий большой двоичный объект. Значение должно быть закодировано в URL-адресе, как оно будет отображаться в URI запроса. Исходный большой двоичный объект должен быть общедоступным или авторизованным с помощью подписанного URL-адреса. Если исходный большой двоичный объект является общедоступным, для выполнения операции не требуется авторизация. Ниже приведены некоторые примеры URL-адресов исходного объекта: - `https://myaccount.blob.core.windows.net/mycontainer/myblob` - `https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>` - `https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>`
`x-ms-copy-source-authorization: <scheme> <signature>`	Необязательно. Указывает схему авторизации и подпись источника копирования. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure. примечание. Для Microsoft Entra поддерживается только схема носителя. Примечание. Если исходный объект является общедоступным или исходный объект находится в учетной записи хранения, и вы используете маркер SAS, передаваемый в `x-ms-copy-source:name`, этот заголовок не нужен. Этот заголовок поддерживается в версиях 2020-10-02 и более поздних версиях.
`x-ms-source-range`	Необязательно. Отправляет только байты большого двоичного объекта в исходном URL-адресе в указанном диапазоне. Если этот заголовок не указан, все содержимое исходного большого двоичного объекта передается в виде одного блока. Дополнительные сведения см. в статье Указание заголовка диапазона для операций службы BLOB-объектов.
`x-ms-source-content-md5`	Необязательно. MD5-хеш содержимого блока из URI. Этот хэш используется для проверки целостности блока во время транспортировки данных из URI. Когда этот заголовок указан, служба хранилища сравнивает хэш содержимого, поступившего из источника копирования, со значением этого заголовка. Примечание: Этот MD5-хэш не хранится вместе с большим двоичным объектом. Если два хэша не соответствуют, операция завершается ошибкой с кодом 400 (недопустимый запрос).
`x-ms-source-content-crc64`	Необязательно. CRC64-хэш содержимого блока из URI. Этот хэш используется для проверки целостности блока во время транспортировки данных из URI. Когда этот заголовок указан, служба хранилища сравнивает хэш содержимого, поступившего из источника копирования, со значением этого заголовка. Примечание: Этот хэш CRC64 не хранится вместе с большим двоичным объектом. Если два хэша не соответствуют, операция завершается ошибкой с кодом 400 (недопустимый запрос). Если присутствуют оба `x-ms-source-content-md5` заголовка and `x-ms-source-content-crc64` , запрос завершается ошибкой со значением 400 (Bad Request). Этот заголовок поддерживается в версиях 2019-02-02 и более поздних.
`x-ms-encryption-scope`	Необязательно. Указывает область шифрования, используемую для шифрования исходного содержимого. Этот заголовок поддерживается в версиях 2019-02-02 и более поздних.
`x-ms-lease-id:<ID>`	Требуется, если большой двоичный объект имеет действующую аренду. Чтобы выполнить эту операцию в большом двоичном объекте с активной арендой, укажите допустимый идентификатор аренды для этого заголовка.
`x-ms-client-request-id`	Необязательно. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-kibibyte (KiB), записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitorхранилища BLOB-объектов Azure.
`x-ms-file-request-intent`	Обязательно, если `x-ms-copy-source` заголовок является URL-адресом файла Azure и `x-ms-copy-source-authorization` в заголовке указан маркер OAuth. Допустимое значение равно `backup`. Этот заголовок указывает, что `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` или `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` следует предоставить, если они включены в политику RBAC, назначенную удостоверению, авторизованному с помощью заголовка `x-ms-copy-source-authorization`. Доступно для версии 2025-07-05 и выше.

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

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

Заголовок запроса	Описание
`x-ms-encryption-key`	Обязательное. Ключ шифрования AES-256 с кодировкой Base64.
`x-ms-encryption-key-sha256`	Обязательное. Хэш шифрования в кодировке Base64 SHA256 ключа шифрования.
`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: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

Ответ

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

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

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

Дополнительные сведения о кодах состояния см. в коды состояния и коды ошибок.

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

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

Заголовок ответа	Описание
`Content-MD5`	Возвращается, чтобы клиент смог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется хранилищем BLOB-объектов. Это не обязательно совпадает со значением, указанным в заголовках запроса. Для версий 2019-02-02 и более поздних этот заголовок возвращается только в том случае, если запрос содержит этот заголовок.
`x-ms-content-crc64`	Для версий 2019-02-02 и выше. Возвращается, чтобы клиент смог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется хранилищем BLOB-объектов. Это не обязательно то же самое, что и значение, указанное в заголовках запроса. Возвращается, если `x-ms-source-content-md5` заголовок отсутствует в запросе.
`x-ms-request-id`	Уникально идентифицирует выполненный запрос, и его можно использовать для устранения неполадок запроса. Дополнительные сведения см. в статье Устранение неполадок с операциями API.
`x-ms-version`	Версия хранилища BLOB-объектов, используемая для выполнения запроса.
`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: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Авторизация

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

Это важно

Корпорация Майкрософт рекомендует использовать идентификатор 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.

Разрешения

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

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

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

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

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

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

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

Делегирование пользователей с помощью SAS

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

Вызов операции Put Block From URL с помощью маркера SAS, делегированного контейнеру или ресурсу БОЛЬШОго двоичного объекта, требует разрешения записи (w) в рамках маркера SAS делегирования пользователей.

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

Сервис SAS

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

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

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

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

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

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

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

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

Замечания

Put Block From URL Отправляет блок для последующего включения в блочный BLOB. Блочный BLOB-объект может содержать не более 50 000 блоков. Каждый блок может быть разного размера. Максимальный размер загружаемого Put Block From URL блока составляет 100 мебибайт (МиБ). Чтобы загрузить блоки большего размера (до 4 000 МиБ), см. раздел Поставить блок.

В версии 2020-10-02 и более поздних версиях авторизация Microsoft Entra поддерживается для источника операции копирования.

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

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

Версия службы	Максимальный размер блока (через `Put Block From URL`)	Максимальный размер большого двоичного объекта (через `Put Block List`)	Максимальный размер большого двоичного объекта за счет одной операции записи (через `Put Blob From URL`)
Версия 2020-04-08 и более поздние версии	4 000 МиБ	Приблизительно 190,7 тебибайт (ТиБ) (4 000 МиБ × 50 000 блоков)	5 000 МиБ
Версии до 2020-04-08	100 МиБ	Приблизительно 4,75 ТиБ (100 МиБ × 50 000 блоков)	256 МиБ

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

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

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

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

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

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

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

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

При вызове Put Block From URL страничного BLOB-объекта возвращается ошибка.

При вызове Put Block From URL архивного большого двоичного объекта возвращается ошибка, а при его вызове hotcool большого двоичного объекта или уровень большого двоичного объекта не изменяется.

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

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

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

¹Целевая учетная запись взимается за одну транзакцию, чтобы инициировать запись.
²исходная учетная запись вызывает одну транзакцию для каждого запроса на чтение исходного объекта.

Кроме того, если исходные и целевые учетные записи находятся в разных регионах (например, на севере США и юге США), пропускная способность, используемая для передачи запроса, взимается в исходную учетную запись хранения в качестве исходящего трафика. Исходящие данные между учетными записями в одном регионе бесплатны.

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