list-objects

Описание

Примечание

Данная операция не поддерживается для ведер каталогов.

Возвращает некоторые или все (до 1000) объекты в ведре. Вы можете использовать параметры запроса в качестве критериев выбора для возврата подмножества объектов в ведре. Ответ 200 OK может содержать допустимые или недопустимые XML-данные. Убедитесь, что ваше приложение разработано для парсинга содержимого ответа и соответствующей обработки.

Предупреждение

Данное действие было пересмотрено. Рекомендуется использовать новую версию, ListObjectsV2, при разработке приложений. Для обеспечения обратной совместимости Amazon S3 продолжает поддерживать ListObjects .

Следующие операции связаны с ListObjects :

ListObjectsV2
GetObject
PutObject
CreateBucket
ListBuckets

См. также: Документация AWS API

list-objects является постраничной операцией. Для получения всего набора результатов могут быть выполнены несколько API-вызовов. Вы можете отключить постраничный вывод, указав аргумент --no-paginate. При использовании --output text и аргумента --query с постраничным ответом, аргумент --query должен извлекать данные из результатов следующих выражений запроса: Contents, CommonPrefixes

Синтаксис

  list-objects
--bucket <value>
[--delimiter <value>]
[--encoding-type <value>]
[--prefix <value>]
[--request-payer <value>]
[--expected-bucket-owner <value>]
[--optional-object-attributes <value>]
[--cli-input-json | --cli-input-yaml]
[--starting-token <value>]
[--page-size <value>]
[--max-items <value>]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]

Параметры

--bucket (строка)

Имя ведра, содержащего объекты.

Ведра каталогов - При использовании этой операции с ведром каталога необходимо использовать запросы в стиле виртуального хостинга в формате `` ИмяВедра .s3express-идентификаторЗоны .*кодРегиона* .amazonaws.com`` . Запросы в стиле пути не поддерживаются. Имена ведер каталогов должны быть уникальными в выбранной зоне (зоне доступности или локальной зоне). Имена ведер должны соответствовать формату `` базовоеИмяВедра –идентификаторЗоны –x-s3`` (например, `` amzn-s3-demo-bucket –usw2-az1 –x-s3`` ). Сведения о ограничениях имен ведер см. в руководстве пользователя Amazon S3 в разделе Правила именования ведер каталогов.

Точки доступа - При использовании этого действия с точкой доступа для ведер общего назначения необходимо указать псевдоним точки доступа вместо имени ведра или указать ARN точки доступа. При использовании этого действия с точкой доступа для ведер каталогов необходимо указать имя точки доступа вместо имени ведра. При использовании ARN точки доступа необходимо направить запросы на хост-имя точки доступа. Хост-имя точки доступа имеет вид ИмяТочкиДоступа -IDАккаунта .s3-accesspoint.*Регион* .amazonaws.com. При использовании этого действия с точкой доступа через Amazon Web Services SDKs вы указываете ARN точки доступа вместо имени ведра. Дополнительную информацию об ARN точек доступа см. в руководстве пользователя Amazon S3 в разделе Использование точек доступа.

Примечание

Точки доступа Object Lambda не поддерживаются ведрами каталогов.

S3 в Outposts - При использовании этого действия с S3 в Outposts необходимо направить запросы на хост-имя S3 в Outposts. Хост-имя S3 в Outposts имеет вид `` ИмяТочкиДоступа -IDАккаунта .*IDOutpost* .s3-outposts.*Регион* .amazonaws.com`` . При использовании этого действия с S3 в Outposts, целевое ведро должно быть ARN точки доступа Outposts или псевдоним точки доступа. Дополнительную информацию об S3 в Outposts см. в руководстве пользователя Amazon S3 в разделе Что такое S3 в Outposts?

--delimiter (строка)

Разделитель - это символ, используемый для группировки ключей.

--encoding-type (строка)

Тип кодирования, используемый Amazon S3 для кодирования ключей объектов в ответе. Ответы кодируются только в UTF-8. Ключ объекта может содержать любой символ Unicode. Однако XML-парсер 1.0 не может обработать определенные символы, например, символы с ASCII-значением от 0 до 10. Для символов, которые не поддерживаются в XML 1.0, вы можете добавить этот параметр, чтобы запросить кодировку Amazon S3 ключей в ответе. Дополнительную информацию о символах, которые следует избегать в именах ключей объектов, см. в руководстве пользователя по именованию ключей объектов.

Примечание

При использовании типа кодирования URL символы, отличные от ASCII, которые используются в имени ключа объекта, будут закодированы по процентам в соответствии с кодовыми значениями UTF-8. Например, объект test_file(3).png будет отображаться как test_file%283%29.png .

Возможные значения:

url

--prefix (строка)

Ограничивает ответ ключами, начинающимися с указанного префикса.

--request-payer (строка)

Подтверждает, что пользователь понимает, что за запрос ListObjects будет взиматься плата. Владельцам ведер не нужно указывать этот параметр в своих запросах.

Возможные значения:

requester

--expected-bucket-owner (строка)

Идентификатор учетной записи ожидаемого владельца ведра. Если предоставленный вами идентификатор учетной записи не совпадает с фактическим владельцем ведра, запрос завершается с HTTP-кодом состояния 403 Forbidden (доступ запрещен).

--optional-object-attributes (список)

Указывает необязательные поля, которые вы хотите получить в ответе. Поля, которые вы не указываете, не возвращаются.

(строка)

Синтаксис:

"string" "string" ...

Where valid values are:
  RestoreStatus

--cli-input-json | --cli-input-yaml (строка) Считывает аргументы из предоставленной JSON-строки. JSON-строка соответствует формату, предоставленному --generate-cli-skeleton. Если на командной строке указаны другие аргументы, эти значения переопределят значения, полученные из JSON. Невозможно передавать произвольные двоичные значения с помощью значения, предоставленного в JSON, так как строка будет воспринята буквально. Это не может быть указано вместе с --cli-input-yaml.

--starting-token (строка)

Токен, указывающий, где следует начать постраничный вывод. Это NextToken из ранее усеченного ответа.

Примеры использования см. в руководстве пользователя AWS CLI в разделе Постраничный вывод.

--page-size (целое число)

Размер каждой страницы для получения в вызове AWS-сервиса. Это не влияет на количество элементов, возвращаемых в выходных данных команды. Установка меньшего размера страницы приводит к большему количеству вызовов AWS-сервиса, получая меньше элементов в каждом вызове. Это может помочь предотвратить истечение времени ожидания вызовов AWS-сервиса.

Примеры использования см. в руководстве пользователя AWS CLI в разделе Постраничный вывод.

--max-items (целое число)

Общее количество элементов, которые нужно вернуть в выходных данных команды. Если общее количество доступных элементов больше указанного значения, в выходных данных команды предоставляется NextToken. Для возобновления постраничного вывода предоставьте значение NextToken в аргументе starting-token последующей команды. **Не** используйте элемент ответа NextToken напрямую за пределами AWS CLI.

Примеры использования см. в руководстве пользователя AWS CLI в разделе Постраничный вывод.

--generate-cli-skeleton (строка) Выводит JSON-скелет в стандартный вывод без отправки API-запроса. При отсутствии значения или значении input выводит JSON-входной образец, который можно использовать в качестве аргумента для --cli-input-json. Аналогично, если предоставлено значение yaml-input, будет выведен образец входных данных YAML, который можно использовать с --cli-input-yaml. Если предоставлено значение output, оно проверяет входные данные команды и возвращает образец выходных JSON для этой команды. Сгенерированный JSON-скелет не стабилен между версиями AWS CLI, и нет гарантий обратной совместимости в сгенерированном JSON-скелете.

Глобальные параметры

--debug (булево)

Включить отладку логов.

--endpoint-url (строка)

Переопределить URL команды указанным URL.

--no-verify-ssl (булево)

По умолчанию AWS CLI использует SSL при общении с AWS-сервисами. Для каждого соединения SSL AWS CLI проверит сертификаты SSL. Этот параметр переопределяет поведение по умолчанию, проверяющее сертификаты SSL.

--no-paginate (булево)

Отключить автоматическую постраничную загрузку. Если автоматическая постраничная загрузка отключена, AWS CLI сделает только один вызов для первой страницы результатов.

--output (строка)

Стиль форматирования выходных данных команды.

json
text
table
yaml
yaml-stream

--query (строка)

JMESPath-запрос для фильтрации данных ответа.

--profile (строка)

Использовать определенный профиль из файла учетных данных.

--region (строка)

Используемая область. Переопределяет настройки конфигурации/среды.

--version (строка)

Отобразить версию этого инструмента.

--color (строка)

Включить/отключить цветной вывод.

on
off
auto

--no-sign-request (булево)

Не подписывать запросы. Учетные данные не будут загружены, если этот аргумент предоставлен.

--ca-bundle (строка)

Файл сертификата CA для использования при проверке SSL-сертификатов. Переопределяет настройки конфигурации/среды.

--cli-read-timeout (целое число)

Максимальное время чтения сокета в секундах. Если значение установлено в 0, чтение сокета будет блокирующим и не будет ограничено по времени. Значение по умолчанию составляет 60 секунд.

--cli-connect-timeout (целое число)

Максимальное время подключения сокета в секундах. Если значение установлено в 0, подключение сокета будет блокирующим и не будет ограничено по времени. Значение по умолчанию составляет 60 секунд.

--cli-binary-format (строка)

Стиль форматирования двоичных блоков. По умолчанию используется формат base64. Формат base64 ожидает, что двоичные блоки будут предоставлены как строка, закодированная в base64. Формат raw-in-base64-out сохраняет совместимость с поведением AWS CLI V1, и двоичные значения должны быть переданы буквально. При предоставлении содержимого из файла, соответствующего двоичному блоку, fileb:// всегда будет обрабатываться как двоичный и будет использовать содержимое файла непосредственно независимо от параметра cli-binary-format. При использовании file:// содержимое файла необходимо правильно отформатировать для настроенного cli-binary-format.

base64
raw-in-base64-out

--no-cli-pager (булево)

Отключить постраничный вывод для вывода.

--cli-auto-prompt (булево)

Автоматически запрашивать параметры входных данных CLI.

--no-cli-auto-prompt (булево)

Отключить автоматическую запрос параметров входных данных CLI.

Примеры

Примечание

Для использования следующих примеров необходимо установить и настроить AWS CLI. Дополнительную информацию см. в руководстве по началу работы в Руководстве пользователя AWS CLI.

Если не указано иное, все примеры используют правила цитирования, подобные unix-подобным. Эти примеры необходимо адаптировать к правилам цитирования вашей терминальной оболочки. Дополнительную информацию см. в разделе «Использование кавычек со строками» в Руководстве пользователя AWS CLI .

Следующий пример использует команду list-objects для отображения имен всех объектов в указанном ведре:

aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}'

В примере используется аргумент --query для фильтрации выходных данных list-objects до значений ключа и размера каждого объекта.

Дополнительную информацию об объектах см. в разделе «Работа с объектами Amazon S3» в Руководстве разработчика Amazon S3.

Вывод

IsTruncated -> (boolean)

Флаг, указывающий, вернул ли Amazon S3 все результаты, удовлетворяющие критериям поиска.

Marker -> (строка)

Указывает, с какой позиции в списке ведра начинается поиск. Marker включается в ответ, если он был отправлен в запросе.

NextMarker -> (строка)

Если ответ усечен (значение элемента IsTruncated в ответе равно true), вы можете использовать имя ключа в этом поле в качестве параметра marker в последующем запросе, чтобы получить следующий набор объектов. Amazon S3 перечисляет объекты в алфавитном порядке.

Примечание

Этот элемент возвращается только в том случае, если вы указали параметр запроса delimiter. Если ответ не включает элемент NextMarker и он усечен, вы можете использовать значение последнего элемента Key в ответе в качестве параметра marker в последующем запросе, чтобы получить следующий набор ключей объектов.

Contents -> (список)

Метаданные о каждом возвращенном объекте.

(структура)

Объект состоит из данных и метаданных описания.

Key -> (строка)

Имя, которое вы назначаете объекту. Вы используете ключ объекта для получения объекта.

LastModified -> (временная метка)

Дата создания объекта.

ETag -> (строка)

Тег сущности — это хеш объекта. Тег ETag отражает изменения только содержимого объекта, а не его метаданных. ETag может или не может быть хэш-суммой MD5 данных объекта. Это зависит от того, как объект был создан и как он был зашифрован, как описано ниже:

Объекты, созданные с помощью операции PUT Object, POST Object или Copy, или через веб-консоль Amazon Web Services и зашифрованные с помощью SSE-S3 или в открытом виде, имеют ETags, представляющие собой хэш-суммы MD5 их данных объекта.
Объекты, созданные с помощью операции PUT Object, POST Object или Copy, или через веб-консоль Amazon Web Services и зашифрованные с помощью SSE-C или SSE-KMS, имеют ETags, которые не являются хэш-суммами MD5 их данных объекта.
Если объект создан с помощью операции Multipart Upload или Part Copy, ETag не является хэш-суммой MD5, независимо от метода шифрования. Если объект больше 16 МБ, веб-консоль Amazon Web Services загрузит или скопирует его как Multipart Upload, и поэтому ETag не будет хэш-суммой MD5.

Примечание

Ведра каталогов - MD5 не поддерживается ведрами каталогов.

ChecksumAlgorithm -> (список)

Алгоритм, используемый для создания контрольной суммы объекта.

(строка)

ChecksumType -> (строка)

Тип контрольной суммы, используемый для вычисления значения контрольной суммы объекта. Дополнительную информацию см. в разделе «Проверка целостности объектов» в Руководстве пользователя Amazon S3.

Size -> (целое)

Размер объекта в байтах.

StorageClass -> (строка)

Класс хранения, используемый для хранения объекта.

Примечание

Ведра каталогов - Ведра каталогов поддерживают только EXPRESS_ONEZONE (класс хранения S3 Express One Zone) в зонах доступности и ONEZONE_IA (класс хранения S3 One Zone-Infrequent Access) в выделенных локальных зонах.

Owner -> (структура)

Владелец объекта

Примечание

Ведра каталогов - Владелец ведра возвращается как владелец объекта.

DisplayName -> (строка)

Контейнер для отображаемого имени владельца. Это значение поддерживается только в следующих регионах Amazon Web Services:

США-Восток (Северная Вирджиния)
США-Запад (Северная Калифорния)
США-Запад (Орегон)
Азия-Тихоокеанский регион (Сингапур)
Азия-Тихоокеанский регион (Сидней)
Азия-Тихоокеанский регион (Токио)
Европа (Ирландия)
Южная Америка (Сан-Паулу)

Примечание

Эта функциональность не поддерживается для ведер каталогов.

ID -> (строка)

Контейнер для идентификатора владельца.

RestoreStatus -> (структура)

Указывает состояние восстановления объекта. Объекты в определенных классах хранения должны быть восстановлены перед тем, как их можно будет получить. Дополнительную информацию об этих классах хранения и о работе с архивированными объектами см. в разделе «Работа с архивированными объектами» в Руководстве пользователя Amazon S3 .

Примечание

Эта функциональность не поддерживается для ведер каталогов. Ведра каталогов поддерживают только EXPRESS_ONEZONE (класс хранения S3 Express One Zone) в зонах доступности и ONEZONE_IA (класс хранения S3 One Zone-Infrequent Access) в выделенных локальных зонах.

IsRestoreInProgress -> (boolean)

Указывает, выполняется ли в настоящее время восстановление объекта. Если восстановление объекта выполняется, заголовок возвращает значение TRUE . Например:

x-amz-optional-object-attributes: IsRestoreInProgress="true"

Если восстановление объекта завершено, заголовок возвращает значение FALSE . Например:

x-amz-optional-object-attributes: IsRestoreInProgress="false", RestoreExpiryDate="2012-12-21T00:00:00.000Z"

Если объект не был восстановлен, нет ответа заголовка.

RestoreExpiryDate -> (временная метка)

Указывает, когда восстановленная копия истечет. Это значение заполняется только в том случае, если объект уже был восстановлен. Например:

x-amz-optional-object-attributes: IsRestoreInProgress="false", RestoreExpiryDate="2012-12-21T00:00:00.000Z"

Name -> (строка)

Имя ведра.

Prefix -> (строка)

Ключи, начинающиеся с указанного префикса.

Delimiter -> (строка)

Приводит к тому, что ключи, содержащие одну и ту же строку между префиксом и первым вхождением разделителя, группируются в один элемент результата в коллекции CommonPrefixes. Эти сгруппированные ключи не возвращаются в другом месте ответа. Каждый сгруппированный результат считается только за один возврат в отношении значения MaxKeys.

MaxKeys -> (целое)

Максимальное количество ключей, возвращаемых в теле ответа.

CommonPrefixes -> (список)

Все ключи (до 1000), сгруппированные в общий префикс, считаются одним возвратом при вычислении количества возвратов.

Ответ может содержать CommonPrefixes только в том случае, если вы указали разделитель.

CommonPrefixes содержит все (если есть) ключи между Prefix и следующим вхождением строки, заданной разделителем.

CommonPrefixes перечисляет ключи, которые действуют как подкаталоги в каталоге, указанном Prefix.

Например, если префикс notes/, а разделитель — косая черта (/), как в notes/summer/july, то общий префикс — notes/summer/. Все ключи, которые группируются в общий префикс, считаются за один возврат при вычислении количества возвратов.

(структура)

Контейнер для всех (если таковые имеются) ключей между префиксом и следующим вхождением строки, заданной разделителем. CommonPrefixes перечисляет ключи, которые действуют как подкаталоги в каталоге, указанном префиксом. Например, если префикс notes/, а разделитель — косая черта (/), как в notes/summer/july, то общий префикс — notes/summer/.

Prefix -> (строка)

Контейнер для указанного общего префикса.

EncodingType -> (строка)

Тип кодирования, используемый Amazon S3 для кодирования ключей объекта в ответе. Ответы кодируются только в UTF-8. Ключ объекта может содержать любые символы Юникода. Однако XML-парсер 1.0 не может обрабатывать определенные символы, например, символы со значением ASCII от 0 до 10. Для символов, которые не поддерживаются в XML 1.0, вы можете добавить этот параметр, чтобы запросить, чтобы Amazon S3 закодировал ключи в ответе. Дополнительную информацию о символах, которых следует избегать в именах ключей объектов, см. в руководстве по наименованию ключей объектов.

Примечание

При использовании типа кодирования URL символы не-ASCII, используемые в имени ключа объекта, будут закодированы в процентах в соответствии со значениями кодов UTF-8. Например, объект test_file(3).png отобразится как test_file%283%29.png.

RequestCharged -> (строка)

Если присутствует, указывает, что запрос был успешно оплачен запросившим.

Примечание

Эта функциональность не поддерживается для ведер каталогов.