OSS支持使用对象标签(Object Tagging)对存储空间(Bucket)中的文件(Object)进行分类,您可以针对相同标签的Object设置生命周期规则、访问权限等。

背景信息

设置对象标签时,请注意以下事项:

  • 您可以在上传Object时设置对象标签,也可以对已上传Object设置对象标签。设置对象标签时,如果对象已有标签,则覆盖原标签。关于设置对象标签的更多信息,请参见PutObjectTagging
  • 设置对象标签时,您要有PutObjectTagging权限。

    请通过脚本配置方式创建以上自定义权限策略,然后为指定的RAM用户授予相应权限。具体操作,请参见为RAM用户授权自定义的RAM Policy

  • 更改标签时不会更新Object的Last‑Modified时间。
  • 单个Object最多可设置10个标签,Key不可重复。
  • 每个Key长度不超过128字节,每个Value长度不超过256字节。
  • Key和Value区分大小写。
  • 标签合法字符集包括大小写字母、数字、空格和以下符号:

    +‑=._:/

    说明 通过HTTP header的方式设置标签且标签中包含任意字符时,您可以对标签的Key和Value做URL编码。

对象标签使用一组键值对(Key-Value)来标记对象。关于对象标签的更多信息,请参见对象标签

上传Object时添加对象标签

  • 简单上传时添加对象标签
    以下代码用于简单上传时添加对象标签。
    package main
    
    import (
        "fmt"
        "os"
        "strings"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // 创建OSSClient实例。
        // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
        // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 填写Bucket名称,例如examplebucket。
        bucketName := "examplebucket"
        // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
        objectName := "exampledir/exampleobject.txt"
    
        // 获取存储空间。
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 依次填写对象标签的键(例如owner)和值(例如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"), oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        fmt.Println(bucket.GetObjectTagging(objectName))
    }
  • 分片上传时添加对象标签
    以下代码用于分片上传本地文件时添加对象标签。
    package main
    
    import (
        "fmt"
        "os"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // 创建OSSClient实例。
        // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
        // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 填写Bucket名称,例如examplebucket。
        bucketName := "examplebucket"
        // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
        objectName := "exampledir/exampleobject.txt"
        // 填写本地文件的完整路径,例如D:\\localpath\\examplefile.txt。
        // 如果未指定本地路径只填写了文件名称(例如examplefile.txt),则默认从示例程序所属项目对应本地路径中上传文件。
        fileName := "D:\\localpath\\examplefile.txt"
    
        // 获取存储空间。
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 依次填写对象标签的键(例如owner)和值(例如John)。
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // 将文件分成3个分片进行上传,具体分片数请根据文件大小确定。
        chunks, err := oss.SplitFileByPartNum(fileName, 3)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 打开文件。
        fd, err := os.Open(fileName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        defer fd.Close()
    
        // 初始化上传的文件,并设置对象标签。
        imur, err := bucket.InitiateMultipartUpload(objectName, oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 分片上传。
        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))
    }
  • 追加上传时添加对象标签
    以下代码用于追加上传时添加对象标签。
    package main
    
    import (
        "fmt"
        "os"
        "strings"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // 创建OSSClient实例。
        // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
        // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
       // 填写Bucket名称,例如examplebucket。
        bucketName := "examplebucket"
        // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
        objectName := "exampledir/exampleobject.txt"
    
        // 获取存储空间。
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 依次填写对象标签的键(例如owner)和值(例如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
        // 第一次上传可追加的文件。只有第一次调用AppendObject时设置的标签才会生效,后续再调用AppendObject设置的标签不生效。
        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)
        }
        // 第二次上传。
        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))
    }
  • 断点续传上传时添加对象标签
    以下代码用于断点续传上传本地文件时添加对象标签。
    package main
    
    import (
        "fmt"
        "os"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // 创建OSSClient实例。
        // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
        // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 填写Bucket名称,例如examplebucket。
        bucketName := "examplebucket"
        // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
        objectName := "exampledir/exampleobject.txt"
        // 填写本地文件的完整路径,例如D:\\localpath\\examplefile.txt。
        // 如果未指定本地路径只填写了文件名称(例如examplefile.txt),则默认从示例程序所属项目对应本地路径中上传文件。
        fileName := "D:\\localpath\\examplefile.txt"
    
        // 获取存储空间。
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 依次填写对象标签的键(例如owner)和值(例如John)。
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // 将文件分成多个分片,每个分片大小为100 KB,使用3个协程并发上传分片,上传时设置对象标签。
        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))
    }

对已上传Object添加或更改对象标签

如果上传Object时未添加对象标签或者添加的对象标签不满足使用需求,您可以在上传Object后为Object添加或更改对象标签。

以下代码用于对已上传Object添加或更改对象标签。
package main

import (
    "fmt"
    "os"
    "strings"

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

func main() {
    // 创建OSSClient实例。
    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
    client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // 填写Bucket名称,例如examplebucket。
    bucketName := "examplebucket"
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    objectName := "exampledir/exampleobject.txt"

    // 获取存储空间。
    bucket, err := client.Bucket(bucketName)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // 依次填写对象标签的键(例如owner)和值(例如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.PutObjectTagging(objectName, tagging)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    fmt.Println(bucket.GetObjectTagging(objectName))
}

为Object指定版本添加或更改对象标签

在已开启版本控制的Bucket中,通过指定Object的版本ID(versionId),您可以为Object指定版本添加或更改对象标签。

以下代码用于为Object指定版本添加或更改对象标签。

说明 关于获取versionId的具体操作,请参见列举文件
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() {
    // 创建OSSClient实例。
    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
    client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
    if err != nil {
        HandleError(err)
    }

    // 填写Bucket名称,例如examplebucket。
    bucketName := "examplebucket"
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    objectName := "exampledir/exampleobject.txt"
    // 填写Object的版本ID。
    versionId := "CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****"

    // 获取存储空间。
    bucket,err := client.Bucket(bucketName)
    if err != nil {
        HandleError(err)
    }
    // 依次填写对象标签的键(例如owner)和值(例如John)。
    tag1 := oss.Tag{
        Key:   "owner",
        Value: "John",
    }

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

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

    // 为Object指定版本设置标签信息。 
    err = bucket.PutObjectTagging(objectName, tagging,oss.VersionId(versionId))

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

拷贝Object时设置对象标签

拷贝Object时,可以指定如何设置目标Object的对象标签。取值如下:
  • Copy(默认值):复制源Object的对象标签到目标Object。
  • Replace:忽略源Object的对象标签,直接采用请求中指定的对象标签。

以下分别提供了简单拷贝1 GB以下的Object及分片拷贝1 GB以上的Object时设置对象标签的详细示例。

  • 简单拷贝时设置对象标签
    以下代码用于简单拷贝1 GB以下的Object时设置对象标签。
    package main
    
    import (
        "fmt"
        "os"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // 创建OSSClient实例。
        // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
        // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 填写Bucket名称,例如examplebucket。
        bucketName := "examplebucket"
        // 填写源Object完整路径,例如srcexampledir/exampleobject.txt。
        srcObjectName := "srcexampledir/exampleobject.txt"
        // 填写目标Object完整路径,例如destexampledir1/exampleobject.txt。
        destObjectName1 := "destexampledir1/exampleobject.txt"
        // 填写目标Object完整路径,例如destexampledir2/exampleobject.txt。
        destObjectName2 := "destexampledir2/exampleobject.txt"
    
        // 获取存储空间。
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 依次填写对象标签的键(例如owner)和值(例如John)。
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // 复制Object时只设置tagging参数,Object标签信息不生效。
        _, err = bucket.CopyObject(srcObjectName, destObjectName1, oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 复制Object时同时设置TaggingReplace和tagging两个参数,Object标签信息才生效。
        _, 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))
    }
  • 分片拷贝时设置对象标签

    以下代码用于分片拷贝1 GB以上的Object时设置对象标签。

    package main
    
    import (
        "fmt"
        "os"
        "strings"
    
        "github.com/aliyun/aliyun-oss-go-sdk/oss"
    )
    
    func main() {
        // 创建OSSClient实例。
        // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
        // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
        client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 填写Bucket名称,例如examplebucket。
        bucketName := "examplebucket"
        // 填写源Object完整路径,例如srcexampledir/exampleobject.txt。
        srcObjectName := "srcexampledir/exampleobject.txt"
        // 填写目标Object完整路径,例如destexampledir/exampleobject.txt。
        destObjectName := "destexampledir/exampleobject.txt"
    
        // 获取存储空间。
        bucket, err := client.Bucket(bucketName)
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 依次填写对象标签的键(例如owner)和值(例如John)。
        tag1 := oss.Tag{
            Key:   "owner",
            Value: "John",
        }
        tag2 := oss.Tag{
            Key:   "type",
            Value: "document",
        }
        tagging := oss.Tagging{
            Tags: []oss.Tag{tag1, tag2},
        }
    
        // 上传一个Object,用于分片拷贝。
        content := "this your object value"
        err = bucket.PutObject(objectName, strings.NewReader(content))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
    
        // 初始化上传的文件,并设置对象标签。
        imur, err := bucket.InitiateMultipartUpload(destObjectName, oss.SetTagging(tagging))
        if err != nil {
            fmt.Println("Error:", err)
            os.Exit(-1)
        }
        // 将Object分成1个分片进行上传。
        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))
    }

为软链接文件设置标签

以下代码用于为软链接文件设置标签。
package main

import (
  "fmt"
  "os"
  "strings"

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

func main() {
    // 创建OSSClient实例。
    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
    client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

   // 填写Bucket名称,例如examplebucket。
    bucketName := "examplebucket"
    // 填写Object完整路径,例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
    objectName := "exampledir/exampleobject.txt"
    // 填写软链接完整路径,例如shortcut/myobject.txt。
    symlinkName := "shortcut/myobject.txt"

    // 获取存储空间。
    bucket, err := client.Bucket(bucketName)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // 依次填写对象标签的键(例如owner)和值(例如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))
}