listObjects method
Returns a list of bucket objects.
It does not return object contents. To get them, use the get method.
Pagination is used for output. You can get a list of up to 1,000 objects per request. If there are more objects, make multiple consecutive requests.
Note
This method has two versions.
listObjectsV2
: Current version, easier to use.listObjectsV1
: Previous version.
The same URL
, with different query parameters, is used to call both methods. To call listObjectsV2
, use the list-type=2
parameter.
listObjectsV2
Request
GET /{bucket}?list-type=2&continuation-token=ContinuationToken&delimiter=Delimiter&encoding-type=EncodingType&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter HTTP/2
Path parameters
Parameter | Description |
---|---|
bucket |
Bucket name. |
Query parameters
All the parameters listed in the table are optional.
Parameter | Description |
---|---|
continuation-token |
Used to get the next part of the list if all the results don't fit in a single response. To get the next part of the list, use the NextContinuationToken value from the previous answer. |
delimiter |
Delimiter character. If this parameter is specified, Object Storage interprets the key as the path to the file with folders separated by the delimiter character. In response to the request, the user gets a list of filesand foldersin the bucket. Filesare output in the Contents elements, and foldersin the CommonPrefixes elements.If the request also specifies the prefix parameter, Object Storage returns a list of filesand foldersin the prefix . |
encoding-type |
Encoding of server responses. Object Storage can encode responses in the format requested by the client. Possible values: url . |
max-keys |
Maximum number of elements in a response. By default, Object Storage outputs no more than 1,000 Contents and CommonPrefixes elements. This parameter should be used if you need to get less than 1000 elements in a single response.If the number of keys meeting the selection criteria is greater than the number that could fit in the output, the response contains <IsTruncated>true</IsTruncated> .To get all output elements if their number exceeds the max-keys value, make several consecutive requests to Object Storage with the continuation-token parameter, where, for each request, the continuation-token is equal to the value of the NextContinuationToken element from the previous response. |
prefix |
The string to start the key from. Object Storage selects only those keys which start with prefix .Can be used simultaneously with the delimiter parameter. In this case, the output logic is determined by the delimiter parameter. |
start-after |
The key to start the listing from. |
Headers
Use only common request headers in requests.
Response
Headers
Responses can only contain common response headers.
Response codes
For a list of possible responses, see Responses.
A successful response contains additional data in XML format with the schema described below.
Data schema
<?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>
Element | Description |
---|---|
ListBucketResult |
Root element. |
IsTruncated |
Flag indicating whether all results are returned in the response.True : Not all. False : All.Path: /ListBucketResult/IsTruncated . |
Contents |
Object description. The response contains as many Contents elements as there are keys that meet the request criteria.Path: /ListBucketResult/Contents . |
ETag |
MD5 hash of the object. No metadata is included in the hash value calculation. Path: /ListBucketResult/Contents/ETag . |
Key |
Object key. Path: /ListBucketResult/Contents/Key . |
LastModified |
Date and time when the object was last modified. Path: /ListBucketResult/Contents/LastModified . |
Size |
Object size in bytes. Path: /ListBucketResult/Contents/Size . |
StorageClass |
Object storage class: STANDARD , COLD , or ICE Path: /ListBucketResult/Contents/StorageClass . |
Name |
Bucket name. Path: /ListBucketResult/Name . |
Prefix |
Value of the prefix query parameter.Path: /ListBucketResult/Prefix . |
Delimiter |
Value of the delimiter query parameter.Path: /ListBucketResult/Delimiter . |
MaxKeys |
Value of the max-keys query parameter.Path: /ListBucketResult/MaxKeys . |
CommonPrefixes |
Part of the key name that is identified when processing the delimiter and prefix query parameters.Path: /ListBucketResult/CommonPrefixes . |
EncodingType |
Encoding in which Object Storage provides a key in the XML response. Appears if the client passed the encoding-type parameter in the request.Path: /ListBucketResult/EncodingType . |
KeyCount |
The number of keys returned by the request. The number of keys is always less than or equal to MaxKeys .Path: /ContinuationToken/KeyCount . |
ContinuationToken |
Value of the continuation-token query parameter.Path: /ContinuationToken/ContinuationToken . |
NextContinuationToken |
Value to insert in the continuation-token query parameter to get the next part of the list if the entire list does not fit in the current response.This value is returned only if IsTruncated = true .Path: /ListBucketResult/NextContinuationToken . |
StartAfter |
Value of the start-after query parameter.Path: /ListBucketResult/StartAfter . |
listObjectsV1
Request
GET /{bucket}?delimiter=Delimiter&encoding-type=EncodingType&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/2
Path parameters
Parameter | Description |
---|---|
bucket |
Bucket name. |
Query parameters
All the parameters listed in the table are optional.
Parameter | Description |
---|---|
delimiter |
Delimiter character. If this parameter is specified, Object Storage interprets the key as the path to the file with folders separated by the delimiter character. In response to the request, the user gets a list of filesand foldersin the bucket. Filesare output in the Contents elements, and foldersin the CommonPrefixes elements.If the request also specifies the prefix parameter, Object Storage returns a list of filesand foldersin the prefix . |
encoding-type |
Encoding of server responses. Object Storage can encode responses in the format requested by the client. Possible values: url . |
marker |
Key to start the output from. In the resulting output, Object Storage leaves the keys starting from the one following the marker . |
max-keys |
Maximum number of elements in a response. By default, Object Storage outputs no more than 1,000 Contents and CommonPrefixes elements. This parameter should be used if you need to get less than 1000 elements in a single response.If the number of keys meeting the selection criteria is greater than the number that could fit in the output, the response contains <IsTruncated>true</IsTruncated> ..To get all output elements if their number exceeds the max-keys value, make several consecutive requests to Object Storage with the marker parameter, where, for each request, the marker is equal to the value of the NextMarker element from the previous response. |
prefix |
The string to start the key from. Object Storage selects only those keys which start with prefix .Can be used simultaneously with the delimiter parameter. In this case, the output logic is determined by the delimiter parameter. |
Headers
Use only common request headers in requests.
Response
Headers
Responses can only contain common response headers.
Response codes
For a list of possible responses, see Responses.
A successful response contains additional data in XML format with the schema described below.
Data schema
<?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>
Element | Description |
---|---|
ListBucketResult |
Root element. |
IsTruncated |
Flag indicating whether all results are returned in the response.True : Not all. False : All.Path: /ListBucketResult/IsTruncated . |
Marker |
Value of the marker query parameter.Path: /ListBucketResult/Marker . |
NextMarker |
Value to insert in the marker query parameter to get the next part of the list if the entire list does not fit in the current response.Path: /ListBucketResult/NextMarker . |
Contents |
Object description. The response contains as many Contents elements as there are keys that meet the request criteria.Path: /ListBucketResult/Contents . |
ETag |
MD5 hash of the object. No metadata is included in the hash value calculation. Path: /ListBucketResult/Contents/ETag . |
Key |
Object key. Path: /ListBucketResult/Contents/Key . |
LastModified |
Date and time when the object was last modified. Path: /ListBucketResult/Contents/LastModified . |
Size |
Object size in bytes. Path: /ListBucketResult/Contents/Size . |
StorageClass |
Object storage class: STANDARD , COLD , or ICE Path: /ListBucketResult/Contents/StorageClass . |
Name |
Bucket name. Path: /ListBucketResult/Name . |
Prefix |
Value of the prefix query parameter.Path: /ListBucketResult/Prefix . |
Delimiter |
Value of the delimiter query parameter.Path: /ListBucketResult/Delimiter . |
MaxKeys |
Value of the max-keys query parameter.Path: /ListBucketResult/MaxKeys . |
CommonPrefixes |
Part of the key name that is identified when processing the delimiter and prefix query parameters.Path: /ListBucketResult/CommonPrefixes . |
EncodingType |
Encoding in which Object Storage provides a key in the XML response. Appears if the client passed the encoding-type parameter in the request.Path: /ListBucketResult/EncodingType . |