Object Storage Service (OSS) allows you to configure object tags to classify objects. You can configure lifecycle rules and control access to objects based on tags.

Background information

When you configure object tagging, take note of the following items:

  • You can add tags to an object when and after you upload the object. If the object already has tags, the existing tags are overwritten. For more information about object tags, see PutObjectTagging.
  • To add tags to an object, you must have permissions to call the PutObjectTagging operation.

    You can configure a custom policy in Script configuration mode to grant the permissions to a specific RAM user. For more information, see Attach a custom policy to a RAM user.

  • The Last-Modified value of an object is not updated when its tags are changed.
  • You can add up to 10 tags to an object. The tags added to an object must have unique keys.
  • A tag key can be a maximum of 128 characters in length. A tag value can be a maximum of 256 characters in length.
  • Tag keys and tag values are case-sensitive.
  • The key and value of a tag can contain letters, digits, spaces, and the following special characters:

    + - = ._:/

    Note If you configure the tags in the HTTP header and the tags contain characters, you can encode the keys and the values of the tags by using URL encoding.

Object tagging uses a key-value pair to identify objects. For more information about object tags, see Object tagging.

Add tags to an object when you upload the object

  • Add tags to an object when you upload the object by using simple upload
    The following code provides an example on how to add tags to an object when you upload the object by using simple upload:
    package main
    
    import (
        "fmt"
        "os"
        "strings"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // Create an OSSClient instance. 
        // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the name of the bucket. Example: examplebucket. 
        bucketName := "examplebucket"
        // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
        objectName := "exampledir/exampleobject.txt"
    
        // Obtain the bucket. 
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // Add tags to the object. 
        err = bucket.PutObject(objectName, strings.NewReader("Hello OSS"), oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        fmt.Println(bucket.GetObjectTagging(objectName))
    }
  • Add tags to an object when you upload the object by using multipart upload
    The following code provides an example on how to add tags to an object when you upload the object by using multipart upload:
    package main
    
    import (
        "fmt"
        "os"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // Create an OSSClient instance. 
        // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the name of the bucket. Example: examplebucket. 
        bucketName := "examplebucket"
        // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
        objectName := "exampledir/exampleobject.txt"
        // Specify the full path of the local file to upload. Example: D:\\localpath\\examplefile.txt. 
        // By default, if you specify only the name of the local file such as examplefile.txt without specifying the local path, the local file is uploaded from the path of the project to which the sample program belongs. 
        fileName := "D:\\localpath\\examplefile.txt"
    
        // Obtain the bucket. 
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the key and the value of the object tag. Example: the key is owner, and the value is John. 
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // You can split an object into multiple parts for upload based on the object size. In this example, the object is split into three parts. 
        chunks, err := oss.SplitFileByPartNum(fileName, 3)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Open the object. 
        fd, err := os.Open(fileName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        defer fd.Close()
    
        // Initialize the multipart upload and configure object tagging. 
        imur, err := bucket.InitiateMultipartUpload(objectName, oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Implement the multipart upload task. 
        var parts []oss.UploadPart
        for _, chunk := range chunks {
            fd.Seek(chunk.Offset, os.SEEK_SET)
            part, err := bucket.UploadPart(imur, fd, chunk.Size, chunk.Number)
            if err != nil {
              fmt.Println("Error:", err)
              os.Exit(-1)
            }
          parts = append(parts, part)
        }
        _, err = bucket.CompleteMultipartUpload(imur, parts)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        fmt.Println(bucket.GetObjectTagging(objectName))
    }
  • Add tags to an object when you upload the object by using append upload
    The following code provides an example on how to add tags to an object when you upload the object by using append upload:
    package main
    
    import (
        "fmt"
        "os"
        "strings"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // Create an OSSClient instance. 
        // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
       // Specify the name of the bucket. Example: examplebucket. 
        bucketName := "examplebucket"
        // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
        objectName := "exampledir/exampleobject.txt"
    
        // Obtain the bucket. 
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        var nextPos int64
        // Upload the object by using append upload for the first time. When you call AppendObject to add tags to an object when you upload the object, the tags can be added to the object only when the object is uploaded for the first time. 
        nextPos, err = bucket.AppendObject(objectName, strings.NewReader("Hello OSS A \n"), nextPos, oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        // Upload the object by using append upload for the second time. 
        nextPos, err = bucket.AppendObject(objectName, strings.NewReader("Hello OSS B \n"), nextPos)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        fmt.Println(bucket.GetObjectTagging(objectName))
    }
  • Add tags to an object when you upload the object by using resumable upload
    The following code provides an example on how to add tags to an object when you upload the object by using resumable upload:
    package main
    
    import (
        "fmt"
        "os"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // Create an OSSClient instance. 
        // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the name of the bucket. Example: examplebucket. 
        bucketName := "examplebucket"
        // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
        objectName := "exampledir/exampleobject.txt"
        // Specify the full path of the local file to upload. Example: D:\\localpath\\examplefile.txt. 
        // By default, if you specify only the name of the local file such as examplefile.txt without specifying the local path, the local file is uploaded from the path of the project to which the sample program belongs. 
        fileName := "D:\\localpath\\examplefile.txt"
    
        // Obtain the bucket. 
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // Split the object into multiple parts, each of which is 100 KB in size. Then, use 3 coroutines to concurrently upload the parts, and add tags to the object when you upload the parts. 
        err = bucket.UploadFile(objectName, fileName, 100*1024, oss.Routines(3), oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        fmt.Println(bucket.GetObjectTagging(objectName))
    }

Add tags to an existing object or modify the tags of the object

If an existing object has no tags or the added tags of the object do not meet your requirements, you can add tags to or modify the tags of the existing object.

The following code provides an example on how to add tags to or modify the tags of an existing object:
package main

import (
    "fmt"
    "os"
    "strings"

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

func main() {
    // Create an OSSClient instance. 
    // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Specify the name of the bucket. Example: examplebucket. 
    bucketName := "examplebucket"
    // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    objectName := "exampledir/exampleobject.txt"

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

    // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
    tag1 := oss.Tag{
        Key:   "owner",
        Value: "John",
    }
    tag2 := oss.Tag{
        Key:   "type",
        Value: "document",
    }
    tagging := oss.Tagging{
        Tags: []oss.Tag{tag1, tag2},
    }
    // Add tags to the object. 
    err = bucket.PutObjectTagging(objectName, tagging)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    fmt.Println(bucket.GetObjectTagging(objectName))
}

Add tags to or modify the tags of a specified version of an object

If versioning is enabled for the bucket, you can add tags to or modify the tags of a specific version of the object by specifying the version ID of the object.

The following code provides an example on how to add tags to or modify the tags of a specified version of the object.

Note For more information about how to obtain the version IDs of an object, see List objects.
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. 
    // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
    if err != nil {
        HandleError(err)
    }

    // Specify the name of the bucket. Example: examplebucket. 
    bucketName := "examplebucket"
    // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    objectName := "exampledir/exampleobject.txt"
    // Specify the version ID of the object. 
    versionId := "CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****"

    // Obtain the bucket. 
    bucket,err := client.Bucket(bucketName)
    if err != nil {
        HandleError(err)
    }
    // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
    tag1 := oss.Tag{
        Key:   "owner",
        Value: "John",
    }

    tag2 := oss.Tag{
        Key:   "type",
        Value: "document",
    }

    tagging := oss.Tagging{
        Tags: []oss.Tag{tag1, tag2},
    }

    // Add tags to the specified version of the object.  
    err = bucket.PutObjectTagging(objectName, tagging,oss.VersionId(versionId))

    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    fmt.Println(bucket.GetObjectTagging(objectName))  
}

Add tags to an object when you copy the object

You can configure one of the following tagging parameters when you copy an object. Default value: Copy. Valid values:
  • Copy: The tag of the source object is copied to the destination object.
  • Replace: The tag of the destination object is set to the tag specified in the request instead of the tag of the source object.

The following examples describe how to add tags to objects smaller than 1 GB in simple copy mode and larger than 1 GB in multipart copy mode:

  • Add tags to an object when you copy the object by calling CopyObject
    The following code provides an example on how to add tags to an object smaller than 1 GB when you copy it by calling CopyObject:
    package main
    
    import (
        "fmt"
        "os"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // Create an OSSClient instance. 
        // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the name of the bucket. Example: examplebucket. 
        bucketName := "examplebucket"
        // Specify the full path of the source object. The full path of the object cannot contain the bucket name. Example: srcexampledir/exampleobject.txt. 
        srcObjectName := "srcexampledir/exampleobject.txt"
        // Specify the full path of the destination object. The full path of the object cannot contain the bucket name. Example: destexampledir1/exampleobject.txt. 
        destObjectName1 := "destexampledir1/exampleobject.txt"
        // Specify the full path of the destination object. The full path of the object cannot contain the bucket name. Example: destexampledir2/exampleobject.txt. 
        destObjectName2 := "destexampledir2/exampleobject.txt"
    
        // Obtain the bucket. 
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // If you configure only the tagging parameter, tags cannot be added to the destination object. 
        _, err = bucket.CopyObject(srcObjectName, destObjectName1, oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Tags can be added to the destination object only when you configure both the TaggingReplace and tagging parameters. 
        _, err = bucket.CopyObject(srcObjectName, destObjectName2, oss.SetTagging(tagging), oss.TaggingDirective(oss.TaggingReplace))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        fmt.Println(bucket.GetObjectTagging(objectName))
    }
  • Add tags to an object when you copy the object by calling UploadPartCopy

    The following code provides an example on how to add tags to an object larger than 1 GB when you copy it by calling UploadPartCopy:

    package main
    
    import (
        "fmt"
        "os"
        "strings"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // Create an OSSClient instance. 
        // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the name of the bucket. Example: examplebucket. 
        bucketName := "examplebucket"
        // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: srcexampledir/exampleobject.txt. 
        srcObjectName := "srcexampledir/exampleobject.txt"
        // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: destexampledir/exampleobject.txt. 
        destObjectName := "destexampledir/exampleobject.txt"
    
        // Obtain the bucket. 
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // Upload an object for calling UploadPartCopy. 
        content := "this your object value"
        err = bucket.PutObject(objectName, strings.NewReader(content))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // Initialize the uploaded object and set tagging for the object. 
        imur, err := bucket.InitiateMultipartUpload(destObjectName, oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        // Use the UploadPartCopy method to upload the object as one part. 
        part, err := bucket.UploadPartCopy(imur, bucketName, srcObjectName, 0, int64(len(content)), 1)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        parts := []oss.UploadPart{part}
        _, err = bucket.CompleteMultipartUpload(imur, parts)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        fmt.Println(bucket.GetObjectTagging(objectName))
    }

Add tags to a symbolic link

The following code provides an example on how to add tags to a symbolic link:
package main

import (
  "fmt"
  "os"
  "strings"

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

func main() {
    // Create an OSSClient instance. 
    // Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

   // Specify the name of the bucket. Example: examplebucket. 
    bucketName := "examplebucket"
    // Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. 
    objectName := "exampledir/exampleobject.txt"
    // Specify the full path of the symbolic link object. Example: shortcut/myobject.txt. 
    symlinkName := "shortcut/myobject.txt"

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

    // Specify the key and the value of the object tag. For example, set the key to owner and the value to John. 
    tag1 := oss.Tag{
        Key:   "owner",
        Value: "John",
    }
    tag2 := oss.Tag{
        Key:   "type",
        Value: "document",
    }
    tagging := oss.Tagging{
        Tags: []oss.Tag{tag1, tag2},
    }

    err = bucket.PutObject(objectName, strings.NewReader("Hello OSS"))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    err = bucket.PutSymlink(objectName, symlinkName, oss.SetTagging(tagging))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    fmt.Println(bucket.GetObjectTagging(objectName))
}