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

Поиск BLOB-объектов по тегам

  • Статья

Операция Find Blobs by Tags находит все большие двоичные объекты в учетной записи хранения, теги которых соответствуют выражению поиска.

Запрос

Запрос можно создать Find Blobs by Tags следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS. Замените myaccount именем своей учетной записи хранения.

URI запроса метода GET параметр "Версия HTTP"
https://myaccount.blob.core.windows.net?comp=blobs&where=<expression> HTTP/1.1

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

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

Параметр Описание
expression Обязательный. Фильтрует результирующий набор для включения только больших двоичных объектов, теги которых соответствуют указанному выражению.

Дополнительные сведения о том, как создать это выражение, см. в разделе Примечания.
marker Необязательный элемент. Строковое значение, определяющее часть результирующих наборов, возвращаемую при выполнении следующей операции. Операция возвращает значение маркера в теле ответа, если возвращенный результирующий набор не был завершен. Затем значение маркера можно использовать в последующем вызове для запроса следующего набора элементов.

Значение маркера непрозрачно для клиента.
maxresults Необязательный элемент. Задает максимальное количество возвращаемых BLOB-объектов. Если в запросе не указано maxresults или указано значение больше 5000, сервер возвращает до 5000 элементов. Если необходимо вернуть дополнительные результаты, служба возвращает маркер продолжения в элементе NextMarker response. В некоторых случаях служба может возвращать меньше результатов, чем maxresults указано. Служба также может возвращать маркер продолжения.

Установка для maxresults значения меньше нуля или равного нулю приводит к возвращению кода ошибки 400 (неправильный запрос).
timeout Необязательный элемент. Выражается в секундах. Дополнительные сведения см. в статье Установка времени ожидания для операций с хранилищем BLOB-объектов.

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

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

Заголовок запроса Описание
Authorization Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
Date или x-ms-date Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
x-ms-version Обязательный параметр для всех авторизованных запросов, но необязательный для анонимных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
x-ms-client-request-id Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером.

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

Нет.

Ответ

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

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

Успешная операция возвращает код состояния 200 (ОК).

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

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

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

Заголовок ответа Описание
Content-Type Указывает application/xml в качестве типа контента.
Content-Length Задает размер возвращаемого XML-документа в байтах.
x-ms-request-id Уникально идентифицирует выполненный запрос. Его можно использовать для устранения неполадок с запросом. Дополнительные сведения см. в статье Устранение неполадок с операциями API.
x-ms-version Указывает версию Хранилище BLOB-объектов Azure, которая использовалась для выполнения запроса.
Date Значение даты и времени в формате UTC, указывающее время отправки ответа службой.
x-ms-client-request-id Может использоваться для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению заголовка x-ms-client-request-id , если он присутствует в запросе и содержит не более 1024 видимых символов ASCII. Если заголовок x-ms-client-request-id отсутствует в запросе, этот заголовок не будет присутствовать в ответе.

Текст ответа

В версии 2020-04-08 и более поздних версиях соответствующие теги большого двоичного объекта инкапсулируются в элементе Tags . Текст ответа имеет следующий формат:

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=http://myaccount.blob.core.windows.net/>  
  <Where>string-value</Where>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</Name>  
      <ContainerName>container-name</ContainerName>  
      <Tags>
        <TagSet>
          <Tag>
            <Key>matching-tag-name1</Key>
            <Value>matching-tag-value1</Value>
          </Tag>
          <Tag>
            <Key>matching-tag-name2</Key>
            <Value>matching-tag-value2</Value>
          </Tag>
        </TagSet>
      </Tags> 
    </Blob>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

Текст ответа представляет собой XML-документ с правильным форматом UTF-8.

Авторизация

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

Важно!

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

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

Комментарии

Эта Find Blobs by Tags операция поддерживается в REST API версии 2019-12-12 и более поздних версиях.

Для учетных записей с включенным иерархическим пространством имен операция не поддерживается, Find Blobs by Tags так как теги больших двоичных объектов не поддерживаются для учетных записей иерархического пространства имен.

Вторичный индекс, который использует, Find Blobs by Tags в конечном итоге будет согласован. Обновления к тегам BLOB-объектов с помощью Set Blob Tags могут быть не сразу видимы для Find Blobs by Tags операций.

Создание выражения поиска

Параметр where URI находит большие двоичные объекты в учетной записи хранения, теги которых соответствуют выражению. Выражение должно иметь значение , true чтобы большой двоичный объект возвращался в результирующем наборе.

Служба хранилища поддерживает подмножество грамматики предложения ANSI SQL WHERE для значения where=<expression> параметра запроса. Служба хранилища поддерживает следующие операторы:

Оператор Описание Пример
= Равно &where=Status = 'In Progress'
> Больше чем &where=LastModified > '2018-06-18 20:51:26Z'
>= Больше или равно &where=Priority >= '05'
< Меньше чем &where=Age < '032'
<= Меньше или равно &where=Reviewer <= 'Smith'
AND Логическое И &where=Name > 'C' AND Name < 'D'
&where=Age > '032' AND Age < '100'
@container Указание контейнера &where=@container='mycontainer' AND Name = 'C'

Примечание

Значение where параметра URI должно быть правильно закодировано (включая пробелы и операторы). В предыдущих примерах это не указано для удобочитаемости.

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

Если имена тегов являются обычными идентификаторами SQL, они могут присутствовать без экранирования. Если они содержат специальные символы, они должны быть разделены двойными кавычками (например, "TagName" = TagValue). Рекомендуется всегда заключать имена тегов в двойные кавычки.

Служба хранилища отклоняет любой запрос, содержащий недопустимое выражение с кодом ошибки 400 (недопустимый запрос).

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

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

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

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

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

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