Help Center/ Object Storage Service/ SDK Reference/ Go/ Buckets (SDK for Go)/ Listing Object Versions in a Bucket (SDK for Go)
Updated on 2024-06-21 GMT+08:00

Listing Object Versions in a Bucket (SDK for Go)

Function

This API returns some or all of the object versions in a bucket. You can use parameters such as the prefix, number of returned object versions, and start position to return the object versions that meet specified criteria. Returned object versions are listed in alphabetical order.

Restrictions

Method

func (obsClient ObsClient) ListVersions(input *ListVersionsInput) (output *ListVersionsOutput, err error)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

input

*ListVersionsInput

Yes

Explanation:

Input parameters for listing object versions in a bucket. For details, see Table 2.

Table 2 ListVersionsInput

Parameter

Type

Mandatory (Yes/No)

Description

Bucket

string

Yes

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

KeyMarker

string

No

Explanation:

Object name to start with when listing object versions in a bucket. All object versions following the value specified by this parameter are listed in alphabetical order by object name.

Restrictions:

This parameter is only used for listing objects with multiple versions.

Value range:

Value of NextKeyMarker in the response body of the last request

Default value:

None

VersionIdMarker

string

No

Explanation:

This parameter is used together with KeyMarker. Version ID you want to start listing from. All object versions following the value specified by this parameter are listed in alphabetical order by object name and version ID. KeyMarker specifies the object name, and VersionIdMarker specifies the version ID of the specified object.

Restrictions:

  • This parameter is only used for listing objects with multiple versions.
  • If the object specified by KeyMarker does not have the version specified by VersionIdMarker, this parameter is invalid.

Value range:

Object version ID, that is, the value of NextVersionIdMarker in the response body of the last request

Default value:

None

Prefix

string

No

Explanation:

Name prefix that the objects to be listed must contain

Assume that you have the following objects: logs/day1, logs/day2, logs/day3, and ExampleObject.jpg. If you specify logs/ as the prefix, logs/day1, logs/day2, and logs/day3 will be returned. If you leave this parameter blank, all objects in the bucket will be returned.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

MaxKeys

int

No

Explanation:

The maximum number of objects returned in the response in alphabetical order

Value range:

The value ranges from 1 to 1000. If the specified value is beyond this range, only 1,000 objects are returned.

Default value:

1000

Delimiter

string

No

Explanation:

Object names are grouped by this parameter, which is often used with Prefix. 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.

Assume that a bucket has objects abcd, abcde, and bbcde in it. 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 current 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.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

EncodingType

string

No

Explanation:

Encoding type for some elements in the response. If Delimiter, KeyMarker, Prefix, CommonPrefixes, NextKeyMarker, and Key contain control characters that are not supported by the XML 1.0 standard, you can use EncodingType to encode Delimiter, KeyMarker, Prefix, CommonPrefixes, NextKeyMarker, and Key in the response.

Value range:

Value option: url

Default value:

None. If you leave this parameter blank, encoding is not applied to elements.

Responses

Table 3 List of returned results

Parameter

Type

Description

output

*ListVersionsOutput

Explanation:

Returned parameters for listing object versions in a bucket. For details, see Table 4.

err

error

Explanation:

Error messages returned by the API

Table 4 ListVersionsOutput

Parameter

Type

Description

StatusCode

int

Explanation:

HTTP status code

Value range:

A status code is a group of digits that can be 2xx (indicating successes) or 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code.

Default value:

None

RequestId

string

Explanation:

Request ID returned by the OBS server

Default value:

None

ResponseHeaders

map[string][]string

Explanation:

HTTP response headers

Default value:

None

Location

string

Explanation:

Region where a bucket is located

Restrictions:

If the endpoint used is obs.myhuaweicloud.eu, this parameter is not required. If any other endpoints are used, this parameter is required.

Default value:

If obs.myhuaweicloud.eu is used as the endpoint and no region is specified, eu-west-101 (the EU-Dublin region) is used by default.

Name

string

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Value range:

The value must contain 3 to 63 characters.

Prefix

string

Explanation:

Object name prefix, which is consistent with that set in the request

Assume that you have the following objects: logs/day1, logs/day2, logs/day3, and ExampleObject.jpg. If you specify logs/ as the prefix, logs/day1, logs/day2, and logs/day3 will be returned. If you leave this parameter blank, all objects in the bucket will be returned.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

KeyMarker

string

Explanation:

Object name to start listing from. All object versions following the value specified by this parameter are listed in alphabetical order by object name.

Restrictions:

This parameter is only used for listing objects with multiple versions.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

VersionIdMarker

string

Explanation:

Version ID of the object specified by keyMarker.

This parameter is used together with KeyMarker. All object versions following the value specified by this parameter are listed in alphabetical order by object name and version ID. KeyMarker specifies the object name, and VersionIdMarker specifies the version ID of the specified object.

Restrictions:

  • This parameter is only used for listing objects with multiple versions.
  • If the object specified by KeyMarker does not have the version specified by VersionIdMarker, this parameter is invalid.

Value range:

The value must contain 32 characters.

Default value:

None

Delimiter

string

Explanation:

Object names are grouped by this parameter, which is often used with Prefix. 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.

Assume that a bucket has objects abcd, abcde, and bbcde in it. 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 current 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.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

MaxKeys

int

Explanation:

Maximum number of objects to list The maximum number of objects returned in the response in alphabetical order

Value range:

The value ranges from 1 to 1000. If the specified value is beyond this range, only 1,000 objects are returned.

Default value:

1000

IsTruncated

bool

Explanation:

Whether all results are returned in the response. A maximum of 1,000 objects can be listed at a time. If the number of objects is greater than 1,000, the objects beyond 1,000 cannot be returned.

Value range:

true: Not all results are returned.

false: All results are returned.

Default value:

None

NextKeyMarker

string

Explanation:

Object name to start with in the next request for listing object versions Key marker for the last returned object in the list. NextKeyMarker is returned when not all the objects are listed. You can set KeyMarker to this value in the next request to list the remaining objects.

Restrictions:

This parameter is only used for listing objects with multiple versions.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

NextVersionIdMarker

string

Explanation:

Version ID to start with in the next request for listing object versions. It must be used together with NextKeyMarker. NextVersionIdMarker is returned when not all the objects are listed. You can set VersionIdMarker to this value in the next request to list the remaining objects.

Restrictions:

This parameter is only used for listing objects with multiple versions.

Value range:

The value must contain 32 characters.

Default value:

None

Versions

[]Version

Explanation:

List of object versions in the bucket. For details, see Table 5.

DeleteMarkers

[]DeleteMarker

Explanation:

List of delete markers in the bucket. For details, see Table 6.

CommonPrefixes

[]string

Explanation:

List of object name prefixes grouped according to the Delimiter parameter (if specified)

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

EncodingType

string

Explanation:

Encoding type for some elements in the response. If Delimiter, KeyMarker, Prefix, CommonPrefixes, NextKeyMarker, and Key contain control characters that are not supported by the XML 1.0 standard, you can use EncodingType to encode Delimiter, KeyMarker, Prefix, CommonPrefixes, NextKeyMarker, and Key in the response.

Value range:

Value option: url

Default value:

None

Table 5 Version

Parameter

Type

Description

Key

string

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing an object is examplebucket.obs.eu-west-101.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

VersionId

string

Explanation:

Object version ID

Value range:

The value must contain 32 characters.

Default value:

None

LastModified

time.Time

Explanation:

Time (UTC) when an object was last modified

Value range:

UTC time

Default value:

None

ETag

string

Explanation:

Base64-encoded, 128-bit MD5 value 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 ETag value is A when an object is uploaded but changes to B when the object is downloaded, it indicates that the object content is changed. The ETag reflects changes to the object content, rather than the object metadata. An uploaded object or copied object has a unique ETag.

Restrictions:

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

Value range:

The value must contain 32 characters.

Default value:

None

Size

int64

Explanation:

Object size in bytes

Value range:

The value ranges from 0 TB to 48.8 TB, in bytes.

Default value:

None

Owner

Owner

Explanation:

Object owner. For details, see Table 7.

StorageClass

StorageClassType

Explanation:

Storage class of the object. For details, see Table 8.

IsLatest

bool

Explanation:

Whether the object is of the current version

Value range:

  • true: The object is the latest version.
  • false: The object is not the latest version.

Default value:

false

Table 6 DeleteMarker

Parameter

Type

Description

Key

string

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.eu-west-101.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Value range:

The value must contain 1 to 1,024 characters.

Default value:

None

VersionId

string

Explanation:

Object version ID

Value range:

The value must contain 32 characters.

Default value:

None

IsLatest

bool

Explanation:

Whether the object is of the current version

Value range:

true: The object is the latest version.

false: The object is not the latest version.

Default value:

false

LastModified

time.Time

Explanation:

Time (UTC) when an object was last modified

Value range:

UTC time

Default value:

None

Owner

Owner

Explanation:

Object owner. This parameter contains the domain ID and name of the object owner. For details, see Table 7.

StorageClass

StorageClassType

Explanation:

Object storage class

Value range:

For details about storage classes, see Table 8.

Default value:

None

Table 7 Owner

Parameter

Type

Mandatory (Yes/No)

Description

ID

string

Yes if used as a request parameter

Explanation:

Account (domain) ID of the owner

Value range:

To obtain the account ID, see How Do I Get My Account ID and User ID?

Default value:

None

Table 8 StorageClassType

Constant

Default Value

Description

StorageClassStandard

STANDARD

OBS Standard

Features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.

StorageClassWarm

WARM

OBS Infrequent Access

Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.

StorageClassCold

COLD

OBS Archive

Used for storing rarely accessed (once a year) data.

Code Examples

This example returns object versions in bucket examplebucket.

 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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
package main
import (
    "fmt"
    "os"
    obs "github.com/huaweicloud/huaweicloud-sdk-go-obs/obs"
)
func main() {
    //Obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways. Using hard coding may result in leakage.
    //Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    ak := os.Getenv("AccessKeyID")
    sk := os.Getenv("SecretAccessKey")
    // (Optional) If you use a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding to reduce leakage risks. You can obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways.
    // securityToken := os.Getenv("SecurityToken")
    // Enter the endpoint corresponding to the bucket. EU-Dublin is used here as an example. Replace it with the one currently in use.
    endPoint := "https://obs.eu-west-101.myhuaweicloud.eu" 
    // Create an obsClient instance.
    // If you use a temporary AK/SK pair and a security token to access OBS, use the obs.WithSecurityToken method to specify a security token when creating an instance.
    obsClient, err := obs.New(ak, sk, endPoint/*, obs.WithSecurityToken(securityToken)*/)
    if err != nil {
        fmt.Printf("Create obsClient error, errMsg: %s", err.Error())
    }
    input := &obs.ListVersionsInput{}
    // Specify a bucket name.
    input.Bucket = "examplebucket"
    // Specify an object prefix (test/ as an example). Objects whose names contain the specified prefix will be listed.
    input.Prefix = "test/"
    // Specify the maximum number of objects to be returned. 100 is used as an example. Returned objects are listed in alphabetic order. The default value is 1000.
    input.MaxKeys = 100
    // Specify the position (test/test2 as an example) where the version listing starts.
    input.KeyMarker = "test/test2"
    // VersionIdMarker must be used together with KeyMarker. If there is no VersionIdMarker mapping to the specified KeyMarker, ignore VersionIdMarker.
    input.VersionIdMarker = "G001117FCE89978B0000401205D5DC9A"
    // Specify an encoding type. url is used as an example. If the objects to list contain special characters, this parameter must be passed.
    input.EncodingType = "url"
    // List object versions in the bucket.
    output, err := obsClient.ListVersions(input)
    if err == nil {
        fmt.Printf("List version objects under the bucket(%s) successful!\n", input.Bucket)
        fmt.Printf("RequestId:%s\n", output.RequestId)
        for index, val := range output.Versions {
            fmt.Printf("Version[%d]-OwnerId:%s, ETag:%s, Key:%s, VersionId:%s, LastModified:%s, Size:%d\n",
                index, val.Owner.ID, val.ETag, val.Key, val.VersionId, val.LastModified, val.Size)
        }
        for index, val := range output.DeleteMarkers {
            fmt.Printf("DeleteMarker[%d]-OwnerId:%s, Key:%s, VersionId:%s, LastModified:%s\n",
                index, val.Owner.ID, val.Key, val.VersionId, val.LastModified)
        }
        return
    }
    fmt.Printf("List version objects under the bucket(%s) fail!\n", input.Bucket)
    if obsError, ok := err.(obs.ObsError); ok {
        fmt.Println("An ObsError was found, which means your request sent to OBS was rejected with an error response.")
        fmt.Println(obsError.Error())
    } else {
        fmt.Println("An Exception was found, which means the client encountered an internal problem when attempting to communicate with OBS, for example, the client was unable to access the network.")
        fmt.Println(err)
    }
}