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

Добавление блока из URL-адреса

  • Статья

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

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

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

Начиная с версии 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: 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 Дата и время последнего изменения BLOB-объекта. Дата в формате согласно 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 Версия 11.12.2015 или более поздняя. Значение этого заголовка устанавливается в , 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 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 From URL операции, а также встроенная роль Azure RBAC с минимальными привилегиями, которая включает это действие.

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

Комментарии

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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