GET Bucket (List Objects)

After being granted the READ permission for a bucket, you can use this operation to obtain the list of objects in this bucket.

If you specify only the bucket name in the URI of the request (GET /BucketName), OBS returns descriptions about some or all objects (a maximum of 1000 objects) in the bucket.

If you also specify one or more parameters among prefixmarkermax-keys, and delimiter in the request, OBS returns a list of objects as specified. Table 1 describes the parameters in this request.

You can also add the versions parameter to request parameters to list objects of different versions in a bucket.

Request Syntax

GET /? HTTP/1.1
Host: bucketname.obs.cn-north-1.myhwclouds.com
Date: date
Authorization: authorization

Request Syntax for Versions

GET /?versions HTTP/1.1 
Host: bucketname.obs.cn-north-1.myhwclouds.com
Date: date 
Authorization: authorization

Request Parameters

You can specify parameters in this request to list desired objects in a bucket. Table 1 describes the parameters.

Table 1 Request parameters

Parameter

Description

Required or Optional

prefix

Limits the response to objects that begin with the specified prefix.

Type: string

Optional

marker

Indicates the marker to start with when listing objects in a bucket. All objects are listed in alphabetical order.

Type: string

Optional

max-keys

Sets the maximum number of objects (in alphabetical order) returned in the response body. The value ranges from 1 to 1000. If the value is not in this range, 1000 is used by default.

Type: integer

Optional

delimiter

Indicates a character string used to group objects in the bucket. If you specify a prefix, all objects that contain the same string between the prefix and the first occurrence of the delimiter after the prefix are grouped under a single result element called CommonPrefixes.

Type: string

Optional

version-id-marker

Indicates the version ID to start with when listing objects in a bucket. All objects are listed in alphabetical order. This parameter is used together with the key-marker in the response. If the value of version-id-marker is not a version ID specified by key-markerversion-id-marker is invalid.

Type: string

Valid value: object version

Constraint: This parameter cannot be an empty string.

Optional

Request Headers

This request uses common headers. For details, see Common Request Headers.

Request Elements

This request contains no element.

Response Syntax

HTTP/1.1 status_code
Date: date
x-amz-bucket-region: region
Content-Type: application/xml
Content-Length: length

<Response Body>

Response Headers

This response uses common headers. For details, see Common Response Headers.

Response Elements

This response lists the objects in a bucket in XML format. Table 2 describes the elements.

Table 2 Response elements

Element

Description

ListBucketResult

A list of objects in a bucket

Type: XML

Contents

Metadata of the objects

Type: XML

Ancestor: ListBucketResultPa

CommonPrefixes

Group information. If you specify the delimiter parameter in the request, the response contains group information in CommonPrefixes.

Type: XML

Ancestor: ListBucketResult

Delimiter

The delimiter parameter specified in a request

Type: string

Ancestor: ListBucketResult

DisplayName

Name of an object owner

Type: string

Ancestor: ListBucketResult.Contents.Owner

ETag

MD5 value of an object. (If an object is encrypted using server-side encryption, the ETag value is not the MD5 value of the object.)

Type: string

Ancestor: ListBucketResult.Contents

ID

Domain ID of an object owner

Type: string

Ancestor: ListBucketResult.Contents.Owner

IsTruncated

Determines whether the returned list is truncated. The value true indicates that the result is incomplete while false indicates that the result is complete.

Type: Boolean

Ancestor: ListBucketResult

Key

Name of an object

Type: string

Ancestor: ListBucketResult.Contents

LastModified

Date and time when the last modification was made to an object

Type: date

Ancestor: ListBucketResult.Contents

Marker

Start point for listing objects

Type: string

Ancestor: 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

Ancestor: ListBucketResult

MaxKeys

Maximum number of objects returned

Type: string

Ancestor: ListBucketResult

Name

Name of the requested bucket

Type: string

Ancestor: ListBucketResult

Owner

User information, including the domain ID and username

Type: XML

Ancestor: ListBucketResult.Contents

Prefix

Prefix of an object key. Only objects whose names have this prefix are listed. Type: string

Ancestor: ListBucketResult

Size

Number of bytes of an object

Type: string

Ancestor: ListBucketResult.Contents

StorageClass

Storage type of an object

Type: enumeration

Valid values: STANDARD | STANDARD_IA | GLACIER

Ancestor: ListBucketResult.Contents

Table 3 Response elements of listing objects with multiple version IDs

Element

Description

ListVersionsResult

Container for the list of objects (including objects with multiple version IDs)

Type: container

Name

Bucket name

Type: string

Ancestor: ListVersionsResult

Prefix

Prefix of an object name. Only objects whose names have this prefix are listed. Type: string

Ancestor: ListVersionsResult

KeyMarker

Marker to start with when listing objects

Type: string

Ancestor: ListVersionsResult

VersionIdMarker

Object version ID to start with when listing objects

Type: string

Ancestor: 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

Ancestor: 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

Ancestor: ListVersionsResult

MaxKeys

Maximum number of objects returned

Type: string

Ancestor: ListVersionsResult

IsTruncated

Indicates whether the returned list of objects is truncated. The value true indicates that the result is incomplete while false indicates that the result is complete.

Type: Boolean

Ancestor: ListVersionsResult

Version

Container of version information

Type: container

Ancestor: ListVersionsResult

DeleteMarker

Container for objects with deletion markers

Type: container

Ancestor: ListVersionsResult

Key

Object name

Type: string

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

VersionId

Object version ID

Type: string

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

IsLatest

Indicates whether the object is or is not of the latest version. If the element is true, the object is of the latest version.

Type: Boolean

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

LastModified

Date and time when the last modification was made to an object

Type: date

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

ETag

MD5 value of an object

Type: string

Ancestor: ListVersionsResult.Version

Size

Number of bytes of an object

Type: string

Ancestor: ListVersionsResult.Version

Owner

User information, including the domain ID and username

Type: container

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

ID

Domain ID of an object owner

Type: string

Ancestor: ListVersionsResult.Version.Owner | ListVersionsResult.DeleteMarker.Owner

DisplayName

Name of an object owner

Type: string

Ancestor: ListVersionsResult.Version.Owner | ListVersionsResult.Version.Owner

StorageClass

Storage type of an object

Type: enumeration

Ancestor: ListVersionsResult.Version

CommonPrefixes

Group information. If you specify a delimiter in the request, the response contains group information in CommonPrefixes.

Type: container

Ancestor: ListVersionsResult

Prefix

Indicates a different prefix in the group information in CommonPrefixes.

Type: string

Ancestor: ListVersionsResult.CommonPrefixes

Error Responses

No special error responses are returned. For details about error responses, see Table 1.

Registration