Listing Objects in a Bucket
Functions
This operation lists objects in a bucket. To use this operation, you must have the permission to read the bucket.
If you specify only the bucket name in the request, OBS returns descriptions for some or all of the objects (a maximum of 1,000 objects) in the bucket. If you also specify one or more parameters among prefix, marker, max-keys, and delimiter in the request, OBS returns a list of objects based on the semantics specified in Table 1.
You can also add the versions parameter to the request to list multiple versions of an object in a bucket.
Request Syntax
1 2 3 4 |
GET / HTTP/1.1 Host: bucketname.obs.region.myhuaweicloud.eu Date: date Authorization: authorization |
Request Syntax (for multi-version objects)
1 2 3 4 |
GET /?versions HTTP/1.1 Host: bucketname.obs.region.myhuaweicloud.eu Date: date Authorization: authorization |
Request Parameters
This request uses parameters to list some objects in a bucket. Table 1 describes the parameters.
Parameter |
Description |
Mandatory |
---|---|---|
prefix |
Lists objects that begin with the specified prefix. Type: string |
No |
marker |
Specifies a marker when listing objects in a bucket. With a marker configured, objects after this marker will be returned in alphabetical order. This field is used only for listing objects. Type: string |
No |
max-keys |
Specifies the maximum number (from 1 to 1000) of objects returned (in alphabetical order) in the response. If the value is beyond this range, only 1,000 objects are returned by default. Type: integer |
No |
delimiter |
Separator used to group object names. If a prefix is specified, objects with the same string from the prefix to the first delimiter are grouped into one CommonPrefixes. If no prefix is specified, objects with the same string from the first character to the first delimiter are grouped into one CommonPrefixes. For example, there are three objects (abcd, abcde, and bbcde) in a bucket. If delimiter is set to d and prefix is set to a, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix. If only delimiter is set to d, objects abcd and abcde are grouped into a CommonPrefixes with abcd as the prefix, and bbcde is grouped separately into another CommonPrefixes with bbcd as the prefix. For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, and subdirectories are also listed. In big data scenarios, parallel file systems usually have deep directory levels and each directory has a large number of files. In such case, you are advised to configure [delimiter=/] to list the content in the current directory, but not list subdirectories, thereby improving the listing efficiency. Type: string |
No |
key-marker |
Position to start with when objects are listed. This field is used only for listing versioned objects. Type: string Valid value: value of NextKeyMarker in the response body of the last request |
No |
version-id-marker |
This parameter applies only when versioning is enabled. Specifies the version ID to start with when objects in a bucket are listed. Objects are listed in alphabetical order (a maximum of 1,000 objects are displayed at a time). This parameter is used together with the key-marker in the request. If the value of version-id-marker is not a version ID specified by key-marker, version-id-marker is invalid. Type: string Valid value: object version ID, that is, the value of NextVersionIdMarker in the response body of the last request |
No |
Request Headers
This request uses common request headers. For details, see Table 3.
Request Elements
This request contains no elements.
Response Syntax
1 2 3 4 5 6 |
HTTP/1.1 status_code Date: date x-obs-bucket-location: region Content-Type: application/xml Content-Length: length <Response Body> |
Response Headers
The response to the request uses common headers. For details, see Table 1.
Response Elements
This response lists objects in XML format. Specific elements are described in Table 2.
Element |
Description |
---|---|
ListBucketResult |
A list of objects in a bucket Type: XML |
Contents |
Object metadata Type: XML Parent: ListBucketResult |
CommonPrefixes |
Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes. Type: XML Parent: ListBucketResult |
Delimiter |
The delimiter parameter specified in a request Type: string Parent: ListBucketResult |
ETag |
The MD5 digest of an object. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. For example, if the ETag value is A when an object is uploaded, but this value has changed to B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the object content, rather than the object metadata. An uploaded object or copied object has a unique ETag after being encrypted using MD5. (If the object is encrypted on the server side, the ETag value is not the MD5 digest of the object, but the unique identifier calculated through server-side encryption.) Type: string Parent: ListBucketResult.Contents |
Type |
Object type. This parameter is returned when the object type is not Normal. Type: string Parent: ListBucketResult.Contents |
ID |
Domain ID of the object owner Type: string Parent: ListBucketResult.Contents.Owner |
IsTruncated |
Determines whether the returned list of objects is truncated. The value true indicates that the list was truncated and false indicates that the list was not truncated. Type: boolean Parent: ListBucketResult |
Key |
Object name Type: string Parent: ListBucketResult.Contents |
LastModified |
Time (UTC) when an object was last modified Type: date Parent: ListBucketResult.Contents |
Marker |
Marker for the position from which objects in a bucket will be listed Type: string Parent: ListBucketResult |
NextMarker |
A marker for the last returned object in the list. NextMarker is returned when not all the objects are listed. You can set the Marker value to list the remaining objects in follow-up requests. Type: string Parent: ListBucketResult |
MaxKeys |
Maximum number of objects returned Type: string Parent: ListBucketResult |
Name |
Name of the requested bucket Type: string Parent: ListBucketResult |
Owner |
User information, including the domain ID and name of the object owner Type: XML Parent: ListBucketResult.Contents |
DisplayName |
Name of the object owner Type: string Parent: ListBucketResult.Contents.Owner |
Prefix |
Prefix of an object name. Only objects whose names have this prefix are listed. Type: string Parent: ListBucketResult |
Size |
Object size in bytes Type: string Parent: ListBucketResult.Contents |
StorageClass |
Storage class of an object Type: string Value options: STANDARD, WARM, COLD Parent: ListBucketResult.Contents |
Element |
Description |
---|---|
ListVersionsResult |
Container for the list of objects (including objects with multiple version IDs) Type: container |
Name |
Bucket name Type: string Parent: ListVersionsResult |
Prefix |
Prefix of an object name. Only objects whose names have this prefix are listed. Type: string Parent: ListVersionsResult |
KeyMarker |
Marker for the object key from which objects will be listed Type: string Parent: ListVersionsResult |
VersionIdMarker |
Object version ID to start with when objects are listed Type: string Parent: ListVersionsResult |
NextKeyMarker |
Key marker for the last returned object in the list. NextKeyMarker is returned when not all the objects are listed. You can set the KeyMarker value to list the remaining objects in follow-up requests. Type: string Parent: ListVersionsResult |
NextVersionIdMarker |
Version ID marker for the last returned object in the list. NextVersionIdMarker is returned when not all the objects are listed. You can set the VersionIdMarker value to list the remaining objects in follow-up requests. Type: string Parent: ListVersionsResult |
MaxKeys |
Maximum number of objects returned Type: string Parent: ListVersionsResult |
IsTruncated |
Indicates whether the returned list of objects is truncated. The value true indicates that the list was truncated and false indicates that the list was not truncated. Type: boolean Parent: ListVersionsResult |
Version |
Container of version information Type: container Parent: ListVersionsResult |
DeleteMarker |
Container for objects with delete markers Type: container Parent: ListVersionsResult |
Key |
Object name Type: string Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
VersionId |
Object version ID Type: string Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
IsLatest |
Whether the object is the latest version. If the parameter value is true, the object is the latest version. Type: boolean Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
LastModified |
Time (UTC) when an object was last modified Type: date Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
ETag |
Base64-encoded 128-bit MD5 digest of an object. ETag is the unique identifier of the object content. It can be used to determine whether the object content is changed. The actual ETag is the hash value of the object. For example, if the ETag value is A when an object is uploaded, but this value has changed to B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the object content, rather than the object metadata. An uploaded object or copied object has a unique ETag after being encrypted using MD5. Type: string Parent: ListVersionsResult.Version |
Type |
Object type. This parameter is returned when the object type is not Normal. Type: string Parent: ListVersionsResult.Version |
Size |
Object size in bytes Type: string Parent: ListVersionsResult.Version |
Owner |
User information, including the domain ID and name of the object owner Type: container Parent: ListVersionsResult.Version | ListVersionsResult.DeleteMarker |
ID |
Domain ID of the object owner Type: string Parent: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner |
DisplayName |
Name of the object owner Type: string Parent: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner |
StorageClass |
Storage class of an object Type: string Value options: STANDARD, WARM, COLD Parent: ListVersionsResult.Version |
CommonPrefixes |
Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes. Type: container Parent: ListVersionsResult |
Prefix |
Indicates a different prefix in the group information in CommonPrefixes. Type: string Parent: ListVersionsResult.CommonPrefixes |
Error Responses
No special error responses are returned. For details about error responses, see Table 2.
Sample Request: Listing All Objects
1 2 3 4 5 6 |
GET / HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.eu Accept: */* Date: WED, 01 Jul 2015 02:28:25 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:KiyoYze4pmRNPYfmlXBfRTVxt8c= |
Sample Response: Listing All Objects
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
HTTP/1.1 200 OK Server: OBS x-obs-request-id: BF260000016435D34E379ABD93320CB9 x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSXiN7GPL/yXM6OSBaYCUV1zcY5OelWp Content-Type: application/xml Date: WED, 01 Jul 2015 02:23:30 GMT Content-Length: 586 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListBucketResult xmlns="http://obs.eu-west-101.myhuaweicloud.eu/doc/2015-06-30/"> <Name>examplebucket</Name> <Prefix/> <Marker/> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>object001</Key> <LastModified>2015-07-01T00:32:16.482Z</LastModified> <ETag>"2fa3bcaaec668adc5da177e67a122d7c"</ETag> <Size>12041</Size> <Owner> <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID> <DisplayName>ObjectOwnerName</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> </ListBucketResult> |
Sample Request: Listing Some Objects
Assume that you have a bucket examplebucket that contains objects newfile, obj001, obj002, and obs001. If you want to list only object obj002, the request message is as follows:
GET /?marker=obj001&prefix=obj HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.eu Accept: */* Date: WED, 01 Jul 2015 02:28:25 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:KiyoYze4pmRNPYfmlXBfRTVxt8c=
Sample Response: Listing Some Objects
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
HTTP/1.1 200 OK Server: OBS x-obs-request-id: BF260000016435D758FBA857E0801874 x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShn/xAyk/xHBX6qgGSB36WXrbco0X80 Content-Type: application/xml Date: WED, 01 Jul 2015 02:29:48 GMT Content-Length: 707 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListBucketResult xmlns="http://obs.eu-west-101.myhuaweicloud.eu/doc/2015-06-30/"> <Name>examplebucket</Name> <Prefix>obj</Prefix> <Marker>obj001</Marker> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>obj002</Key> <LastModified>2015-07-01T02:11:19.775Z</LastModified> <ETag>"a72e382246ac83e86bd203389849e71d"</ETag> <Size>9</Size> <Owner> <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID> <DisplayName>ObjectOwnerName</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Contents> </ListBucketResult> |
Sample Request: Listing Some Objects
Assume that bucket examplebucket contains three objects: abcd, abcde, and bbcde. Set the prefix and the delimiter to a and d respectively to define a CommonPrefixes of abcd. The specific request format is as follows:
GET /?prefix=a&delimiter=d HTTP/1.1 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4= User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.com Date: WED, 01 Jul 2015 02:37:22 GMT Content-Type: application/xml;charset=UTF-8
Sample Response: Listing Some Objects
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSsokG49mPTa0cU5U/4gjFYLmYPgfYs/ x-obs-request-id: 0000018A2A563686D2C61543407D6ABF Server: OBS x-obs-bucket-location: region Content-Length: 333 Date: WED, 01 Jul 2015 02:37:22 GMT Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListBucketResult xmlns="http://obs.myhwclouds.com/doc/2015-06-30/"> <Name>examplebucket</Name> <Prefix>a</Prefix> <Marker> </Marker> <MaxKeys>1000</MaxKeys> <Delimiter>d</Delimiter> <IsTruncated>false</IsTruncated> <CommonPrefixes> <Prefix>abcd</Prefix> </CommonPrefixes> </ListBucketResult>
Sample Request: Listing Object Versions
1 2 3 4 5 6 |
GET /?versions HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.eu Accept: */* Date: WED, 01 Jul 2015 02:29:45 GMT Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iZeDESIMxBK2YODk7vIeVpyO8DI= |
Sample Response: Listing Object Versions
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
HTTP/1.1 200 OK Server: OBS x-obs-request-id: BF260000016435D758FBA857E0801874 x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCShn/xAyk/xHBX6qgGSB36WXrbco0X80 Content-Type: application/xml Date: WED, 01 Jul 2015 02:29:48 GMT Content-Length: 707 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListVersionsResult xmlns="http://obs.eu-west-101.myhuaweicloud.eu/doc/2015-06-30/"> <Name>bucket02</Name> <Prefix/> <KeyMarker/> <VersionIdMarker/> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Version> <Key>object001</Key> <VersionId>00011000000000013F16000001643A22E476FFFF9046024ECA3655445346485a</VersionId> <IsLatest>true</IsLatest> <LastModified>2015-07-01T00:32:16.482Z</LastModified> <ETag>"2fa3bcaaec668adc5da177e67a122d7c"</ETag> <Size>12041</Size> <Owner> <ID>b4bf1b36d9ca43d984fbcb9491b6fce9</ID> <DisplayName>ObjectOwnerName</DisplayName> </Owner> <StorageClass>STANDARD</StorageClass> </Version> </ListVersionsResult> |
Sample Request: Listing Objects (Including Archive Objects) in a Bucket
GET / HTTP/1.1 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4= User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.com Date: WED, 01 Jul 2015 02:37:22 GMT Content-Type: application/xml;charset=UTF-8
Sample Response: Listing Objects (Including Archive Objects) in a Bucket
HTTP/1.1 200 OK x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSWqA48YKdA2aExVAgcpwubHQO5wd9ww x-obs-request-id: 0000018A2A5FE372D308213442F9065F Server: OBS x-obs-bucket-location: region Content-Length: 497 Date: WED, 01 Jul 2015 02:37:22 GMT Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ListBucketResult xmlns="http://obs.myhwclouds.com/doc/2015-06-30/"> <Name>examplebucket</Name> <Prefix> </Prefix> <Marker> </Marker> <MaxKeys>1000</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>abcd.txt</Key> <LastModified>2014-08-25T01:47:00.838Z</LastModified> <ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag> <Size>0</Size> <Owner> <ID>d029cb567d464a93pdl9v800575ee4cf</ID> </Owner> <StorageClass>COLD</StorageClass> </Contents> </ListBucketResult>
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.