List objects

This topic describes how to list the objects contained in a bucket.

Objects are listed alphabetically. You can use Bucket.ListObjects to list the objects in a bucket. The following table describes the parameters for Bucket.ListObjects.

Parameter	Description
delimiter	Groups objects by name. CommonPrefixes specifies a set of substrings of object names. The substrings start with the prefix and end with the next occurrence of the specified delimiter.
prefix	Specifies the prefix that returned object names must contain.
maxKeys	Specifies the maximum number of objects that can be listed each time. The default value is 100. The maximum value is 1000.
marker	Specifies the name of the object after which the list begins.

For the complete code of ListObjects, visit Github.

Simple list

You can use the default parameters to obtain the list of objects in a bucket. By default, 100 objects are listed. The code is as follows:

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func HandleError(err error) {
    fmt.Println("Error:", err)
    os.Exit(-1)
}

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        HandleError(err)
    }

    // Obtain the bucket.
    bucketName := "<yourBucketName>"
    bucket, err := client.Bucket(bucketName)
    if err ! = nil {
        HandleError(err)
    }

    // List all objects.
    marker := ""
    for {
        lsRes, err := bucket.ListObjects(oss.Marker(marker))
        if err ! = nil {
            HandleError(err)
        }

        // Obtain the listed objects. By default, 100 records are returned each time. 
        for _, object := range lsRes.Objects {
            fmt.Println("Bucket: ", object.Key)
        }

        if lsRes.IsTruncated {
            marker = lsRes.NextMarker
        } else {
            break
        }
    }
}
			

List a specified number of objects

Run the following code to list a specified number of objects:

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    bucketName := "<yourBucketName>"

    // Obtain the bucket.
    bucket, err := client.Bucket(bucketName)
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Set the maximum number of objects that can be listed and list the objects.
    lsRes, err := bucket.ListObjects(oss.MaxKeys(200))
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Obtain the listed objects.
    fmt.Println("Objects:", lsRes.Objects)
    for _, object := range lsRes.Objects {
        fmt.Println("Object:", object.Key)
    }
}
			

List objects whose names contain a specified prefix

Run the following code to list objects with a specified prefix:

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    bucketName := "<yourBucketName>"

    // Obtain the bucket.
    bucket, err := client.Bucket(bucketName)
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // List the objects whose names contain the specified prefix. By default, 100 objects are listed.
    lsRes, err := bucket.ListObjects(oss.Prefix("my-object-"))
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Obtain the listed objects.
    fmt.Println("Objects:", lsRes.Objects)
    for _, object := range lsRes.Objects {
        fmt.Println("Object:", object.Key)
    }
}
			

List the objects that follow a specified marker

The marker parameter indicates the name of an object from which the listing begins. Run the following code to specify an object (specified with marker) after which the listing begins:

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    bucketName := "<yourBucketName>"

    // Obtain the bucket.
    bucket, err := client.Bucket(bucketName)
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // List the objects that follow the specified marker. By default, 100 objects are listed.
    lsRes, err := bucket.ListObjects(oss.Marker("my-object-xx"))
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Obtain the listed objects.
    fmt.Println("Objects:", lsRes.Objects)
    for _, object := range lsRes.Objects {
        fmt.Println("Object:", object.Key)
    }
}
			

List all objects by page

Use the following code to list all objects on one or more pages. The maximum number of objects listed on each page is specified with maxKeys.

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    bucketName := "<yourBucketName>"

    // Obtain the bucket.
    bucket, err := client.Bucket(bucketName)
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // List all objects by page, with 200 objects on each page.
    marker := oss.Marker("")
    for {
        lsRes, err := bucket.ListObjects(oss.MaxKeys(200), marker)
        if err ! = nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        marker = oss.Marker(lsRes.NextMarker)

        fmt.Println("Objects:", lsRes.Objects)

        if ! lsRes.IsTruncated {
            break
        }
    }
}
			

List objects that follow a specified marker by page

The following code provides an example on how to list the objects that follow a specified marker by page. The maximum number of objects that can be listed on each page is specified by MaxKeys.

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    bucketName := "<yourBucketName>"

    // Obtain the bucket.
    bucket, err := client.Bucket(bucketName)
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // List the objects that follow the specified marker by page, with 50 objects on each page.
    marker = oss.Marker("my-object-xx")
    for {
        lsRes, err := bucket.ListObjects(oss.MaxKeys(50), marker)
        if err ! = nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }

        marker = oss.Marker(lsRes.NextMarker)

        fmt.Println("Objects:", lsRes.Objects)

        if ! lsRes.IsTruncated {
            break
        }
    }
}
			

List objects whose names contain a specified prefix by page

The following code provides an example on how to list the objects whose names contain a specified prefix by page. The maximum number of objects that can be listed on each page is specified by MaxKeys.

package main

import (
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    bucketName := "<yourBucketName>"

    // Obtain the bucket.
    bucket, err := client.Bucket(bucketName)
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // List the objects whose names contain the specified prefix by page, with 80 objects on each page.
    prefix := oss.Prefix("my-object-")
    marker := oss.Marker("")
    for {
        lsRes, err := bucket.ListObjects(oss.MaxKeys(80), marker, prefix)
        if err ! = nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }

        prefix = oss.Prefix(lsRes.Prefix)
        marker = oss.Marker(lsRes.NextMarker)

        fmt.Println("Objects:", lsRes.Objects)

        if ! lsRes.IsTruncated {
            break
        }
    }
}
			

List the information about the objects whose names contain a specified prefix

The following code provides an example on how to list the information about the objects whose names contain a specified prefix. Such information includes the object size, the time when the object was last modified, and the object name.

package main

import (
    "fmt"
    "os"

    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Obtain the bucket.
    bucket, err := client.Bucket("<yourBucketName>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Traverse the objects.
    marker := oss.Marker("")
    prefix := oss.Prefix("<yourObjectPrefix>")
    for {
        lor, err := bucket.ListObjects(marker, prefix)
        if err ! = nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }

        for _, object := range lor.Objects {
            fmt.Printf("%s %d %s\n", object.LastModified, object.Size, object.Key)
        }

        prefix = oss.Prefix(lor.Prefix)
        marker = oss.Marker(lsRes.NextMarker)
        if ! lor.IsTruncated {
            break
        }
    }
}

List the information about the subdirectories whose names contain a specified prefix

The following code provides an example on how to list the information about the subdirectories whose names contain a specified prefix:

import (
    "fmt"
    "os"

    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
    // Create an OSSClient instance.
    client, err := oss.New("<yourEndpoint>", "<yourAccessKeyId>", "<yourAccessKeySecret>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Obtain the bucket.
    bucket, err := client.Bucket("<yourBucketName>")
    if err ! = nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    marker := oss.Marker("")
    prefix := oss.Prefix("<yourObjectPrefix>")
    for {
        lor, err := bucket.ListObjects(marker, prefix, oss.Delimiter("/"))
        if err ! = nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }

        for _, dirName := range lor.CommonPrefixes {
            fmt.Println(dirName)
        }

        prefix = oss.Prefix(lor.Prefix)
        marker = oss.Marker(lsRes.NextMarker)
        if ! lor.IsTruncated {
            break
        }
    }
}