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

Метод listObjects

Статья создана
Улучшена
Обновлена 30 сентября 2024 г.

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

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

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

Примечание

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

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

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

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

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 или 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.

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 или 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.

См. также

Предыдущая
getMeta
Следующая
listBuckets