Manage objects

A bucket may have a lot of objects. The SDK provides a series of interfaces for you to conveniently manage the objects.

List objects in a bucket

You can use the Bucket.ListObjects interface to list all objects in the current bucket. Main parameters are described as follows:

Note: For example code of ListObjects, see sample/list_objects.go

Get the object list in a bucket using the default parameters. The first 100 objects are returned by default.

    import "fmt"
    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    lsRes, err := bucket.ListObjects()
    if err != nil {
        // HandleError(err)
    }
    fmt.Println("Objects:", lsRes.Objects)

The maximum number of objects to be returned. A maximum of 1,000 objects can be returned.

    lsRes, err := bucket.ListObjects(oss.MaxKeys(200))
    if err != nil {
        // HandleError(err)
    }
    fmt.Println("Objects:", lsRes.Objects)

Specify the prefix of the objects to be returned. A maximum of 100 objects can be returned by default.

    lsRes, err := bucket.ListObjects(oss.Prefix("my-object-"))
    if err != nil {
        // HandleError(err)
    }
    fmt.Println("Objects:", lsRes.Objects)

Specify to return objects after a specific object (my-object-xx). A maximum of 100 objects can be returned by default.

    lsRes, err := bucket.ListObjects(oss.Marker("my-object-xx"))
    if err != nil {
        // HandleError(err)
    }
    fmt.Println("Objects:", lsRes.Objects)

Retrieve all objects by page. 200 objects are returned each time.

    marker := oss.Marker("")
    for {
        lsRes, err := bucket.ListObjects(oss.MaxKeys(200), marker)
        if err != nil {
            HandleError(err)
        }
        marker = oss.Marker(lsRes.NextMarker)
        fmt.Println("Objects:", lsRes.Objects)
        if !lsRes.IsTruncated {
            break
        }
    }

Retrieve all objects after a specific object by page. 50 objects are returned each time.

    marker = oss.Marker("my-object-xx")
    for {
        lsRes, err := bucket.ListObjects(oss.MaxKeys(50), marker)
        if err != nil {
            // HandleError(err)
        }
        marker = oss.Marker(lsRes.NextMarker)
        fmt.Println("Objects:", lsRes.Objects)
        if !lsRes.IsTruncated {
            break
        }
    }

Retrieve all objects with the specified prefix by page. 80 objects are returned each time.

    prefix := oss.Prefix("my-object-")
    marker := oss.Marker("")
    for {
        lsRes, err := bucket.ListObjects(oss.MaxKeys(80), marker, prefix)
        if err != nil {
            // HandleError(err)
        }
        prefix = oss.Prefix(lsRes.Prefix)
        marker = oss.Marker(lsRes.NextMarker)
        fmt.Println("Objects:", lsRes.Objects)
        if !lsRes.IsTruncated {
            break
        }
    }

Simulate the directory structure

OSS is an object-based storage service. It has no directory. All objects stored in a bucket are uniquely identified by the key of the object. Hierarchical structure cannot be seen among these objects. Such a structure allows OSS to efficiently store objects. However, you may want to put different types of objects under different “directories” to manage objects in a conventional way. OSS provides a “Public Prefix” feature for you to conveniently create a stimulated directory structure. For more information about the public prefix concept, see View the object list.

Let’s assume that the bucket already contains the following objects:

foo/x
foo/y
foo/bar/a
foo/bar/b
foo/hello/C/1
foo/hello/C/2

You can use ListObjects to list all the objects and subdirectories under the specified directory:

    lsRes, err := bucket.ListObjects(oss.Prefix("foo/"), oss.Delimiter("/"))
    if err != nil {
        // HandleError(err)
    }
    fmt.Println("Objects:", lsRes.Objects,"SubDir:", lsRes.CommonPrefixes)

In the results displayed, lsRes.Objects is an object, including foo/x and foo/y; lsRes.CommonPrefixes is a subdirectory, including foo/bar/ and foo/hello/.

Identify whether an object exists

You can use Bucket.IsObjectExist to identify whether an object exists:

    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    isExist, err := bucket.IsObjectExist("my-object")
    if err != nil {
        // HandleError(err)
    }

Delete a single object

You can use Bucket.DeleteObject to delete an object:

    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    err = bucket.DeleteObject("my-object")
    if err != nil {
        // HandleError(err)
    }

Delete multiple objects

You can use Bucket.DeleteObjects to delete multiple objects. You can use the DeleteObjectsQuiet parameter to specify whether to return the deletion results. The deletion results are returned by default.

Note: For the example code for deleting objects, see sample/delete_object.go.

    import "fmt"
    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    // The results of deleted objects are returned by default.
    delRes, err := bucket.DeleteObjects([]string{"my-object-1", "my-object-2"})
    if err != nil {
        // HandleError(err)
    }
    fmt.Println("Deleted Objects:", delRes.DeletedObjects)
    // The deletion results are not returned.
    _, err = bucket.DeleteObjects([]string{"my-object-3", "my-object-4"},
        oss.DeleteObjectsQuiet(true))
    if err != nil {
        // HandleError(err)
    }

Note:

• Bucket.DeleteObjects must contain at least one ObjectKey and cannot be empty.
• Bucket.DeleteObjects uses the XML package of Go. The version of the XML package is XML1.0. Do not use features not supported in XML1.0.

Get object metadata

When uploading/copying an object in OSS, besides the object content, you can also specify some attributes for the object. The attributes are called “metadata”. The metadata is stored together with the object during uploading, and returned together with the object during downloading.

The object metadata in SDK is indicated by a map. Other keys and values are of the string type and only contain simple printable ASCII characters and cannot contain line breaks. The total size of all metadata cannot exceed 8 KB.

Note:

• This is because, the object meta information is stored in HTTP headers during object uploading/downloading, the meta information cannot contain any complex character according to HTTP.

• The name of the object metadata is case-insensitive. The case sensitivity can be ignored during comparison/reading operations.

You can use Bucket.GetObjectDetailedMeta to get the object metadata.

Note: For the example code of object metadata, see sample/object_meta.go.

    import "fmt"
    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    props, err := bucket.GetObjectDetailedMeta("my-object")
    if err != nil {
        // HandleError(err)
    }
    fmt.Println("Object Meta:", props)

Note: Object ACLs are not included in Bucket.GetObjectMeta. You can use Bucket.GetObjectACL to get the object ACLs.

Modify object meta

You can modify one or multiple pieces of metadata at a time. The available metadata is described in the following table:

You can use Bucket.SetObjectMeta to set the object metadata:

    import "fmt"
    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    // Modify one piece of metadata at a time
    err = bucket.SetObjectMeta("my-object", oss.Meta("MyMeta", "MyMetaValue"))
    if err != nil {
        // HandleError(err)
    }
    // Modify multiple pieces of metadata
    options := []oss.Option{
        oss.Meta("MyMeta", "MyMetaValue"),
        oss.Meta("MyObjectLocation", "HangZhou"),
    }
    err = bucket.SetObjectMeta("my-object", options...)
    if err != nil {
        // HandleError(err)
    }

Copy an object

You can use Bucket.CopyObject to copy objects within the same bucket and use Bucket.CopyObjectToBucket to copy objects to another bucket.

Note: For the example code of object copy, see sample/copy_objects.go.

Copy objects within the same bucket

    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    _, err = bucket.CopyObject("my-object", "descObjectKey")
    if err != nil {
        // HandleError(err)
    }

Copy objects to another bucket

    import "github.com/aliyun/aliyun-oss-go-sdk/oss"
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    _, err = bucket.CopyObjectToBucket("my-object", "my-bucket-desc", "descObjectKey")
    if err != nil {
        // HandleError(err)
    }

Process object metadata during copy

You can process the object metadata in two ways when copying an object (CopyObject/CopyObjectToBucket) by specifying the parameter MetadataDirective:

• oss.MetaCopy: The same with the source object, that is, copying the source object metadata
• oss.MetaReplace: Overwrite the source object information with the new metadata

The default value is oss.MetaCopy.

When the value of the parameter MetadataDirective is MetaReplace during a copy, you can specify the following metadata items for the new object:

    import (
        "time"
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    expires := time.Date(2049, time.January, 10, 23, 0, 0, 0, time.UTC)
    options := []oss.Option{
        oss.MetadataDirective(oss.MetaReplace),
        oss.Expires(expires),
        oss.ObjectACL(oss.ACLPublicRead),
        oss.Meta("MyMeta", "MyMetaValue")}
    _, err = bucket.CopyObject("my-object", "descObjectKey", options...)
    if err != nil {
        // HandleError(err)
    }

Define copy conditions

You can set conditions for object copy. The object is copied only when the conditions are satisfied. Otherwise, an error is reported and the object does not get copied. Available conditions include:

    import (
        "fmt"
        "time"
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
    if err != nil {
        // HandleError(err)
    }
    bucket, err := client.Bucket("my-bucket")
    if err != nil {
        // HandleError(err)
    }
    date := time.Date(2015, time.November, 10, 23, 0, 0, 0, time.UTC)
    // The copy operation is not executed because the constraint conditions are not met.
    _, err = bucket.CopyObject("my-object", "descObjectKey", oss.CopySourceIfModifiedSince(date))
    fmt.Println("CopyObjectError:", err)
    // The copy operation runs because, the constraint conditions are satisfied.
    _, err = bucket.CopyObject("my-object", "descObjectKey", oss.CopySourceIfUnmodifiedSince(date))
    if err != nil {
        // HandleError(err)
    }

Note: Both of Bucket.CopyObject and Bucket.CopyObjectToBucket support object metadata processing and defining of copy conditions for copying objects.