Yandex Cloud
КейсыДокументация
ПрезентацияСвязаться с намиНачать бесплатно
Создавайте контент и получайте гранты!Готовы написать своё руководство? Участвуйте в контент-программе и получайте гранты на работу с облачными сервисами!
Подробнее о программе
Сделано на Gravity UI
Проект Яндекса
© 2026 ООО «Яндекс.Облако»
Yandex Object Storage
  • Правила тарификации
  • Справочник Terraform
    • Аутентификация в API
      • Как пользоваться API
      • Подписывание запросов
      • Начало работы с S3 API
        • Все сервисы и методы
          • Все методы
          • CreateBucket
          • GetBucketEncryption
          • HeadBucket
          • ListObjects
          • ListBuckets
          • DeleteBucket
          • DeleteBucketEncryption
          • PutBucketEncryption
          • PutBucketVersioning
          • GetBucketVersioning
          • PutBucketLogging
          • GetBucketLogging
          • ListObjectVersions
          • PutObjectLockConfiguration
          • GetObjectLockConfiguration
          • PutBucketTagging
          • GetBucketTagging
          • DeleteBucketTagging
        • Общие заголовки запросов
        • Общие заголовки ответов
        • Ответы
  • Метрики Monitoring
  • Аудитные логи Audit Trails
  • Логи бакета
  • История изменений
  • Вопросы и ответы
  • Обучающие курсы

В этой статье:

  • listObjectsV2
  • Запрос
  • Ответ
  • listObjectsV1
  • Запрос
  • Ответ
  1. Справочник API
  2. AWS S3 REST
  3. REST
  4. Bucket
  5. ListObjects

Object Storage API, REST совместимый с Amazon S3: ListObjects

Статья создана
Yandex Cloud
Улучшена
Обновлена 17 августа 2026 г.
Открыть в Markdown
  • listObjectsV2
    • Запрос
    • Ответ
  • listObjectsV1
    • Запрос
    • Ответ

Возвращает список объектов в бакете.

Не возвращает содержимое объектов. Чтобы получить его, воспользуйтесь методом get.

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

Примечание

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

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

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

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

listObjectsV2listObjectsV2

ЗапросЗапрос

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

Path параметрыPath параметры

Параметр

Описание

bucket

Имя бакета

Query параметры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, ICE или INTELLIGENT_TIERING.

Путь: /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.

listObjectsV1listObjectsV1

ЗапросЗапрос

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

Path параметрыPath параметры

Параметр

Описание

bucket

Имя бакета

Query параметры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, ICE или INTELLIGENT_TIERING.

Путь: /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.

Связанные статьиСвязанные статьи

  • Бакет в Object Storage

  • Получить список объектов в бакете

Полезные ссылкиПолезные ссылки

  • Начало работы с AWS S3 API в Yandex Object Storage

  • Отладка запросов с помощью утилиты AWS CLI

  • Пример отправки подписанного запроса с помощью утилиты curl

  • Пример кода для генерации подписи

Была ли статья полезна?

Предыдущая
HeadBucket
Следующая
ListBuckets
Создавайте контент и получайте гранты!Готовы написать своё руководство? Участвуйте в контент-программе и получайте гранты на работу с облачными сервисами!
Подробнее о программе
Сделано на Gravity UI
Проект Яндекса
© 2026 ООО «Яндекс.Облако»