Go设置对象标签 - 对象存储 OSS

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

注意事项

本文以华东1（杭州）外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见访问域名和数据中心。
本文以OSS域名新建OSSClient为例。如果您希望通过自定义域名、STS等方式新建OSSClient，请参见Go初始化。
要设置对象标签，您必须具有oss:PutObjectTagging权限。具体操作，请参见为RAM用户授权自定义的权限策略。

背景信息

设置对象标签时，请注意以下事项：

您可以在上传Object时设置对象标签，也可以对已上传Object设置对象标签。设置对象标签时，如果对象已有标签，则覆盖原标签。关于设置对象标签的更多信息，请参见PutObjectTagging。
设置对象标签时，您要有PutObjectTagging权限。
请通过脚本配置方式创建以上自定义权限策略，然后为指定的RAM用户授予相应权限。具体操作，请参见为RAM用户授权自定义的权限策略。
更改标签时不会更新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完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
    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完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
    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完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
    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完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
    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完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
    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的具体操作，请参见Go列举文件。

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完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
    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完整路径，Object完整路径中不能包含Bucket名称。例如srcexampledir/exampleobject.txt。
    srcObjectName := "srcexampledir/exampleobject.txt"
    // 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如destexampledir1/exampleobject.txt。
    destObjectName1 := "destexampledir1/exampleobject.txt"
    // 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如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完整路径，Object完整路径中不能包含Bucket名称。例如srcexampledir/exampleobject.txt。
    srcObjectName := "srcexampledir/exampleobject.txt"
    // 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如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完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
    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))
}