Связаться с намиПодключиться

Метод selectObjectContent

Статья создана
Обновлена 6 сентября 2024 г.

Фильтрует и возвращает содержимое объекта Object Storage на основе запроса на языке S3 Select.

Важно

Чтобы получить возможность отправлять запросы на языке S3 Select, обратитесь в техническую поддержку. Также вы должны иметь разрешение на действие s3:GetObject — подробнее читайте в разделе Политика доступа (bucket policy).

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

  • Поддерживаются объекты в формате CSV, JSON и Parquet.

  • Поддерживаются объекты в кодировке UTF-8.

  • Для CSV-файлов поддерживаются методы сжатия GZIP и BZIP2. Для файлов в формате Parquet поддерживается столбчатое сжатие с помощью методов GZIP, Snappy и ZSTD.

  • Объекты могут быть защищены шифрованием на стороне сервера.

Для объектов, которые зашифрованы с помощью управляемых ключей шифрования, хранящихся в YC Key Management Service (SSE-KMS), шифрование на стороне сервера выполняется прозрачно, поэтому вам не нужно дополнительно ничего указывать.

Подробнее о подготовке к работе с API и общем виде запроса см. в разделе Как пользоваться S3 API.

Запрос

POST /{bucket}/{key}?select&select-type=2 HTTP/2

Path параметры

Параметр Описание
bucket Имя бакета.
key Ключ объекта.

Query параметры

Параметр Описание
select Обязательный параметр для обозначения типа операции.
select-type Необязательный параметр для обозначения типа запроса.

Заголовки

Используйте в запросе необходимые общие заголовки.

Схема данных

Параметры запроса передаются в XML формате:

<SelectObjectContentRequest xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Expression>string</Expression>
   <ExpressionType>string</ExpressionType>
   <RequestProgress>
      <Enabled>boolean</Enabled>
   </RequestProgress>
   <InputSerialization>
      <CompressionType>string</CompressionType>
      <CSV>
         <AllowQuotedRecordDelimiter>boolean</AllowQuotedRecordDelimiter>
         <Comments>string</Comments>
         <FieldDelimiter>string</FieldDelimiter>
         <FileHeaderInfo>string</FileHeaderInfo>
         <QuoteCharacter>string</QuoteCharacter>
         <QuoteEscapeCharacter>string</QuoteEscapeCharacter>
         <RecordDelimiter>string</RecordDelimiter>
      </CSV>
      <JSON>
         <Type>string</Type>
      </JSON>
      <Parquet>
      </Parquet>
   </InputSerialization>
   <OutputSerialization>
      <CSV>
         <FieldDelimiter>string</FieldDelimiter>
         <QuoteCharacter>string</QuoteCharacter>
         <QuoteEscapeCharacter>string</QuoteEscapeCharacter>
         <QuoteFields>string</QuoteFields>
         <RecordDelimiter>string</RecordDelimiter>
      </CSV>
      <JSON>
         <RecordDelimiter>string</RecordDelimiter>
      </JSON>
   </OutputSerialization>
   <ScanRange>
      <End>long</End>
      <Start>long</Start>
   </ScanRange>
</SelectObjectContentRequest>
Тег Описание
SelectObjectContentRequest Тег корневого уровня для передачи параметров запроса.

Обязательный: да.

Путь: /SelectObjectContentRequest.
Expression SQL-выражение, используемое для запроса данных объекта.

Тип данных: строка.

Обязательный: да.

Путь: /SelectObjectContentRequest/Expression.
ExpressionType Тип выражения, используемого для запроса.

Тип данных: строка.

Допустимые значения: SQL.

Обязательный: да.

Путь: /SelectObjectContentRequest/ExpressionType.
InputSerialization Описание формата данных в запрашиваемом объекте.

Тип данных: InputSerialization.

Обязательный: да.

Путь: /SelectObjectContentRequest/InputSerialization.
OutputSerialization Описание формата возвращаемых данных.

Тип данных: OutputSerialization.

Обязательный: да.

Путь: /SelectObjectContentRequest/OutputSerialization.
RequestProgress Указывает, должно ли быть включено периодическое информирование о ходе выполнения запроса.

Тип данных: RequestProgress.

Обязательный: нет.

Путь: /SelectObjectContentRequest/RequestProgress.
ScanRange Задает диапазон байтов объекта, из которого будут получены записи. Запись обрабатывается, когда ее первый байт содержится в диапазоне. Применяется только для объектов в формате CSV.

Тип данных: ScanRange.

Обязательный: нет.

Путь: /SelectObjectContentRequest/ScanRange.

Ответ

Заголовки

Ответ может содержать только общие заголовки.

Коды ответов

Перечень возможных ответов смотрите в разделе Ответы.

Успешный ответ содержит дополнительные данные в формате XML, схема которого описана ниже.

Схема данных

<Payload>
   <Records>
      <Payload>blob</Payload>
   </Records>
   <Stats>
      <Details>
         <BytesProcessed>long</BytesProcessed>
         <BytesReturned>long</BytesReturned>
         <BytesScanned>long</BytesScanned>
      </Details>
   </Stats>
   <Progress>
      <Details>
         <BytesProcessed>long</BytesProcessed>
         <BytesReturned>long</BytesReturned>
         <BytesScanned>long</BytesScanned>
      </Details>
   </Progress>
   <Cont>
   </Cont>
   <End>
   </End>
</Payload>
Тег Описание
Payload Тег корневого уровня для передачи параметров ответа.

Путь: /Payload.
Cont Сообщение, указывающее, что запрос обрабатывается.

Путь: /Payload/Cont.
End Сообщение, указывающее, что запрос обработан.

Путь: /Payload/End.
Progress Информация о ходе выполнения запроса.

Путь: /Payload/Progress.
Records Результат запроса.
Путь: /Payload/Records.
Stats Статистика по обработанным данным. Высылается один раз в конце запроса.
Путь: /Payload/Stats.

См. также

Предыдущая
options
Следующая
putObjectRetention