ListObjects/ListObjectsV2
Returns a list of objects in a bucket.
When issuing, pagination is used; in one request, you can get a list of no longer than 1000 objects. If there are more objects, then it is necessary to execute several queries in a row.
Note
This method has two versions.
listObjectsV2
- up-to-date version, more convenient to use.listObjectsV1
- previous version.
To call both methods, the same is used
URL
, but it differs in the query parameter. To invoke listObjectsV2
, use the parameter list-type=2
.GET /{bucket}?list-type=2&continuation-token=ContinuationToken&delimiter=Delimiter&encoding-type=EncodingType&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter HTTP/1.1
Path parameters
Parameter | Description |
bucket | Bucket name. |
Query parameters
All parameters listed in the table are optional.
Parameter | Description |
continuation-token | Used to get the next part of the list if all the results do not fit into one answer.
To get the next part of the list, use the value NextContinuationToken from the previous answer. |
delimiter | Separator character.
If specified, Object Storage treats the key as a file path, where directories are separated by a character delimiter . In response to the request, the user will see a list of files and directories in the bucket. Files will be displayed in items Contents , and directories in items CommonPrefixes .
If a parameter is also specified in the request prefix , then Object Storage will return a list of files and directories in the directory prefix . |
encoding-type | Server response encoding.
Object Storage, at the request of the client, can encode the response in the required form.
Possible values: url . |
max-keys | The maximum number of items in a response.
By default, Object Storage yields no more than 1000 items Contents and CommonPrefixes . This parameter should be used if you need to get less than 1000 items in one response.
If more keys fall under the selection criteria than fit in the search results, then the answer contains <IsTruncated>true</IsTruncated> .
To get all the elements of the issue, if there are more of them max-keys , it is necessary to perform several consecutive requests to Object Storage with a parameter continuation-token , where for each request continuation-token is equal to the value of the element NextContinuationToken from the previous response. |
prefix | The string that the key should start with.
Object Storage will only select keys that start with prefix .
It can be used simultaneously with the parameter delimiter . In this case, the output logic is determined by the parameter delimiter . |
start-after | The key to start the listing with. |
Headings
Headings
Response codes
The successful response contains additional data in XML format, the schema of which is 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 | A flag indicating whether all results were returned in this response.
True - everything. False - Not all.
Path: /ListBucketResult/IsTruncated . |
Contents | Description of the object.
The response will contain as many elements Contents as the keys match the request conditions.
Path: /ListBucketResult/Contents . |
ETag | MD5 hash of the object. Metadata is not included in the hash calculation.
Path: /ListBucketResult/Contents/ETag . |
Key | Object key.
Path: /ListBucketResult/Contents/Key . |
LastModified | The date and time the object was last modified.
Path: /ListBucketResult/Contents/LastModified . |
Size | The size of the object in bytes.
Path: /ListBucketResult/Contents/Size . |
StorageClass | Object storage class: STANDARD or COLD .
Path: /ListBucketResult/Contents/StorageClass . |
Name | Bucket name.
Path: /ListBucketResult/Name . |
Prefix | The value of the query parameter prefix .
Path: /ListBucketResult/Prefix . |
Delimiter | The value of the query parameter delimiter .
Path: /ListBucketResult/Delimiter . |
MaxKeys | The value of the query parameter max-keys .
Path: /ListBucketResult/MaxKeys . |
CommonPrefixes | The part of the key name that is determined when processing query parameters delimiter and prefix .
Path: /ListBucketResult/CommonPrefixes . |
EncodingType | The encoding in which Object Storage represents the key in the XML response.
Appears if the client passed a parameter when requested encoding-type .
Path: /ListBucketResult/EncodingType . |
KeyCount | The number of keys returned by the query.
The number of keys will always be less than or equal MaxKeys .
Path: /ContinuationToken/KeyCount . |
ContinuationToken | The value of the query parameter continuation-token .
Path: /ContinuationToken/ContinuationToken . |
NextContinuationToken | The value that must be substituted into the query parameter continuation-token to get the next part of the list, if the entire list does not fit into the current response.
Refundable only if IsTruncated = true .
Path: /ListBucketResult/NextContinuationToken . |
StartAfter | The value of the query parameter start-after .
Path: /ListBucketResult/StartAfter . |
GET /{bucket}?delimiter=Delimiter&encoding-type=EncodingType&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/1.1
Path parameters
Parameter | Description |
bucket | Bucket name. |
Query parameters
All parameters listed in the table are optional.
Parameter | Description |
delimiter | Separator character.
If specified, Object Storage treats the key as a file path, where directories are separated by a character delimiter . In response to the request, the user will see a list of files and directories in the bucket. Files will be displayed in items Contents , and directories in items CommonPrefixes .
If a parameter is also specified in the request prefix , then Object Storage will return a list of files and directories in the directory prefix . |
encoding-type | Server response encoding.
Object Storage, at the request of the client, can encode the response in the required form.
Possible values: url . |
marker | The key from which the issuance will begin.
In the resulting output, Object Storage will leave the keys starting from the next one after marker . |
max-keys | The maximum number of items in a response.
By default, Object Storage yields no more than 1000 items Contents and CommonPrefixes . This parameter should be used if you need to get less than 1000 items in one response.
If more keys fall under the selection criteria than fit in the search results, then the answer contains <IsTruncated>true</IsTruncated> .
To get all the elements of the issue, if there are more of them max-keys , it is necessary to perform several consecutive requests to Object Storage with a parameter marker , where for each request marker is equal to the value of the element NextMarker from the previous response. |
prefix | The string that the key should start with.
Object Storage will only select keys that start with prefix .
It can be used simultaneously with the parameter delimiter . In this case, the output logic is determined by the parameter delimiter . |
Headings
Headings
Response codes
The successful response contains additional data in XML format, the schema of which is 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 | A flag indicating whether all results were returned in this response.
True - everything. False - Not all.
Path: /ListBucketResult/IsTruncated . |
Marker | The value of the query parameter marker .
Path: /ListBucketResult/Marker . |
NextMarker | The value that must be substituted into the query parameter marker to get the next part of the list, if the entire list does not fit into the current response.
Path: /ListBucketResult/NextMarker . |
Contents | Description of the object.
The response will contain as many elements Contents as the keys match the request conditions.
Path: /ListBucketResult/Contents . |
ETag | MD5 hash of the object. Metadata is not included in the hash calculation.
Path: /ListBucketResult/Contents/ETag . |
Key | Object key.
Path: /ListBucketResult/Contents/Key . |
LastModified | The date and time the object was last modified.
Path: /ListBucketResult/Contents/LastModified . |
Size | The size of the object in bytes.
Path: /ListBucketResult/Contents/Size . |
StorageClass | Object storage class: STANDARD or COLD .
Path: /ListBucketResult/Contents/StorageClass . |
Name | Bucket name.
Path: /ListBucketResult/Name . |
Prefix | The value of the query parameter prefix .
Path: /ListBucketResult/Prefix . |
Delimiter | The value of the query parameter delimiter .
Path: /ListBucketResult/Delimiter . |
MaxKeys | The value of the query parameter max-keys .
Path: /ListBucketResult/MaxKeys . |
CommonPrefixes | The part of the key name that is determined when processing query parameters delimiter and prefix .
Path: /ListBucketResult/CommonPrefixes . |
EncodingType | The encoding in which Object Storage represents the key in the XML response.
Appears if the client passed a parameter when requested encoding-type .
Path: /ListBucketResult/EncodingType . |
Last modified 2yr ago