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

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

Операция Append Block разрешена только в том случае, если blob был создан с 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

Когда вы делаете запрос к эмулируемому сервису хранения, укажите имя хоста эмулятора и порт Azure Blob Storage как 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

Параметр Description
timeout Необязательно. Параметр timeout выражается в секундах. Для получения дополнительной информации см. раздел «Установка таймаутов для операций Azure Blob Storage».

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

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

Заголовок запроса Description
Authorization Обязательное. Указывает схему авторизации, имя учетной записи и подпись. См. раздел «Авторизировать запросы на Azure Storage » для получения дополнительной информации.
Date или x-ms-date Обязательное. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
x-ms-version Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
Content-Length Обязательное. Длина содержания блока в байтах. Размер блока должен быть меньше или равен размеру 100 МиБ (предварительный просмотр) для версии 2022-11-02 и более поздней. См. раздел Примечания для ограничений в старых версиях.

Если длина не указана, операция не выполняется с кодом статуса 411 (Требуется длина).
Content-MD5 Необязательно. MD5-хэш содержимого блока. Этот хэш используется для проверки целостности блока во время транспортировки. Когда этот заголовок задаётся, служба хранения сравнивает хэш пришедшего содержимого с этим значением заголовка.

Обратите внимание, что этот хэш MD5 не хранится вместе с blob.

Если два хэша не совпадают, операция провалится с ошибкой 400 (Плохой запрос).
x-ms-content-crc64 Необязательно. Хэш CRC64 содержимого блока приложений. Этот хеш используется для проверки целостности блока приложения во время транспортировки. Когда этот заголовок задаётся, служба хранения сравнивает хэш пришедшего содержимого с этим значением заголовка.

Обратите внимание, что этот хэш CRC64 не хранится вместе с blob.

Если два хэша не совпадают, операция провалится с ошибкой 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. Если Append Block операция приводит к тому, что blob превышает этот предел, или если размер blob уже превышает значение, указанное в этом заголовке, запрос проваливается с кодом ошибки 412 (предварительное условие не выполнено).
x-ms-blob-condition-appendpos Опциональный условный заголовок, используемый только для Append Block операции. Число указывает смещение на байт для сравнения. Append Block успешен только если позиция прибавки равна этому числу. Если нет, запрос не проходит с кодом ошибки 412 (предварительное условие не выполнено).

Эта операция поддерживает использование дополнительных условных заголовков, чтобы обеспечить успех API только при выполнении заданного условия. Для получения дополнительной информации см. раздел «Указание условных заголовков для операций Azure Blob Storage».

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

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

Заголовок запроса Description
x-ms-encryption-key Обязательное. Ключ шифрования AES-256, закодированный по Base64.
x-ms-encryption-key-sha256 Обязательное. Хэш SHA256, закодированный в Base64, ключ шифрования.
x-ms-encryption-algorithm: AES256 Обязательное. Задаёт алгоритм для шифрования. Значение этого заголовка должно быть AES256.

Заголовки запросов (структурированное тело)

По состоянию на версию 2025-01-05 в запросе могут быть указаны следующие заголовки для использования формата структурированного тела.

Заголовок запроса Description
Content-Length Обязательное. Должна быть длина закодированного запроса (а не только длина содержимого блока).

Если значение заголовка не совпадает с ожидаемой длиной закодированного запроса, операция неудачна с кодом ошибки 400 (Плохой запрос).
x-ms-structured-body Обязательное. Необходимо включить, если формат сообщения структурирован. Значение этого заголовка содержит версию схемы сообщений и свойства.

В настоящее время единственное поддерживаемое значение — XSM/1.0; properties=crc64, указывающее, что запрос использует сегменты контрольной суммы crc64 в закодированном сообщении. Если значение не совпадает с этим, операция заканчивается с кодом ошибки 400 (Плохой запрос). Запрос также не будет выполнен, если содержание, предоставленное в запросе, не совпадает с предоставленной контрольной суммой для данного сегмента.
x-ms-structured-content-length Обязательное. Необходимо включить, если формат сообщения структурирован. Значение этого заголовка — это длина содержимого блока и всегда будет меньше Content-Length значения заголовка из-за кодирования сообщений.

Если значение заголовка не совпадает с длиной блока, указанного в запросе, операция заканчивается с ошибкой 400 (Плохой запрос).

Основное содержание запроса

Тело запроса содержит содержание блока.

Пример запроса

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.

Заголовок ответа Description
ETag Значение ETag содержит в кавычках. Клиент может использовать это значение для выполнения условных PUT операций, используя If-Match заголовок запроса.
Last-Modified Дата и время последней модификации слепка. Формат даты соответствует RFC 1123. Для получения дополнительной информации см. Представление значений даты-времени в заголовках.

Любая операция записи на blob (включая обновления метаданных или свойств blob) меняет время последнего изменения blob-а.
Content-MD5 Этот заголовок возвращается, чтобы клиент смог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется Blob Storage. Это не обязательно то же значение, что указано в заголовках запроса. Для версий 2019-02-02 и более поздние этот заголовок возвращается только тогда, когда запрос содержит этот заголовок.
x-ms-content-crc64 Для версий 2019-02-02 и позже этот заголовок возвращается, чтобы клиент мог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется Blob Storage. Это не обязательно то же значение, что указано в заголовках запроса.

Этот заголовок возвращается, когда он 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 или позже. Этот заголовок возвращается, если запрос использовал область шифрования. Затем клиент может убедиться, что содержимое запроса успешно зашифровано, используя область шифрования.
x-ms-client-request-id Этот заголовок можно использовать для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению x-ms-client-request-id самого заголовка, если оно присутствует в запросе. Значение не более 1024 видимых символов ASCII. Если заголовок x-ms-client-request-id отсутствует в запросе, он отсутствует в ответе.
x-ms-structured-body Возвращается, если запрос был обработан как структурированный запрос. Значение этого заголовка равно значению, отправленному в запросе, которое в настоящее время должно быть XSM/1.0; properties=crc64.

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

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

Authorization

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

Это важно

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

Permissions

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

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

Замечания

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

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

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

Append Block Это успешно только если Blob уже существует.

Blobs, загруженные с помощью Append Block использования, не открывают блоковые идентификаторы. Нельзя вызвать Get Block List против blob с добавлением. Это приводит к ошибке.

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

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

    Клиенты, использующие один редактор, могут использовать этот заголовок для определения успешности Append Block операции несмотря на сбой сети.

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

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

Если у blob есть активный договор аренды, клиент должен указать действительный идентификатор аренды в запросе, чтобы записать блок в blob. Если клиент не указывает идентификатор аренды или указывает недействительный идентификатор аренды, Blob Storage возвращает код ошибки 412 (предварительное условие не выполнено). Если клиент указывает идентификатор аренды, но у blob нет активного аренды, Blob Storage также возвращает код ошибки 412.

Если вы вызываете Append Block существующий блок или блоб страницы, сервис возвращает ошибку конфликта. Если вы вызываете Append Block несуществующий blob, сервис также возвращает ошибку.

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

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

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

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

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

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

Append Blocks не поддерживают уровень уровня объекта, но выводят свой уровень доступа по умолчанию в настройках доступа аккаунта и выставляются соответственно. Чтобы узнать больше о настройках стандартного уровня учетной записи, смотрите раздел Access tiers for blob data — Azure Storage.

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

  • Last updated on