edit-icon download-icon

Manage objects

Last Updated: Nov 07, 2017

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:

Parameter Description
Delimiter A character to group object names. All those objects whose names contain the specified prefix and are between the delimiter for the first time form a group of elements called CommonPrefixes.
Prefix The keys of returned objects must use the prefix. Note that when you make a query using the prefix, the returned key still contains the prefix.
MaxKeys The maximum number of objects returned for one request. If this parameter is not set, the default value of 100 applies. The max-keys value cannot exceed 1,000.
Marker Set the returned results to begin from the first entry after the Marker in the alphabetical order.

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.

  1. import "fmt"
  2. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  3. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  4. if err != nil {
  5. // HandleError(err)
  6. }
  7. bucket, err := client.Bucket("my-bucket")
  8. if err != nil {
  9. // HandleError(err)
  10. }
  11. lsRes, err := bucket.ListObjects()
  12. if err != nil {
  13. // HandleError(err)
  14. }
  15. fmt.Println("Objects:", lsRes.Objects)

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

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

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

  1. lsRes, err := bucket.ListObjects(oss.Prefix("my-object-"))
  2. if err != nil {
  3. // HandleError(err)
  4. }
  5. 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.

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

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

  1. marker := oss.Marker("")
  2. for {
  3. lsRes, err := bucket.ListObjects(oss.MaxKeys(200), marker)
  4. if err != nil {
  5. HandleError(err)
  6. }
  7. marker = oss.Marker(lsRes.NextMarker)
  8. fmt.Println("Objects:", lsRes.Objects)
  9. if !lsRes.IsTruncated {
  10. break
  11. }
  12. }

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

  1. marker = oss.Marker("my-object-xx")
  2. for {
  3. lsRes, err := bucket.ListObjects(oss.MaxKeys(50), marker)
  4. if err != nil {
  5. // HandleError(err)
  6. }
  7. marker = oss.Marker(lsRes.NextMarker)
  8. fmt.Println("Objects:", lsRes.Objects)
  9. if !lsRes.IsTruncated {
  10. break
  11. }
  12. }

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

  1. prefix := oss.Prefix("my-object-")
  2. marker := oss.Marker("")
  3. for {
  4. lsRes, err := bucket.ListObjects(oss.MaxKeys(80), marker, prefix)
  5. if err != nil {
  6. // HandleError(err)
  7. }
  8. prefix = oss.Prefix(lsRes.Prefix)
  9. marker = oss.Marker(lsRes.NextMarker)
  10. fmt.Println("Objects:", lsRes.Objects)
  11. if !lsRes.IsTruncated {
  12. break
  13. }
  14. }

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:

  1. foo/x
  2. foo/y
  3. foo/bar/a
  4. foo/bar/b
  5. foo/hello/C/1
  6. foo/hello/C/2

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

  1. lsRes, err := bucket.ListObjects(oss.Prefix("foo/"), oss.Delimiter("/"))
  2. if err != nil {
  3. // HandleError(err)
  4. }
  5. 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:

  1. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  2. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  3. if err != nil {
  4. // HandleError(err)
  5. }
  6. bucket, err := client.Bucket("my-bucket")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. isExist, err := bucket.IsObjectExist("my-object")
  11. if err != nil {
  12. // HandleError(err)
  13. }

Delete a single object

You can use Bucket.DeleteObject to delete an object:

  1. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  2. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  3. if err != nil {
  4. // HandleError(err)
  5. }
  6. bucket, err := client.Bucket("my-bucket")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. err = bucket.DeleteObject("my-object")
  11. if err != nil {
  12. // HandleError(err)
  13. }

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.

  1. import "fmt"
  2. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  3. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  4. if err != nil {
  5. // HandleError(err)
  6. }
  7. bucket, err := client.Bucket("my-bucket")
  8. if err != nil {
  9. // HandleError(err)
  10. }
  11. // The results of deleted objects are returned by default.
  12. delRes, err := bucket.DeleteObjects([]string{"my-object-1", "my-object-2"})
  13. if err != nil {
  14. // HandleError(err)
  15. }
  16. fmt.Println("Deleted Objects:", delRes.DeletedObjects)
  17. // The deletion results are not returned.
  18. _, err = bucket.DeleteObjects([]string{"my-object-3", "my-object-4"},
  19. oss.DeleteObjectsQuiet(true))
  20. if err != nil {
  21. // HandleError(err)
  22. }

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.

  1. import "fmt"
  2. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  3. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  4. if err != nil {
  5. // HandleError(err)
  6. }
  7. bucket, err := client.Bucket("my-bucket")
  8. if err != nil {
  9. // HandleError(err)
  10. }
  11. props, err := bucket.GetObjectDetailedMeta("my-object")
  12. if err != nil {
  13. // HandleError(err)
  14. }
  15. 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:

Metadata Description
CacheControl Specifies the cache action of the web page when the new object is downloaded.
ContentDisposition Specifies the name of the new object when it is downloaded.
ContentEncoding Specifies the content encoding format when a new object is downloaded.
Expires Specify the expiration time of a new object. The GMT format is recommended.
Meta Custom parameter prefixed with “X-Oss-Meta-“.

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

  1. import "fmt"
  2. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  3. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  4. if err != nil {
  5. // HandleError(err)
  6. }
  7. bucket, err := client.Bucket("my-bucket")
  8. if err != nil {
  9. // HandleError(err)
  10. }
  11. // Modify one piece of metadata at a time
  12. err = bucket.SetObjectMeta("my-object", oss.Meta("MyMeta", "MyMetaValue"))
  13. if err != nil {
  14. // HandleError(err)
  15. }
  16. // Modify multiple pieces of metadata
  17. options := []oss.Option{
  18. oss.Meta("MyMeta", "MyMetaValue"),
  19. oss.Meta("MyObjectLocation", "HangZhou"),
  20. }
  21. err = bucket.SetObjectMeta("my-object", options...)
  22. if err != nil {
  23. // HandleError(err)
  24. }

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

  1. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  2. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  3. if err != nil {
  4. // HandleError(err)
  5. }
  6. bucket, err := client.Bucket("my-bucket")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. _, err = bucket.CopyObject("my-object", "descObjectKey")
  11. if err != nil {
  12. // HandleError(err)
  13. }

Copy objects to another bucket

  1. import "github.com/aliyun/aliyun-oss-go-sdk/oss"
  2. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  3. if err != nil {
  4. // HandleError(err)
  5. }
  6. bucket, err := client.Bucket("my-bucket")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. _, err = bucket.CopyObjectToBucket("my-object", "my-bucket-desc", "descObjectKey")
  11. if err != nil {
  12. // HandleError(err)
  13. }

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:

Metadata Description
CacheControl Specifies the cache action of the web page when the new object is downloaded.
ContentDisposition Specifies the name of the new object when it is downloaded.
ContentEncoding Specifies the content encoding format when a new object is downloaded.
Expires Specify the expiration time (seconds) of the new object. For more information, see RFC2616.
ServerSideEncryption Specifies the server-side encryption algorithm used when the OSS creates an object.
ObjectACL Specifies the object ACL policies when the OSS creates an object.
Meta Custom parameter prefixed with “X-Oss-Meta-“.
  1. import (
  2. "time"
  3. "github.com/aliyun/aliyun-oss-go-sdk/oss"
  4. )
  5. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  6. if err != nil {
  7. // HandleError(err)
  8. }
  9. bucket, err := client.Bucket("my-bucket")
  10. if err != nil {
  11. // HandleError(err)
  12. }
  13. expires := time.Date(2049, time.January, 10, 23, 0, 0, 0, time.UTC)
  14. options := []oss.Option{
  15. oss.MetadataDirective(oss.MetaReplace),
  16. oss.Expires(expires),
  17. oss.ObjectACL(oss.ACLPublicRead),
  18. oss.Meta("MyMeta", "MyMetaValue")}
  19. _, err = bucket.CopyObject("my-object", "descObjectKey", options...)
  20. if err != nil {
  21. // HandleError(err)
  22. }

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:

Parameter Description
CopySourceIfMatch If the source object’s ETag value is the same as the ETag provided by the user, the copy operation is executed. Otherwise, an error is returned.
CopySourceIfNoneMatch If the source object’s ETag value is the not same as the ETag provided by the user, the copy operation is actioned. Otherwise, an error is returned.
CopySourceIfModifiedSince If the specified time in the input parameter is the same as or later than the actual modification time of the source object, the object is copied normally. Otherwise, an error is returned.
CopySourceIfUnmodifiedSince If the source object has been modified after the time specified by the user, the copy operation is actioned. Otherwise, an error is returned.
  1. import (
  2. "fmt"
  3. "time"
  4. "github.com/aliyun/aliyun-oss-go-sdk/oss"
  5. )
  6. client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
  7. if err != nil {
  8. // HandleError(err)
  9. }
  10. bucket, err := client.Bucket("my-bucket")
  11. if err != nil {
  12. // HandleError(err)
  13. }
  14. date := time.Date(2015, time.November, 10, 23, 0, 0, 0, time.UTC)
  15. // The copy operation is not executed because the constraint conditions are not met.
  16. _, err = bucket.CopyObject("my-object", "descObjectKey", oss.CopySourceIfModifiedSince(date))
  17. fmt.Println("CopyObjectError:", err)
  18. // The copy operation runs because, the constraint conditions are satisfied.
  19. _, err = bucket.CopyObject("my-object", "descObjectKey", oss.CopySourceIfUnmodifiedSince(date))
  20. if err != nil {
  21. // HandleError(err)
  22. }

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

Thank you! We've received your feedback.