Добавить блок из URL

Статья
2025-05-11

Операция Append Block From URL фиксирует новый блок данных в конце существующего добавочного BLOB-объекта.

Операция Append Block From URL разрешена только в том случае, если большой двоичный объект был создан с x-ms-blob-type установленным значением .AppendBlob Append Block From URL поддерживается только на версии 2018-11-09 или более поздней.

Просьба

Можно создать запрос Append Block From URL следующим образом. Рекомендуется использовать протокол HTTPS. Замените myaccount именем учетной записи хранения.

URI запроса метода PUT	Версия HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock`	HTTP/1.1

При отправке запроса к эмулируемой службе хранилища укажите имя узла эмулятора и порт хранилища BLOB-объектов Azure как 127.0.0.1:10000, а затем имя эмулируемой учетной записи хранения.

URI запроса метода PUT	Версия HTTP
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock`	HTTP/1.1

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

Параметры URI

Параметр	Описание
`timeout`	Необязательно. Параметр времени ожидания выражается в секундах. Дополнительные сведения см. в статье Настройка времени ожидания для операций с хранилищем BLOB-объектов.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательное. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в авторизации запросов к службе хранилища Azure.
`Date` или `x-ms-date`	Обязательное. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями служб хранилища Azure.
`Content-Length`	Обязательное. Указывает количество байтов, передаваемых в тексте запроса. Значение этого заголовка должно быть равно нулю. Если длина не равна нулю, операция завершится ошибкой с кодом ошибки 400 (Bad Request).
`x-ms-copy-source:name`	Обязательное. Указывает URL-адрес исходного большого двоичного объекта. Значением может быть URL-адрес длиной до 2 КБ, указывающий большой двоичный объект. Значение должно быть закодировано в URL-адресе, как оно будет отображаться в URI запроса. Исходный BLOB-объект должен быть либо общедоступным, либо авторизованным с помощью подписанного 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 ID поддерживается только канал передачи схемы. Этот заголовок поддерживается в версии 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` заголовка 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-blob-condition-maxsize`	Необязательный условный заголовок. Максимально допустимая длина в байтах для добавляемого большого двоичного объекта. Если в результате `Append Block From URL` операции большой двоичный объект превышает это ограничение или если размер большого двоичного объекта уже превышает значение, указанное в этом заголовке, запрос завершается ошибкой 412 (сбой предварительного условия).
`x-ms-blob-condition-appendpos`	Необязательный условный заголовок, используемый только для `Append Block from URL` операции. Число, указывающее смещение байтов для сравнения. `Append Block from URL` успешно выполняется только в том случае, если позиция добавления равна этому числу. Если это не так, запрос завершается ошибкой 412 (Precondition Failed).
`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 и выше.

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

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

Начиная с версии 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=appendblock  HTTP/1.1  

Request Headers:  
x-ms-version: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
If-Match: "0x8CB172A360EC34B"

Ответ

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

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

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

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

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

Заголовок ответа	Описание
`Etag`	Содержит `ETag` значение в кавычках. Клиент использует это значение для выполнения условных `PUT` операций с помощью `If-Match` заголовка запроса.
`Last-Modified`	Дата и время последнего изменения большого двоичного объекта. Формат даты следует RFC 1123. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Любая операция записи большого двоичного объекта (включая обновление метаданных или свойств большого двоичного объекта) изменяет время последнего изменения большого двоичного объекта.
`Content-MD5`	Этот заголовок возвращается, чтобы клиент смог проверить целостность содержимого сообщения. Хранилище BLOB-объектов вычисляет значение этого заголовка. Это не обязательно то же значение, которое указано в заголовках запроса. Для версии 2019-02-02 или более поздней этот заголовок возвращается только в том случае, если запрос содержит этот заголовок.
`x-ms-content-crc64`	Для версии 2019-02-02 или более поздней. Этот заголовок возвращается, чтобы клиент смог проверить целостность содержимого сообщения. Хранилище BLOB-объектов вычисляет значение этого заголовка. Это не обязательно то же значение, которое указано в заголовках запроса. Этот заголовок возвращается, если он `x-ms-source-content-md5` отсутствует в запросе.
`x-ms-request-id`	Этот заголовок однозначно идентифицирует выполненный запрос и может использоваться для устранения неполадок запроса.
`x-ms-version`	Указывает версию хранилища BLOB-объектов, используемую для выполнения запроса. Этот заголовок возвращается для запросов к версии 2009-09-19 и более поздних версий.
`Date`	Значение даты и времени в формате UTC, созданное службой, указывающее время, в течение которого был инициирован ответ.
`x-ms-blob-append-offset`	Этот заголовок ответа возвращается только для операций добавления. Он возвращает смещение, по которому блок был зафиксирован, в байтах.
`x-ms-blob-committed-block-count`	Число зафиксированных блоков, присутствующих в большом двоичном объекте. Вы можете использовать это для управления тем, сколько еще добавлений можно сделать.
`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 или более поздняя. Этот заголовок возвращается, если в запросе использовалась область шифрования. После этого клиент может убедиться, что содержимое запроса успешно зашифровано с помощью области шифрования.

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

Response Status:  
HTTP/1.1 201 Created  

Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000

Авторизация

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

Сведения о полномочиях, приведенные в этом разделе, относятся к месту назначения копирования. Дополнительные сведения об авторизации источника копирования см. в деталях заголовка x-ms-copy-sourceзапроса.

Это важно

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

Действие Azure RBAC:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action или Microsoft.Storage/storageAccounts/blobServices/containers/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.

Для вызова Append Block From URL операции с помощью маркера SAS, делегированного контейнеру или ресурсу BLOB-объекта, требуется разрешение Add (a) или Write (w) в рамках токена SAS делегирования пользователя:

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

Сервис SAS

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

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

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

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

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

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

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

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

Замечания

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

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

Версия службы	Максимальный размер блока (через `Append Block From URL`)	Максимальный размер большого двоичного объекта
Версия 2022-11-02 и более поздние версии	100 МиБ (предварительная версия)	Приблизительно 4,75 ТиБ (100 МиБ × 50 000 блоков)
Версии до 2022-11-02	4 МиБ	Приблизительно 195 гибибайт (ГиБ) (4 МиБ × 50 000 блоков)

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

Append Block From URL выполняется успешно только в том случае, если большой двоичный объект уже существует.

Большие двоичные объекты, отправленные с помощью Append Block From URL функции Не предоставлять идентификаторы блокировок, поэтому вы не можете вызвать Get Block List для добавляемого большого двоичного объекта. Это приводит к ошибке.

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

x-ms-blob-condition-appendpos: Вы можете установить для этого заголовка смещение в байтах, при котором клиент ожидает добавить блок. Запрос выполняется успешно только в том случае, если текущее смещение совпадает с значением, указанным клиентом. В противном случае запрос завершается ошибкой с кодом 412 (Precondition Failed).

Клиенты, использующие один модуль записи, могут использовать этот заголовок, чтобы определить, была ли операция выполнена успешно Append Block From URL , несмотря на сбой сети.
x-ms-blob-condition-maxsizeКлиенты могут использовать этот заголовок, чтобы гарантировать, что операции добавления не увеличивают размер большого двоичного объекта сверх ожидаемого максимального размера в байтах. Если условие не выполняется, запрос завершается ошибкой с кодом ошибки 412 (Precondition Failed).

Если вы попытаетесь загрузить блок, размер которого больше разрешенного, сервис вернет код ошибки HTTP 413 (Request Entity Too Large). Сервис также возвращает дополнительную информацию об ошибке в ответе, в том числе максимально допустимый размер блока в байтах. Если вы попытаетесь загрузить более 50 000 блоков, сервис вернет код ошибки 409 (Конфликт).

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

При вызове Append Block From URL существующего блочного или страничного BLOB-объекта служба возвращает код ошибки 409 (конфликт). Если вы вызываете Append Block From URL несуществующий большой двоичный объект, служба возвращает код ошибки 404 (не найдено).

Избегайте дублирования или задержки добавления

В сценарии с одним модулем записи клиент может избежать дублирования добавлений или задержки записи, используя x-ms-blob-condition-appendpos условный заголовок для проверки текущего смещения. Клиент также может избежать дубликатов или задержек, проверив условно ETag , используя If-Match.

В сценарии с несколькими модулями записи каждый клиент может использовать условные заголовки. Это может быть не лучшим для производительности. Для обеспечения максимальной пропускной способности параллельных добавлений приложения должны обрабатывать избыточные добавления и отложенные добавления на уровне приложения. Например, приложения могут добавлять эпохи или порядковые номера в добавляемые данные.

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

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

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

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

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