Object Storage API, REST совместимый с Amazon S3: SelectObjectContent
Фильтрует и возвращает содержимое объекта 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. |