ListObjects/ListObjectsV2
Last updated
Last updated
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.
Path parameters
Query parameters
All parameters listed in the table are optional.
Headings
Use only generic headers in your request .
Headings
The response can only contain general headers .
Response codes
For a list of possible answers, see the Answers section .
The successful response contains additional data in XML format, the schema of which is described below.
Data schema
Path parameters
Query parameters
All parameters listed in the table are optional.
Headings
Use only generic headers in your request .
Headings
The response can only contain general headers .
Response codes
For a list of possible answers, see the Answers section .
The successful response contains additional data in XML format, the schema of which is described below.
Data schema
Parameter
Description
bucket
Bucket name.
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 NextContinuationTokenfrom 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 Contentsand 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-tokenis equal to the value of the element NextContinuationTokenfrom 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.
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 Contentsas 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: STANDARDor 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 delimiterand 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-tokento 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.
Parameter
Description
bucket
Bucket name.
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 Contentsand 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 markeris equal to the value of the element NextMarkerfrom 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.
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 markerto 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 Contentsas 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: STANDARDor 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 delimiterand 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.