Get Bucket (List Object)

Last Updated: Sep 12, 2017

The Get Bucket operation can be used to list all of the object information in a bucket.

Request syntax

  1. GET / HTTP/1.1
  2. Host: BucketName.oss-cn-hangzhou.aliyuncs.com
  3. Date: GMT Date
  4. Authorization: SignatureValue

Request parameters

When you initiate a GetBucket (ListObject) request, you can use prefix, marker, delimiter, and max-keys to prescribe a limit to the list to return partial results. Besides, encoding-type can be used to encode the following elements in the returned results: delimiter, marker, prefix, NextMarker, and key.

Name Description
delimiter A character used to group object names. All those objects whose names contain the specified prefix and behind which the delimiter occurs for the first time act as a group of elements - CommonPrefixes.
Data type: string
Default value: None
marker Sets the returned results to begin from the first entry after the marker in alphabetical order.
Data type: string
Default value: None
max-keys Limits the maximum number of objects returned for one request. If not specified, the default value is 100. The max-keys value cannot exceed 1000.
Data type: string
Default value: 100
prefix Limits that the returned object key must be prefixed accordingly. Note that the keys returned from queries using a prefix will still contain the prefix.
Data type: string
Default value: None
encoding-type Specifies the encoding of the returned content and the encoding type. Parameters delimiter, marker, prefix, NextMarker, and key use UTF-8 characters, but the XML 1.0 Standard does not support parsing certain control characters, such as characters with ASCII values ranging from 0 to 10. If some elements in the returned results contain characters that are not supported by the XML 1.0 Standard, encoding-type can be specified to encode these elements, such as delimiter, marker, prefix, NextMarker, and key.
Data type: string
Default value: None; optional value: URL

Response elements

Name Description
Contents Container used for saving every returned object meta.
Type: container
Parent node: ListBucketResult
CommonPrefixes If the delimiter parameter is specified in the request, the response returned by the OSS contains the CommonPrefixes element. This element indicates the set of objects which end with a delimiter and have a common prefix.
Type: string
Parent node: ListBucketResult
Delimiter A character used to group object names. All those objects whose names contain the specified prefix and behind which the delimiter occurs for the first time act as a group of elements - CommonPrefixes.
Type: string
Parent node: ListBucketResult
EncodingType Encoding type for the returned results If encoding-type is specified in a request, the following elements in the returned results will be encoded: delimiter, marker, prefix, NextMarker, and key.
Type: string
Parent node: ListBucketResult
DisplayName Name of the object owner.
Type: string
Parent node: ListBucketResult.Contents.Owner
ETag The ETag (entity tag) is created when an object is generated and is used to indicate the content of the object. For an object created by a Put Object request, the value of ETag is the value of MD5 in the content of the object. For an object created in other manners, the value of ETag is the UUID in the content of the object. The value of ETag can be used to check whether the content of the object is changed. It is not recommended that the ETag be used as the MD5 value of the object content to verify data integrity.
Type: string
Parent node: ListBucketResult.Contents
ID User ID of the bucket owner.
Type: string
Parent node: ListBucketResult.Contents.Owner
IsTruncated Indicates whether all results have been returned; “true” means that not all results are returned this time; “false” means that all results are returned this time.
Type: enumerated string
Valid values: “true” and “false”
Parent node: ListBucketResult
Key Key of an object
Type: string
Parent node: ListBucketResult.Contents
LastModified Time when the object is last modified.
Type: time
Parent node: ListBucketResult.Contents
ListBucketResult Container for storing the results of the “Get Bucket” request
Type: container; subnodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, and Contents
Parent node: None
Marker Marks the origin of the current Get Bucket (List Object) request.
Type: string
Parent node: ListBucketResult
MaxKeys The maximum number of returned results in response to the request.
Type: string
Parent node: ListBucketResult
Name Name of a bucket
Type: string
Parent node: ListBucketResult
Owner Container used for saving the information about the bucket owner.
Type: container; subnodes: DisplayName and ID
Parent node: ListBucketResult
Prefix Starting prefix for the current results of query.
Type: string
Parent node: ListBucketResult
Size Number of bytes of the object.
Type: string
Parent node: ListBucketResult.Contents
StorageClass Indicates Object storage type. “Standard”, “IA”, and “Archive” types are available. (The “Archive” type is only available in some regions currently.)
Type: string
Parent node: ListBucketResult.Contents

Detail analysis

  • The custom meta in the object is not returned during the GetBucket request.
  • If the bucket to be accessed does not exist, or if you attempt to access a bucket which cannot be created due to non-standard naming, Error 404 Not Found with the error code “NoSuchBucket” is returned.
  • If you have no permission to access the bucket, the system returns Error 403 Forbidden with the error code “AccessDenied”.
  • If listing cannot be completed at one time because of the max-keys setting, a <NextMarker> is appended to the returned result, prompting that this can be taken as a marker for continued listing. The value in NextMarker is still in the list result.
  • During a condition query, even if the marker does not exist in the list actually, what is returned is printed starting from the next to what conforms to the marker letter sorting. If the max-keys value is less than 0 or greater than 1000, error 400 Bad Request is returned. The error code is “InvalidArgument”.
  • If the prefix, marker, or delimiter parameters do not meet the length requirement, 400 Bad Request is returned. The error code is “InvalidArgument”.
  • The prefix and marker parameters are used to achieve display by pages, and the parameter length must be less than 1024 bytes.
  • Setting a prefix as the name of a folder enumerates the files starting with this prefix, recursively returning all files and subfolders in this folder. If, in addition, we set the Delimiter as “/“, the returned values will list the files in the folder and the subfolders will be returned in the CommonPrefixes section. Recursive files and folders in subfolders will not be displayed. For example, a bucket has the following three objects: fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. If the prefix is set to “fun/“, three objects are returned. If the delimiter is set to “/“ additionally, file “fun/test.jpg” and prefix “fun/movie/“ are returned. That is, the folder logic is achieved.

Scenario example

Four objects are available in the bucket “my_oss” and are respectively named as:

  • oss.jpg
  • fun/test.jpg
  • fun/movie/001.avi
  • fun/movie/007.avi

Example

Request example:

  1. GET / HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

Return example:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 1866
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
  10. <Name>oss-example</Name>
  11. <Prefix></Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter></Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/movie/001.avi</Key>
  18. <LastModified>2012-02-24T08:43:07.000Z</LastModified>
  19. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user-example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <Contents>
  29. <Key>fun/movie/007.avi</Key>
  30. <LastModified>2012-02-24T08:43:27.000Z</LastModified>
  31. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  32. <Type>Normal</Type>
  33. <Size>344606</Size>
  34. <StorageClass>Standard</StorageClass>
  35. <Owner>
  36. <ID>00220120222</ID>
  37. <DisplayName>user-example</DisplayName>
  38. </Owner>
  39. </Contents>
  40. <Contents>
  41. <Key>fun/test.jpg</Key>
  42. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  43. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  44. <Type>Normal</Type>
  45. <Size>344606</Size>
  46. <StorageClass>Standard</StorageClass>
  47. <Owner>
  48. <ID>00220120222</ID>
  49. <DisplayName>user-example</DisplayName>
  50. </Owner>
  51. </Contents>
  52. <Contents>
  53. <Key>oss.jpg</Key>
  54. <LastModified>2012-02-24T06:07:48.000Z</LastModified>
  55. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  56. <Type>Normal</Type>
  57. <Size>344606</Size>
  58. <StorageClass>Standard</StorageClass>
  59. <Owner>
  60. <ID>00220120222</ID>
  61. <DisplayName>user-example</DisplayName>
  62. </Owner>
  63. </Contents>
  64. </ListBucketResult>

Example of a request containing the prefix parameter:

  1. GET /?prefix=fun HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

Return example:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 1464
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
  10. <Name>oss-example</Name>
  11. <Prefix>fun</Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter></Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/movie/001.avi</Key>
  18. <LastModified>2012-02-24T08:43:07.000Z</LastModified>
  19. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user_example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <Contents>
  29. <Key>fun/movie/007.avi</Key>
  30. <LastModified>2012-02-24T08:43:27.000Z</LastModified>
  31. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  32. <Type>Normal</Type>
  33. <Size>344606</Size>
  34. <StorageClass>Standard</StorageClass>
  35. <Owner>
  36. <ID>00220120222</ID>
  37. <DisplayName>user_example</DisplayName>
  38. </Owner>
  39. </Contents>
  40. <Contents>
  41. <Key>fun/test.jpg</Key>
  42. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  43. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  44. <Type>Normal</Type>
  45. <Size>344606</Size>
  46. <StorageClass>Standard</StorageClass>
  47. <Owner>
  48. <ID>00220120222</ID>
  49. <DisplayName>user_example</DisplayName>
  50. </Owner>
  51. </Contents>
  52. </ListBucketResult>

Example of a request containing parameters prefix and delimiter:

  1. GET /?prefix=fun/&delimiter=/ HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY1vY=

Return example:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 712
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
  10. <Name>oss-example</Name>
  11. <Prefix>fun/</Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter>/</Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/test.jpg</Key>
  18. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  19. <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE"</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user_example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <CommonPrefixes>
  29. <Prefix>fun/movie/</Prefix>
  30. </CommonPrefixes>
  31. </ListBucketResult>
Thank you! We've received your feedback.