Yandex Cloud
Поиск
Связаться с намиПодключиться
  • Документация
  • Блог
  • Все сервисы
  • Статус работы сервисов
    • Доступны в регионе
    • Инфраструктура и сеть
    • Платформа данных
    • Контейнеры
    • Инструменты разработчика
    • Бессерверные вычисления
    • Безопасность
    • Мониторинг и управление ресурсами
    • Машинное обучение
    • Бизнес-инструменты
  • Все решения
    • По отраслям
    • По типу задач
    • Экономика платформы
    • Безопасность
    • Техническая поддержка
    • Каталог партнёров
    • Обучение и сертификация
    • Облако для стартапов
    • Облако для крупного бизнеса
    • Центр технологий для общества
    • Партнёрская программа
    • Поддержка IT-бизнеса
    • Облако для фрилансеров
    • Обучение и сертификация
    • Блог
    • Документация
    • Мероприятия и вебинары
    • Контакты, чаты и сообщества
    • Идеи
    • Истории успеха
    • Тарифы Yandex Cloud
    • Промоакции и free tier
    • Правила тарификации
  • Документация
  • Блог
Проект Яндекса
© 2025 ТОО «Облачные Сервисы Казахстан»
Yandex Object Storage
  • Правила тарификации
  • Справочник Terraform
    • Аутентификация в API
      • Как пользоваться API
      • Подписывание запросов
      • Начало работы с S3 API
        • Все сервисы и методы
          • Все методы
          • create
          • getBucketEncryption
          • getMeta
          • listObjects
          • listBuckets
          • deleteBucket
          • deleteBucketEncryption
          • putBucketEncryption
          • putBucketVersioning
          • getBucketVersioning
          • putBucketLogging
          • getBucketLogging
          • listObjectVersions
          • putObjectLockConfiguration
          • getObjectLockConfiguration
          • putBucketTagging
          • getBucketTagging
          • deleteBucketTagging
        • Общие заголовки запросов
        • Общие заголовки ответов
        • Ответы
  • Метрики Monitoring
  • Аудитные логи Audit Trails
  • Логи бакета
  • История изменений
  • Вопросы и ответы
  • Обучающие курсы

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

  • listObjectsV2
  • Запрос
  • Ответ
  • listObjectsV1
  • Запрос
  • Ответ
  1. Справочник API
  2. REST (совместимый с Amazon S3)
  3. REST
  4. Bucket
  5. listObjects

Метод listObjects

Статья создана
Yandex Cloud
Улучшена
poltsarstva
Обновлена 19 мая 2025 г.
  • 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.

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

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

См. такжеСм. также

  • Начало работы с AWS S3 API в Yandex Object Storage
  • Отладка запросов с помощью утилиты AWS CLI
  • Пример отправки подписанного запроса с помощью утилиты curl
  • Пример кода для генерации подписи

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

Предыдущая
getMeta
Следующая
listBuckets
Проект Яндекса
© 2025 ТОО «Облачные Сервисы Казахстан»