Вставка блока из URL-адреса

Статья
02/12/2024

Операция 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`версия должна быть 28.03.2018 или более поздней.
`Content-Length`	Обязательный. Указывает число байтов, передаваемых в тексте запроса. Значение этого заголовка должно быть равно 0. Если длина не равна 0, операция завершается ошибкой с кодом состояния 400 (недопустимый запрос).
`x-ms-copy-source:name`	Обязательный. Указывает URL-адрес исходного BLOB-объекта. Значением может быть URL-адрес длиной до 2 кибибайт (КиБ), указывающий большой двоичный объект. Значение должно быть закодировано в URL-адресе, так как оно будет отображаться в URI запроса. Исходный BLOB-объект должен быть общедоступным или авторизованным с помощью подписанного URL-адреса. Если исходный BLOB-объект является общедоступным, для выполнения операции авторизация не требуется. Ниже приведены некоторые примеры 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-объекта передается в виде одного блока. Дополнительные сведения см . в разделе Указание заголовка диапазона для операций службы 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 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Хранилище 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: 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`	Версия 11.12.2015 и более поздняя. Значение этого заголовка устанавливается в , `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 как описано ниже.

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

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

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

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

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

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

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

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

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

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

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

SAS для службы

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

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

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

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

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

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

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

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

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

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

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

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

Блок, успешно переданный с 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 From URL объекту или Put Block List в них. Если для большого двоичного объекта вызывается метод Put BLOB-объект , все незафиксированные блоки собираются мусором.

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

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

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

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

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

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

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

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

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

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

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