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

Пакет больших двоичных объектов

  • Статья

Эта Blob Batch операция позволяет внедрить несколько вызовов API в один HTTP-запрос. Этот API поддерживает два типа вложенных запросов: Задать уровень BLOB-объектов для блочных BLOB-объектов и Удалить BLOB-объект. Ответ, возвращаемый сервером для пакетного запроса, содержит результаты для каждого вложенного запроса в пакете. Пакетный запрос и ответ используют синтаксис спецификации OData пакетной обработки с изменениями семантики. Этот API доступен начиная с версии 2018-11-09.

Запрос

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

Метод Универсальный код ресурса (URI) запроса параметр "Версия HTTP"
POST https://myaccount.blob.core.windows.net/?comp=batch

https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch		 HTTP/1.1

Параметры универсального кода ресурса (URI)

В URI запроса можно указать следующие дополнительные параметры.

Параметр Описание
timeout Необязательный элемент. Параметр времени ожидания выражается в секундах с максимальным значением 120 секунд. Дополнительные сведения см. в разделе Настройка времени ожидания для операций с хранилищем BLOB-объектов.
restype Необязательно, версия 2020-04-08 и более поздние. Для параметра поддерживается restypecontainerтолько значение . Если указан этот параметр, универсальный код ресурса (URI) должен содержать имя контейнера. Все вложенные запросы должны быть ограничены тем же контейнером.

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

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

Заголовок запроса Описание
Authorization Обязательный. Указывает схему авторизации, имя учетной записи хранения и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
Date или x-ms-date Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
x-ms-version Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Эта версия будет использоваться для всех вложенных запросов. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
Content-Length Обязательный. Длина запроса.
Content-Type Обязательный. Значение этого заголовка должно быть multipart/mixedравно , с границей пакета. Пример значения заголовка: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252.
x-ms-client-request-id Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Хранилище BLOB-объектов Azure.

Текст запроса

Текст запроса для пакета BLOB-объектов содержит список всех вложенных запросов. Формат использует синтаксис спецификации OData пакета с изменениями семантики.

Текст запроса начинается с границы пакета, за которой следуют два обязательных заголовка: Content-Type заголовок со значением application/httpи Content-Transfer-Encoding заголовок со значением binary. За ним следует необязательный Content-ID заголовок со строковым значением для отслеживания каждого из вложенных запросов. Ответ содержит Content-ID заголовок для каждого соответствующего ответа вложенного запроса, используемого для отслеживания.

За этими заголовками запроса следует обязательная пустая строка, а затем определение для каждого вложенного запроса. Текст каждого вложенного запроса представляет собой полный HTTP-запрос с командой, URL-адресом, заголовками и текстом запроса. Обратите внимание на следующие предостережения.

  • Вложенные запросы не должны содержать x-ms-version header. Все вложенные запросы выполняются с версией пакетного запроса верхнего уровня.
  • URL-адрес вложенного запроса должен содержать только путь к URL-адресу (без узла).
  • Каждый пакетный запрос поддерживает не более 256 вложенных запросов.
  • Все вложенные запросы должны иметь один и тот же тип запроса.
  • Каждое вложенное расследование авторизоваться отдельно, с информацией, предоставленной в подзапросе.
  • Каждая строка в тексте запроса должна заканчиваться \r\n символами.

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

POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1 
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
x-ms-version: 2018-11-09 
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000 
Content-Length: 1569 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 0 

DELETE /container0/blob0 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 1 

DELETE /container1/blob1 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 2 

DELETE /container2/blob2 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--

Ответ

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

Текст ответа

Пакетный ответ — это multipart/mixed ответ, который содержит ответ для каждого вложенного запроса. Ответ фрагментирован. Каждый вложенный ответ начинается с заголовка Content-Type: application/http . Заголовок Content-ID следует за заголовком , если он был указан в запросе. За ним следует код состояния HTTP-ответа и заголовки ответа для каждого вложенного запроса.

Сведения о заголовках, возвращаемых каждым вложенным запросом, см. в документации по операциям Удаления BLOB-объекта и Задания уровня BLOB-объектов .

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

HTTP/1.1 202 Accepted 
Transfer-Encoding: chunked 
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000 
x-ms-version: 2018-11-09 

409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 0 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 1 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 2 

HTTP/1.1 404 The specified blob does not exist. 
x-ms-error-code: BlobNotFound 
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852 
x-ms-version: 2018-11-09 
Content-Length: 216 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?> 
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist. 
RequestId:778fdc83-801e-0000-62ff-0334671e2852 
Time:2018-06-14T16:46:54.6040685Z</Message></Error> 
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed-- 
0

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

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

Дополнительные сведения см. в разделе Состояние и коды ошибок.

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

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

Авторизация

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

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

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

Важно!

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

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

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

Запрос Blob Batch REST учитывается как одна транзакция, а каждый отдельный вложенный запрос также учитывается как одна транзакция. Дополнительные сведения о выставлении счетов за отдельные вложенные запросы см. в документации по операциям удаления BLOB-объектов и задания уровня BLOB-объектов .

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

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

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

Комментарии

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

  • В пакете поддерживаются вложенные запросы Set Blob Tier (для блочных BLOB-объектов) и Delete Blob.
  • Поддерживает только до 256 вложенных запросов в одном пакете. Размер текста пакетного запроса не может превышать 4 МБ.
  • Пустой пакетный запрос завершается ошибкой с кодом 400 (недопустимый запрос).
  • Нет никаких гарантий по порядку выполнения вложенных запросов пакета.
  • Выполнение вложенного запроса пакетной службы не является атомарным. Каждый вложенный запрос выполняется независимо.
  • Каждый вложенный запрос должен быть для ресурса в одной учетной записи хранения. Один пакетный запрос не поддерживает выполнение запросов из разных учетных записей хранения.
  • Вложенный текст запроса не поддерживается.
  • Если серверу не удается проанализировать текст запроса, весь пакет завершается ошибкой, и запрос не будет выполняться.
  • Обратите внимание, что SAS учетной записи является единственным типом подписанного URL-адреса, поддерживаемым Blob Batch, если пакет не использует restype=container.

Область действия всех вложенных запросов к определенному контейнеру

Начиная с REST версии 2020-04-08 API Blob Batch поддерживает определение области подзапросов в указанном контейнере. Если универсальный код ресурса (URI) запроса содержит имя контейнера и restype=container параметр , каждый вложенный запрос должен применяться к одному и тому же контейнеру. Если имя контейнера, указанное для вложенного запроса, не соответствует имени контейнера, указанному в универсальном коде ресурса (URI), служба возвращает код ошибки 400 (недопустимый запрос).

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

См. также раздел

Авторизация запросов к состоянию службы хранилища Azureи коды ошибокхранилища BLOB-объектов.Установка времени ожидания для операций с хранилищем BLOB-объектов