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

Метод listObjectVersions

Статья создана
Обновлена 15 августа 2025 г.

Возвращает метаданные обо всех версиях объектов в бакете.
Также можно использовать параметры запроса в качестве критерия выбора для возврата метаданных о подмножестве версий объекта.

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

Запрос

GET /{bucket}?versions&delimiter=Delimiter&encoding-type=EncodingType&key-marker=KeyMarker&max-keys=MaxKeys&prefix=Prefix&version-id-marker=VersionIdMarker HTTP/2

Path параметры

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

Query параметры

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

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

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

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

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

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

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

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

Если под критерии отбора попадает больше ключей, чем поместилось в выдаче, то ответ содержит <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <KeyCount>1</KeyCount> <Name>my-sample-bucket</Name> <Prefix></Prefix> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>text.txt</Key> <LastModified>2025-05-15T07:23:08.030Z</LastModified> <Owner> <ID>ajegtlf2q28a********</ID> <DisplayName>ajegtlf2q28a********</DisplayName> </Owner> <ETag>&#34;f75a361db63aa4722fb8e083********&#34;</ETag> <Size>103</Size> <StorageClass>STANDARD</StorageClass> <TagSet></TagSet> </Contents> </ListBucketResult>.

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

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

Может использоваться одновременно с параметром delimiter. В этом случае логика выдачи становится той, что указана в описании параметра delimiter.
version-id-marker Версия объекта, с которой начинается выдача.

В результирующей выдаче Object Storage оставит версии, начиная со следующей за version-id-marker.

Заголовки

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

Ответ

Заголовки

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

Коды ответов

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

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

Схема данных

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult
          xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
          <KeyCount>1</KeyCount>
          <Name>my-sample-bucket</Name>
          <Prefix></Prefix>
          <MaxKeys>1000</MaxKeys>
          <IsTruncated>false</IsTruncated>
          <Contents>
              <Key>text.txt</Key>
              <LastModified>2025-05-15T07:23:08.030Z</LastModified>
              <Owner>
                  <ID>ajegtlf2q28a********</ID>
                  <DisplayName>ajegtlf2q28a********</DisplayName>
              </Owner>
              <ETag>&#34;f75a361db63aa4722fb8e083********&#34;</ETag>
              <Size>103</Size>
              <StorageClass>STANDARD</StorageClass>
              <TagSet></TagSet>
          </Contents>
      </ListBucketResult>
Элемент Описание
ListVersionsResult Корневой элемент
CommonPrefixes Часть имени ключа, которая определяется при обработке query параметров delimiter и prefix.

Путь: /ListVersionsResult/CommonPrefixes.
DeleteMarker Контейнер для объекта, который является маркером удаления.

Путь: /ListVersionsResult/DeleteMarker.
Delimiter Значение query параметра delimiter.

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

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

Путь: /ListVersionsResult/EncodingType.
IsTruncated Признак неполноты списка.

Если IsTruncated — true, то это означает, что Object Storage вернул не полный список частей.

Путь: /ListVersionsResult/IsTruncated.
KeyMarker Последний ключ, возвращенный в неполном ответе.

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

Путь: /ListBucketResult/MaxKeys.
Name Название бакета.

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

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

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

Путь: /ListBucketResult/Prefix.
Version Версия объекта.

Путь: /ListBucketResult/Version.
VersionIdMarker Отмечает последнюю версию ключа, возвращенную в усеченном ответе.

Путь: /ListBucketResult/VersionIdMarker.

См. также

Предыдущая
getBucketLogging
Следующая
putObjectLockConfiguration