Добавление блока

Статья
02/03/2024

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

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

Запрос

Запрос можно создать Append Block следующим образом. Рекомендуется использовать протокол 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`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для Хранилище BLOB-объектов Azure операций.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure .
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`Content-Length`	Обязательный. Длина содержимого блокировки в байтах. Размер блока должен быть меньше или равен 100 МиБ (предварительная версия) для версии 2022-11-02 и более поздних версий. Ограничения в более ранних версиях см. в разделе Примечания . Если длина не указана, операция завершается ошибкой с кодом состояния 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.
`x-ms-blob-condition-maxsize`	Необязательный условный заголовок. Указывает максимальную длину в байтах, разрешенную для добавочного BLOB-объекта. `Append Block` Если операция приводит к тому, что большой двоичный объект превышает это ограничение или размер большого двоичного объекта уже больше значения, указанного в этом заголовке, запрос завершается ошибкой с кодом 412 (сбой условия).
`x-ms-blob-condition-appendpos`	Необязательный условный заголовок, используемый `Append Block` только для операции. Число указывает смещение байтов для сравнения. `Append Block` Выполняется успешно, только если позиция добавления равна этому числу. Если это не так, запрос завершается ошибкой с кодом 412 (сбой предварительного условия).

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

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

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

Заголовок запроса	Описание
`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=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
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-объектов. Это не обязательно то же значение, указанное в заголовках запроса. Этот заголовок возвращается, если заголовок `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`	Версия 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: <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 как описано ниже.

Важно!

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

Служба хранилища 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 пользователю, группе, управляемому удостоверению или субъекту-службе для вызова Append Block операции, а также встроенная роль 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.

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

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

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

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

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

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

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

SAS для службы

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

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

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

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

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

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

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

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

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

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

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

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

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

Blob-объекты, отправленные с помощью Append Block , не предоставляют блочные идентификаторы. Вы не можете вызвать get block list для добавочного BLOB-объекта. Это приведет к ошибке.

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

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

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

При попытке отправить блок, превышающий допустимый размер, служба возвращает код ошибки 413 (Слишком большой объект запроса). Кроме того, служба также вернет в ответе дополнительные сведения об ошибке, в том числе максимально допустимый размер блокировки в байтах. При попытке отправить более 50 000 блоков служба возвращает код ошибки 409 (конфликт).

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

При вызове Append Block существующего блочного BLOB-объекта или страничного BLOB-объекта служба возвращает ошибку конфликта. При вызове Append Block для несуществующего BLOB-объекта служба также возвращает ошибку.

Предотвращение повторяющихся или отложенных добавлений

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

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

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

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

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

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

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

Поделиться через