Запрос содержимого BLOB-объекта

Статья
06/14/2023

Операция Query Blob Contents применяет простую инструкцию язык SQL (SQL) к содержимому большого двоичного объекта и возвращает только запрашиваемое подмножество данных. Можно также вызвать для Query Blob Contents запроса содержимого версии или snapshot.

Запрос

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

URI запроса метода POST	параметр "Версия HTTP"
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=query&versionid=<DateTime>`	HTTP/1.0 HTTP/1.1

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

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

Параметр	Описание
`snapshot`	Необязательный элемент. Параметр snapshot является непрозрачным значением`DateTime`. Если он присутствует, он указывает snapshot большого двоичного объекта для запроса. Дополнительные сведения о работе с моментальными снимками BLOB-объектов см. в статье Создание snapshot большого двоичного объекта.
`versionid`	Необязательно, версия 2019-12-12 и более поздние. Параметр `versionid` является непрозрачным значением `DateTime` . При наличии он указывает версию извлекаемого большого двоичного объекта.
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в статье Установка времени ожидания для операций с хранилищем BLOB-объектов.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему проверки подлинности, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Обязательно для всех запросов с проверкой подлинности, необязательно для анонимных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`Content-Type`	Обязательный. Значение этого заголовка должно быть `application/xml; charset=UTF-8`.
`x-ms-lease-id:<ID>`	Необязательный элемент. Если этот заголовок указан, то операция будет выполнена, только если выполняются оба следующих условия. — Аренда BLOB-объекта в настоящее время активна. — идентификатор аренды, указанный в запросе, совпадает с идентификатором большого двоичного объекта. Если этот заголовок указан и оба эти условия не выполнены, попытка выполнения запроса окончится неудачей и операция `Query Blob Contents` завершится ошибкой с кодом состояния 412 (необходимое условие не выполнено).
`Origin`	Необязательный элемент. Указывает источник, от которого выдан запрос. Наличие этого заголовка приводит к заголовкам ОБЩЕГО доступа к ресурсам независимо от источника (CORS) в ответе.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером.

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

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

Текст запроса для этой версии Query Blob Contents использует следующий формат XML:

<?xml version="1.0" encoding="utf-8"?>  
<QueryRequest>
  <QueryType>String</QueryType>
  <Expression>String</Expression>
  <InputSerialization>
    <Format>
      <Type>String</Type>
          <DelimitedTextConfiguration>
            <ColumnSeparator>String</ColumnSeparator>
            <FieldQuote>String</FieldQuote>
            <RecordSeparator>String</RecordSeparator>
            <EscapeChar>String</EscapeChar>
            <HasHeaders>Boolean</HasHeaders>
          </DelimitedTextConfiguration>
          <JsonTextConfiguration>
            <RecordSeparator>String</RecordSeparator>
          </JsonTextConfiguration>
    </Format>
  </InputSerialization>
  <OutputSerialization>
    <Format>
      <Type>String</Type>
      <DelimitedTextConfiguration>
        <ColumnSeparator>String</ColumnSeparator >
        <FieldQuote>String</FieldQuote >
        <RecordSeparator>String</RecordSeparator>
        <EscapeChar>String</EscapeChar>
        <HasHeaders>Boolean</HasHeaders>
      </DelimitedTextConfiguration>
      <JsonTextConfiguration>
        <RecordSeparator>String</RecordSeparator>
      </JsonTextConfiguration>
      <ArrowConfiguration>
        <Schema>
            <Field>
                <Type>String</Type>
                <Name>String</Name>
            </Field>
            <Field>
                <Type>String</Type>
            </Field>
                .
                .
                .
            <Field>
                <Type>String</Type>
                <Precision>Integer</Precision>
                <Scale>Integer</Scale>
            </Field>
        </Schema>
      </ArrowConfiguration>
    </Format>
  </OutputSerialization>
</QueryRequest>

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

Имя элемента	Описание
`QueryRequest`	Обязательный. Группирует набор параметров запроса.
`QueryType`	Обязательный. Указывает тип предоставленного выражения запроса. Единственное допустимое значение для текущей версии — `SQL`.
`Expression`	Обязательный. Указывает выражение запроса в SQL. Максимальный размер выражения запроса составляет 256 КиБ. Дополнительные сведения о синтаксисе выражений см. в статье Ускорение запросов: справочник по языку SQL.
`InputSerialization`	Необязательный элемент. Группирует параметры, касающиеся сериализации входных данных содержимого BLOB-объекта. Если он не указан, используется конфигурация текста с разделителями.
`Format`	Обязателен, если указан ключ `InputSerialization`. Группирует параметры, относящиеся к формату данных большого двоичного объекта.
`Type`	Обязателен, если указан ключ `InputSerialization`. Указывает тип формата. Допустимые значения: `delimited`, `csv` и `json`.
`DelimitedTextConfiguration`	Необязательный элемент. Группирует параметры, используемые для интерпретации данных большого двоичного объекта, если большой двоичный объект имеет формат текста с разделителями.
`ColumnSeparator`	Необязательный элемент. Указывает строку, используемую для разделения столбцов.
`FieldQuote`	Необязательный элемент. Указывает строку, используемую для кавычек определенного поля.
`RecordSeparator`	Необязательный элемент. Указывает строку, используемую для разделения записей.
`EscapeChar`	Необязательный элемент. Указывает строку, используемую в качестве escape-символа.
`HasHeaders`	Необязательный элемент. Задает логическое значение, указывающее, имеются ли у данных заголовки.
`JsonTextConfiguration`	Необязательный элемент. Группирует параметры, используемые для интерпретации данных большого двоичного объекта, если большой двоичный объект имеет формат JSON.
`RecordSeparator`	Необязательный элемент. Указывает строку, используемую для разделения записей.
`OutputSerialization`	Необязательный элемент. Указывает формат сериализации отфильтрованного содержимого большого двоичного объекта, возвращенного в ответе. Если он не указан, используется конфигурация текста с разделителями.
`Format`	Обязателен, если указан ключ `OutputSerialization`. Группирует параметры в отношении формата возвращаемого ответа.
`Type`	Обязателен, если указан ключ `OutputSerialization`. Указывает тип формата. Допустимые значения: `delimited`, `csv`, `json` и `arrow`.
`DelimitedTextConfiguration`	Необязательный элемент. Группирует параметры, используемые для форматирования ответа, если ответ должен быть отформатирован текстом с разделителями.
`ColumnSeparator`	Необязательный элемент. Указывает строку, используемую для разделения столбцов.
`FieldQuote`	Необязательный элемент. Указывает строку, используемую для кавычек определенного поля.
`RecordSeparator`	Необязательный элемент. Указывает строку, используемую для разделения записей.
`EscapeChar`	Необязательный элемент. Указывает строку, используемую в качестве escape-символа.
`HasHeaders`	Необязательный элемент. Задает логическое значение, указывающее, имеются ли у данных заголовки.
`JsonTextConfiguration`	Необязательный элемент. Группирует параметры, используемые для форматирования ответа, если ответ должен быть в формате JSON.
`RecordSeparator`	Необязательный элемент. Указывает строку, используемую для разделения записей.
`ArrowConfiguration`	Необязательный элемент. Группирует параметры, используемые для форматирования ответа, если ответ должен быть отформатирован со стрелками.
`Schema`	Обязателен, если указан ключ `ArrowConfiguration`. Группирует параметры, относящиеся к схеме возвращаемого ответа со стрелкой.
`Field`	Необязательный элемент. Группирует параметры, относящиеся к определенному полю.
`Type`	Обязателен, если указан ключ `Field`. Указывает тип поля. Допустимые значения: `Int`, `Float`, `Decimal` и `Bool`.
`Precision`	Необязательный элемент. Указывает точность поля.
`Scale`	Необязательный элемент. Указывает масштаб поля.

Ответ

Ответ включает код состояния HTTP, набор заголовков ответа и текст ответа. Текст ответа имеет двоичный формат Avro. Так как длина содержимого ответа неизвестна, ответ передается в потоковую передачу с блоками кодировки.

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

Если запрос хорошо сформирован и авторизован, операция возвращает код состояния 202 (принято). Все ошибки или сообщения о ходе выполнения, возникшие во время потоковой передачи ответа, будут возвращены как часть текста ответа.

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

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

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

Синтаксис	Описание
`Last-Modified`	Указывает дату и время последнего изменения большого двоичного объекта. Дата в формате согласно RFC 1123. Любая операция, которая изменяет большой двоичный объект, включая обновление метаданных или свойств большого двоичного объекта, изменяет время последнего изменения большого двоичного объекта.
`Content-Type`	Задает формат, в котором возвращаются результаты. В настоящее время это значение равно `avro/binary`.
`ETag`	Содержит значение, которое можно использовать для условного выполнения операций. Дополнительные сведения см . в разделе Указание условных заголовков для операций с хранилищем BLOB-объектов. Если версия запроса — 18.08.2011 или более поздняя, `ETag` значение будет в кавычках.
`Content-Encoding`	Возвращает значение, указанное для заголовка `Content-Encoding` запроса.
`Content-Language`	Возвращает значение, указанное для заголовка `Content-Language` запроса.
`Cache-Control`	Возвращается, если этот заголовок был ранее указан для большого двоичного объекта.
`Content-Disposition`	Возвращается для запросов к 2013-08-15 и последующей версии. Заголовок возвращает значение, которое было указано для заголовка `x-ms-blob-content-disposition`. Поле `Content-Disposition` заголовка ответа содержит дополнительные сведения об обработке полезных данных ответа. Вы также можете использовать поле заголовка ответа для вложения дополнительных метаданных. Например, если для поля заголовка ответа задано значение `attachment`, агент пользователя не должен отображать ответ. Вместо этого должно отобразиться диалоговое окно Сохранить как с именем файла, отличного от указанного имени большого двоичного объекта.
`x-ms-blob-type: <BlockBlob>`	Возвращает тип большого двоичного объекта.
`x-ms-request-id`	Уникально идентифицирует выполненный запрос. Его можно использовать для устранения неполадок с запросом. Дополнительные сведения см. в статье Устранение неполадок с операциями API.
`x-ms-version`	Указывает версию Хранилище BLOB-объектов Azure, которая используется для выполнения запроса. Включено для запросов, выполненных с использованием версии 2009-09-19 и более поздних версий. Этот заголовок также возвращается для анонимных запросов без указанной версии, если контейнер был помечен для общего доступа с помощью версии 2009-09-19 Хранилища BLOB-объектов.
`Date`	Значение даты и времени в формате UTC, указывающее время отправки ответа службой.
`Access-Control-Allow-Origin`	Возвращается, если запрос содержит заголовок `Origin` и включен CORS с совпадающим правилом. В случае совпадения этот заголовок возвращает значение заголовка источника запроса.
`Access-Control-Expose-Headers`	Возвращается, если запрос содержит заголовок `Origin` и включен CORS с совпадающим правилом. Этот заголовок возвращает список заголовков ответов, которые будут доступны клиенту или издателю запроса.
`Vary`	Возвращается со значением заголовка `Origin`, если заданы правила CORS. Дополнительные сведения см. в статье Поддержка CORS для службы хранилища Azure.
`Access-Control-Allow-Credentials`	Возвращается, если запрос включает заголовок `Origin` , а CORS включен с правилом сопоставления, которое не разрешает все источники. Этот заголовок имеет значение `true`.
`x-ms-blob-committed-block-count`	Указывает количество зафиксированных блоков, присутствующих в большом двоичном объекте. Этот заголовок возвращается только для добавочных BLOB-объектов.
`x-ms-server-encrypted: true/false`	Версия 11.12.2015 или более поздняя. Этот заголовок имеет значение `true` , если данные BLOB-объекта и метаданные приложения полностью зашифрованы с помощью указанного алгоритма. Если большой двоичный объект незашифрован или если шифруются только части метаданных большого двоичного объекта или приложения, устанавливается значение `false`.

Текст ответа

Текст ответа содержит отфильтрованное содержимое большого двоичного объекта, отправленного в виде ряда сообщений в двоичном формате Avro. В нем используется следующая схема:

{
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.resultData",
    "doc": "Holds result data in the format specified for this query (CSV, JSON, etc.).",
    "fields": [
      {
        "name": "data",
        "type": "bytes"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.error",
    "doc": "An error that occurred while processing the query.",
    "fields": [
      {
        "name": "fatal",
        "type": "boolean",
        "doc": "If true, this error prevents further query processing.  More result data may be returned, but there is no guarantee that all of the original data will be processed.  If false, this error does not prevent further query processing."
      },
      {
        "name": "name",
        "type": "string",
        "doc": "The name of the error"
      },
      {
        "name": "description",
        "type": "string",
        "doc": "A description of the error"
      },
      {
        "name": "position",
        "type": "long",
        "doc": "The blob offset at which the error occurred"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.progress",
    "doc": "Information about the progress of the query",
    "fields": [
      {
        "name": "bytesScanned",
        "type": "long",
        "doc": "The number of bytes that have been scanned"
      },
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  },
  {
    "type": "record",
    "name": "com.microsoft.azure.storage.queryBlobContents.end",
    "doc": "Sent as the final message of the response, indicating that all results have been sent.",
    "fields": [
      {
        "name": "totalBytes",
        "type": "long",
        "doc": "The total number of bytes to be scanned in this query"
      }
    ]
  }
]

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

      "StatusCode": 200,
      "ResponseHeaders": {
        "Content-Type": "avro/binary",
        "Date": "Fri, 24 Apr 2020 20:25:42 GMT",
        "ETag": "\u00220x8D7E88DA9C0A75B\u0022",
        "Last-Modified": "Fri, 24 Apr 2020 20:25:43 GMT",
        "Transfer-Encoding": "chunked",
        "x-ms-blob-type": "BlockBlob",
        "x-ms-client-request-id": "f6d1983c-55e5-9f95-6d3d-80d74862d99e",
        "x-ms-creation-time": "Fri, 24 Apr 2020 20:25:43 GMT",
        "x-ms-lease-state": "available",
        "x-ms-lease-status": "unlocked",
        "x-ms-request-id": "46c09ab1-b01e-0001-1076-1acef2000000",
        "x-ms-version": "2019-12-12"
	},
	"ResponseBody":{...}

Авторизация

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

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

Действие Azure RBAC:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Встроенная роль с минимальными привилегиями:читатель данных BLOB-объектов хранилища

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

Подписанный URL-адрес (SAS) обеспечивает безопасный делегированный доступ к ресурсам в учетной записи хранения. С помощью SAS вы можете детально контролировать доступ клиента к данным. Вы можете указать, к какому ресурсу может обращаться клиент, какие у него есть разрешения для этих ресурсов и как долго будет действителен SAS.

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

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

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

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

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

Query Blob Contents Для вызова операции с использованием маркера SAS, делегированного контейнеру или ресурсу BLOB-объекта, требуется разрешение на чтение (r) в рамках маркера SAS делегирования пользователей.

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

SAS для службы

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

Query Blob Contents Для вызова операции с использованием маркера SAS, делегированного контейнеру или ресурсу BLOB-объекта, требуется разрешение на чтение (r) в составе маркера SAS службы.

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

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

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

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

Операция	Подписанная служба	Подписанный тип ресурса	Подписанное разрешение
Запрос содержимого BLOB-объекта	Большой двоичный объект (b)	Объект (o)	Чтение (r)

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

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

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

Операция Query Blob Contents поддерживается только для BlockBlob типа .
Запрос содержимого большого двоичного объекта, зашифрованного с помощью ключей, предоставленных клиентом, не поддерживается в этой версии API.
Эта операция не поддерживается для больших двоичных объектов в учетных записях с включенным шифрованием инфраструктуры .
Заголовок x-ms-version необходим для получения большого двоичного объекта, принадлежащего частному контейнеру. Если большой двоичный объект принадлежит контейнеру, доступного для полного или частичного общего доступа, любой клиент может прочитать его, не указывая версию. Версия службы не требуется для получения большого двоичного объекта, принадлежащего общедоступному контейнеру. Дополнительные сведения см. в разделе Ограничение доступа к контейнерам и BLOB-объектам.
Операцию можно использовать для Query Blob Contents запроса только объектов с разделителями/CSV или JSON.

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

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

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

¹Помимо платы за чтение, с учетной записи взимается плата за категории транзакций "Ускорение запросов - сканирование данных " и "Ускорение запросов - возвращаемые данные ". Цены для этих категорий отображаются на странице цен Azure Data Lake Storage.

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

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