Подключиться
Yandex Object Storage

Метод listObjects

Статья создана

Возвращает перечень объектов в бакете.

При выдаче используется пагинация, за один запрос можно получить список не длиннее 1000 объектов. Если объектов больше, то необходимо выполнить несколько запросов подряд.

Примечание

У этого метода есть две версии.

  • listObjectsV2 — актуальная версия, более удобная в использовании.
  • listObjectsV1 — предыдущая версия.

Для вызова обоих методов используется один и тот же URL, но он отличается query-параметром. Чтобы вызвать listObjectsV2, используйте параметр list-type=2.

listObjectsV2

Запрос

GET /{bucket}?list-type=2&continuation-token=ContinuationToken&delimiter=Delimiter&encoding-type=EncodingType&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter HTTP/2

Path параметры

Параметр Описание
bucket Имя бакета.

Query параметры

Все перечисленные в таблице параметры необязательные.

Параметр Описание
continuation-token Используется для получения следующей части списка, если все результаты не помещаются в один ответ.
Чтобы получить следующую часть списка, используйте значение NextContinuationToken из предыдущего ответа.
delimiter Символ-разделитель.

Если параметр указан, то Object Storage рассматривает ключ как путь к файлу, где каталоги разделяются символом delimiter. В ответе на запрос пользователь увидит перечень файлов и каталогов в бакете. Файлы будут выведены в элементах Contents, а каталоги в элементах CommonPrefixes.

Если в запросе указан еще и параметр prefix, то Object Storage вернет перечень файлов и каталогов в каталоге prefix.
encoding-type Кодировка ответа от сервера.

Object Storage по требованию клиента может закодировать ответ в требуемом виде.

Возможные значения: url.
max-keys Максимальное количество элементов в ответе.

По умолчанию Object Storage выдает не более 1000 элементов Contents и CommonPrefixes. Параметр следует использовать, если вам нужно получать менее 1000 элементов в одном ответе.

Если под критерии отбора попадает больше ключей, чем поместилось в выдаче, то ответ содержит <IsTruncated>true</IsTruncated>.

Чтобы получить все элементы выдачи, если их больше max-keys, необходимо выполнить несколько последовательных запросов к Object Storage с параметром continuation-token, где для каждого запроса continuation-token равен значению элемента NextContinuationToken из предыдущего ответа.
prefix Строка, с которой должен начинаться ключ.

Object Storage выберет только те ключи, которые начинаются с prefix.

Может использоваться одновременно с параметром delimiter. В этом случае логика выдачи определяется параметром delimiter.
start-after Ключ, с которого нужно начать листинг.

Заголовки

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

Ответ

Заголовки

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

Коды ответов

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

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

Схема данных

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
   <IsTruncated>boolean</IsTruncated>
   <Contents>
      <ETag>string</ETag>
      <Key>string</Key>
      <LastModified>timestamp</LastModified>
      <Size>integer</Size>
      <StorageClass>string</StorageClass>
   </Contents>
   ...
   <Name>string</Name>
   <Prefix>string</Prefix>
   <Delimiter>string</Delimiter>
   <MaxKeys>integer</MaxKeys>
   <CommonPrefixes>
      <Prefix>string</Prefix>
   </CommonPrefixes>
   ...
   <EncodingType>string</EncodingType>
   <KeyCount>integer</KeyCount>
   <ContinuationToken>string</ContinuationToken>
   <NextContinuationToken>string</NextContinuationToken>
   <StartAfter>string</StartAfter>
</ListBucketResult>
Элемент Описание
ListBucketResult Корневой элемент.
IsTruncated Флаг, показывающий все ли результаты возвращены в этом ответе.

True — все. False — не все.

Путь: /ListBucketResult/IsTruncated.
Contents Описание объекта.

Ответ будет содержать столько элементов Contents, сколько ключей попало под условия запроса.

Путь: /ListBucketResult/Contents.
ETag MD5-хэш объекта. Метаданные в расчете хэша не участвуют.

Путь: /ListBucketResult/Contents/ETag.
Key Ключ объекта.

Путь: /ListBucketResult/Contents/Key.
LastModified Дата и время последнего изменения объекта.

Путь: /ListBucketResult/Contents/LastModified.
Size Размер объекта в байтах.

Путь: /ListBucketResult/Contents/Size.
StorageClass Класс хранения объекта: STANDARD или COLD.

Путь: /ListBucketResult/Contents/StorageClass.
Name Имя бакета.

Путь: /ListBucketResult/Name.
Prefix Значение query-параметра prefix.

Путь: /ListBucketResult/Prefix.
Delimiter Значение query-параметра delimiter.

Путь: /ListBucketResult/Delimiter.
MaxKeys Значение query-параметра max-keys.

Путь: /ListBucketResult/MaxKeys.
CommonPrefixes Часть имени ключа, которая определяется при обработке query-параметров delimiter и prefix.

Путь: /ListBucketResult/CommonPrefixes.
EncodingType Кодировка, в которой Object Storage представляет ключ в XML-ответе.

Появляется, если клиент при запросе передал параметр encoding-type.

Путь: /ListBucketResult/EncodingType.
KeyCount Количество ключей, возвращенных запросом.
Количество ключей всегда будет меньше или равно MaxKeys.

Путь: /ContinuationToken/KeyCount.
ContinuationToken Значение query-параметра continuation-token.

Путь: /ContinuationToken/ContinuationToken.
NextContinuationToken Значение, которое надо подставить в query-параметр continuation-token для получения следующей части списка, если весь список не поместился в текущий ответ.
Возвращается только в том случае, если IsTruncated = true.

Путь: /ListBucketResult/NextContinuationToken.
StartAfter Значение query-параметра start-after.

Путь: /ListBucketResult/StartAfter.

listObjectsV1

Запрос

GET /{bucket}?delimiter=Delimiter&encoding-type=EncodingType&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/2

Path параметры

Параметр Описание
bucket Имя бакета.

Query параметры

Все перечисленные в таблице параметры необязательные.

Параметр Описание
delimiter Символ-разделитель.

Если параметр указан, то Object Storage рассматривает ключ как путь к файлу, где каталоги разделяются символом delimiter. В ответе на запрос пользователь увидит перечень файлов и каталогов в бакете. Файлы будут выведены в элементах Contents, а каталоги в элементах CommonPrefixes.

Если в запросе указан еще и параметр prefix, то Object Storage вернет перечень файлов и каталогов в каталоге prefix.
encoding-type Кодировка ответа от сервера.

Object Storage по требованию клиента может закодировать ответ в требуемом виде.

Возможные значения: url.
marker Ключ, с которого начнется выдача.

В результирующей выдаче Object Storage оставит ключи, начиная со следующего за marker.
max-keys Максимальное количество элементов в ответе.

По умолчанию Object Storage выдает не более 1000 элементов Contents и CommonPrefixes. Параметр следует использовать, если вам нужно получать менее 1000 элементов в одном ответе.

Если под критерии отбора попадает больше ключей, чем поместилось в выдаче, то ответ содержит <IsTruncated>true</IsTruncated>.

Чтобы получить все элементы выдачи, если их больше max-keys, необходимо выполнить несколько последовательных запросов к Object Storage с параметром marker, где для каждого запроса marker равен значению элемента NextMarker из предыдущего ответа.
prefix Строка, с которой должен начинаться ключ.

Object Storage выберет только те ключи, которые начинаются с prefix.

Может использоваться одновременно с параметром delimiter. В этом случае логика выдачи определяется параметром delimiter.

Заголовки

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

Ответ

Заголовки

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

Коды ответов

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

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

Схема данных

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
   <IsTruncated>boolean</IsTruncated>
   <Marker>string</Marker>
   <NextMarker>string</NextMarker>
   <Contents>
      <ETag>string</ETag>
      <Key>string</Key>
      <LastModified>timestamp</LastModified>
      <Size>integer</Size>
      <StorageClass>string</StorageClass>
   </Contents>
   ...
   <Name>string</Name>
   <Prefix>string</Prefix>
   <Delimiter>string</Delimiter>
   <MaxKeys>integer</MaxKeys>
   <CommonPrefixes>
      <Prefix>string</Prefix>
   </CommonPrefixes>
   ...
   <EncodingType>string</EncodingType>
</ListBucketResult>
Элемент Описание
ListBucketResult Корневой элемент.
IsTruncated Флаг, показывающий все ли результаты возвращены в этом ответе.

True — все. False — не все.

Путь: /ListBucketResult/IsTruncated.
Marker Значение query-параметра marker.

Путь: /ListBucketResult/Marker.
NextMarker Значение, которое надо подставить в query-параметр marker для получения следующей части списка, если весь список не поместился в текущий ответ.

Путь: /ListBucketResult/NextMarker.
Contents Описание объекта.

Ответ будет содержать столько элементов Contents, сколько ключей попало под условия запроса.

Путь: /ListBucketResult/Contents.
ETag MD5-хэш объекта. Метаданные в расчете хэша не участвуют.

Путь: /ListBucketResult/Contents/ETag.
Key Ключ объекта.

Путь: /ListBucketResult/Contents/Key.
LastModified Дата и время последнего изменения объекта.

Путь: /ListBucketResult/Contents/LastModified.
Size Размер объекта в байтах.

Путь: /ListBucketResult/Contents/Size.
StorageClass Класс хранения объекта: STANDARD или COLD.

Путь: /ListBucketResult/Contents/StorageClass.
Name Имя бакета.

Путь: /ListBucketResult/Name.
Prefix Значение query-параметра prefix.

Путь: /ListBucketResult/Prefix.
Delimiter Значение query-параметра delimiter.

Путь: /ListBucketResult/Delimiter.
MaxKeys Значение query-параметра max-keys.

Путь: /ListBucketResult/MaxKeys.
CommonPrefixes Часть имени ключа, которая определяется при обработке query-параметров delimiter и prefix.

Путь: /ListBucketResult/CommonPrefixes.
EncodingType Кодировка, в которой Object Storage представляет ключ в XML-ответе.

Появляется, если клиент при запросе передал параметр encoding-type.

Путь: /ListBucketResult/EncodingType.
В этой статье: