Размещение блока из URL-адреса

Статья
09/22/2022
Чтение занимает 9 мин

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

Имитированный URI службы хранилища

При построении запроса к эмулированной службе хранилища укажите имя узла эмулятора и порт службы 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

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

Параметры 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. Для URL-адреса put Block From версия должна быть 2018-03-28 или более поздней.
`Content-Length`	Обязательный. Указывает число байтов, передаваемых в тексте запроса. Значение этого заголовка должно быть равно нулю. Если длина не равна нулю, операция завершится ошибкой с кодом состояния 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". Для Azure Active Directory поддерживается только носитель схемы. Этот заголовок поддерживается в версиях 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` заголовка `x-ms-source-content-crc64` присутствуют, запрос завершится ошибкой 400 (недопустимый запрос). Этот заголовок поддерживается в версиях 2019-02-02 или более поздней версии.
`x-ms-encryption-scope`	Необязательный элемент. Указывает область шифрования, используемую для шифрования исходного содержимого. Этот заголовок поддерживается в версиях 2019-02-02 или более поздней версии.
`x-ms-lease-id:<ID>`	Требуется, если у большого двоичного объекта имеется активная аренда. Для выполнения этой операции в большом двоичном объекте с активной арендой укажите допустимый идентификатор аренды для этого заголовка.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением на 1 КиБ, которое записывается в журналы аналитики при включении ведения журнала аналитики хранилища. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления операций на стороне клиента с запросами, которые получает сервер. Дополнительные сведения см. в статье "Сведения о Аналитика Службы хранилища ведения журнала и ведения журнала 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: 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

Авторизация

Эта операция может быть отменена владельцем учетной записи и любым обладателем подписи общего доступа с разрешениями на запись для этого большого двоичного объекта или контейнера.

Remarks

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

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

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

В таблице ниже приведены сведения о максимальном размере блоков и BLOB-объектов, разрешенных определенными версиями службы.

Версия службы	Максимальный размер блока (с помощью put Block from URL)	Максимальный размер BLOB-объекта (при выполнении Put Block List)	Максимальный размер большого двоичного объекта с помощью одной операции записи (с помощью put BLOB-объекта из URL-адреса)
Версия 2020-04-08 и более поздних версий	4000 МиБ	Около 190,7 ТиБ (4000 МиБ X 50 000 блоков)	5000 МиБ (предварительная версия)
Версии до 2020-04-08	100 МиБ	Около 4,75 ТиБ (100 МиБ X 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 вызовом для фиксации нового или обновленного большого двоичного объекта все вызовы get BLOB возвращают содержимое большого двоичного объекта без включения незафиксированного блока.

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

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

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

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

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

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

Вызов Put Block From URL архивного большого двоичного объекта вернет ошибку, и в Hot/Cool большом двоичном объекте не изменяется уровень BLOB-объектов.