AI 助理
备案控制台
文档
输入文档关键字查找
首页 对象存储 开发参考 SDK参考 Python 对象/文件 管理文件 对象标签 设置对象标签

设置对象标签

更新时间：
产品详情
相关技术圈
我的收藏

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

背景信息

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

  • 您可以在上传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）来标记对象。关于对象标签的更多信息，请参见对象标签。

注意事项

  • 本文以华东1（杭州）外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见访问域名和数据中心。

  • 本文以OSS域名新建OSSClient为例。如果您希望通过自定义域名、STS等方式新建OSSClient，请参见初始化。

  • 要设置对象标签，您必须具有oss:PutObjectTagging权限。具体操作，请参见为RAM用户授权自定义的权限策略。

上传Object时添加对象标签

  • 简单上传时添加对象标签

    以下代码用于简单上传Object时添加对象标签。

    # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'

# 设置tagging字符串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果标签中包含了任意字符，则需要对标签的Key和Value做URL编码。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中设置标签信息。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 调用put_object接口时指定headers，将会为上传的文件添加标签。
result = bucket.put_object(object_name, 'content', headers=headers)
print('http response status: ', result.status)

# 查看Object的标签信息。
result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

  • 分片上传时添加对象标签

    以下代码用于通过multipart_upload方式上传Object时添加对象标签。 

    # -*- coding: utf-8 -*-

import os
import oss2
from oss2 import SizedFileAdapter, determine_part_size
from oss2.models import PartInfo
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填写本地文件的完整路径，例如D:\\localpath\\examplefile.txt。
# 如果未指定本地路径只填写了文件名称（例如examplefile.txt），则默认从示例程序所属项目对应本地路径中上传文件。
filename = 'D:\\localpath\\examplefile.txt'

total_size = os.path.getsize(filename)
# determine_part_size方法用于确定分片大小。
part_size = determine_part_size(total_size, preferred_size=100 * 1024)

# 设置tagging字符串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果标签中包含了任意字符，则需要对标签的Key和Value做URL编码。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中设置标签信息。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 初始化分片。
# 调用init_multipart_upload接口时指定headers，将会给上传的文件添加标签。
upload_id = bucket.init_multipart_upload(object_name, headers=headers).upload_id
parts = []

# 逐个上传分片。
with open(filename, 'rb') as fileobj:
    part_number = 1
    offset = 0
    while offset < total_size:
        num_to_upload = min(part_size, total_size - offset)
        # SizedFileAdapter(fileobj, size)方法会生成一个新的文件对象，重新计算起始追加位置。
        result = bucket.upload_part(object_name, upload_id, part_number,
                                    SizedFileAdapter(fileobj, num_to_upload))
        parts.append(PartInfo(part_number, result.etag))

        offset += num_to_upload
        part_number += 1

# 完成分片上传。
result = bucket.complete_multipart_upload(object_name, upload_id, parts)
print('http response status: ', result.status)

# 查看Object的标签信息。
result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 验证分片上传。
with open(filename, 'rb') as fileobj:
    assert bucket.get_object(object_name).read() == fileobj.read()

  • 追加上传时添加对象标签

    以下代码用于通过append_object方式上传Object时添加对象标签。 

    # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'

# 设置tagging字符串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果标签中包含了任意字符，则需要对标签的Key和Value做URL编码。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中设置标签信息。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 追加上传文件。调用append_object接口时指定headers，将会给文件设置标签。
# 只有第一次调用append_object设置的标签才会生效，后续使用此种方式添加的标签不生效。
result = bucket.append_object(object_name, 0, '<yourContent>', headers=headers)

# 查看Object的标签信息。
result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

  • 断点续传上传时添加对象标签

    以下代码用于通过resumable_upload方式上传Object时添加对象标签。

    # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填写本地文件的完整路径。如果未指定本地路径，则默认从示例程序所属项目对应本地路径中上传文件。
local_file = 'D:\\localpath\\examplefile.txt'

# 设置tagging字符串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果标签中包含了任意字符，则需要对标签的Key和Value做URL编码。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中设置标签信息。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 当文件长度大于或等于可选参数multipart_threshold（默认值为10 MB）时使用分片上传。如果未使用参数store指定目录，则会在HOME目录下建立.py-oss-upload目录来保存断点信息。
# 调用resumable_upload接口时指定headers，将会给上传的文件添加标签。
oss2.resumable_upload(bucket, object_name, local_file, headers=headers)

result = bucket.get_object_tagging(object_name)
for key in result.tag_set.tagging_rule:
    print('object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

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

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

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

# -*- coding: utf-8 -*-

import oss2
from oss2.models import Tagging, TaggingRule
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
#填写Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'

# 创建标签规则。
rule = TaggingRule()
rule.add('key1', 'value1')
rule.add('key2', 'value2')

# 创建标签。
tagging = Tagging(rule)

# 设置标签。
result = bucket.put_object_tagging(object_name, tagging)
# 查看HTTP返回码。
print('http response status:', result.status)

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

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

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

说明

关于获取versionId的具体操作，请参见列举文件。

# -*- coding: utf-8 -*-

import oss2
from oss2.models import Tagging
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
#填写Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填写Object的版本ID，例如CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****。
version_id = 'CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****'

tagging = Tagging()
# 依次填写对象标签的键（例如owner）和值（例如John）。
tagging.tag_set.add('owner', 'John')
tagging.tag_set.add('type', 'document')

params = dict()
params['versionId'] = version_id

bucket.put_object_tagging(object_name, tagging, params=params)

拷贝Object时设置对象标签

拷贝Object时，可以指定如何设置目标Object的对象标签。取值如下：

  • Copy（默认值）：复制源Object的对象标签到目标Object。

  • Replace：忽略源Object的对象标签，直接采用请求中指定的对象标签。

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

  • 简单拷贝时设置对象标签

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

    # -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING, OSS_OBJECT_TAGGING_COPY_DIRECTIVE
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写源Object完整路径，Object完整路径中不能包含Bucket名称。例如srcexampledir/exampleobject.txt。
src_object_name = 'srcexampledir/exampleobject.txt'
# 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如destexampledir1/exampleobject.txt。
dest_object_name1 = 'destexampledir1/exampleobject.txt'
# 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如destexampledir2/exampleobject.txt。
dest_object_name2 = 'destexampledir2/exampleobject.txt'

# 设置tagging字符串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果标签中包含了任意字符，则需要对标签的Key和Value做URL编码。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中指定OSS_OBJECT_TAGGING_COPY_DIRECTIVE参数为COPY或者默认不指定，则dest_object_name1将拥有与源文件相同的标签信息。
headers=dict()
headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'COPY'
bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name1, headers=headers)

# 在HTTP header中指定OSS_OBJECT_TAGGING_COPY_DIRECTIVE参数为REPLACE，则dest_object_name2的标签信息将会设置为headers[OSS_OBJECT_TAGGING]指定的标签信息。
headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'REPLACE'
headers[OSS_OBJECT_TAGGING] = tagging
bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name2, headers=headers)

# 查看src_object_name的标签信息。
result = bucket.get_object_tagging(src_object_name)
for key in result.tag_set.tagging_rule:
    print('src tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 查看dest_object_name1的标签信息。dest_object_name1的标签信息与src_object_name的标签信息相同。
result = bucket.get_object_tagging(dest_object_name1)
for key in result.tag_set.tagging_rule:
    print('dest1 object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 查看dest_object_name2的标签信息。dest_object_name2的标签信息为headers[OSS_OBJECT_TAGGING]指定的标签信息。
result = bucket.get_object_tagging(dest_object_name2)
for key in result.tag_set.tagging_rule:
    print('dest2 object tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

  • 分片拷贝时设置对象标签

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

    # -*- coding: utf-8 -*-

import os
import oss2
from oss2 import determine_part_size
from oss2.models import PartInfo
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写源Object完整路径，Object完整路径中不能包含Bucket名称。例如srcexampledir/exampleobject.txt。
src_object_name = 'srcexampledir/exampleobject.txt'
# 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如destexampledir/exampleobject.txt。
dest_object_name = 'destexampledir/exampleobject.txt'

# 获取源文件的文件大小。
head_info = bucket.head_object(src_object_name)
total_size = head_info.content_length
print('src object size:', total_size)

# determine_part_size方法用于确定分片大小。
part_size = determine_part_size(total_size, preferred_size=100 * 1024)
print('part_size:', part_size)

# 设置tagging字符串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果标签中包含了任意字符，则需要对标签的Key和Value做URL编码。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中设置标签信息。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 初始化分片。
# 调用init_multipart_upload接口时指定headers，将会给目标文件添加标签。
upload_id = bucket.init_multipart_upload(dest_object_name, headers=headers).upload_id
parts = []

# 逐个上传分片。
part_number = 1
offset = 0
while offset < total_size:
    num_to_upload = min(part_size, total_size - offset)
    end = offset + num_to_upload - 1;
    result = bucket.upload_part_copy(bucket.bucket_name, src_object_name, (offset, end), dest_object_name, upload_id, part_number)
    #保存part信息
    parts.append(PartInfo(part_number, result.etag))

    offset += num_to_upload
    part_number += 1

# 完成分片上传。
result = bucket.complete_multipart_upload(dest_object_name, upload_id, parts)

# 获取文件元数据。
head_info = bucket.head_object(dest_object_name)

# 查看目标文件大小。
dest_object_size = head_info.content_length
print('dest object size:', dest_object_size)

# 对比源文件大小。
assert dest_object_size == total_size

# 查看源文件的标签信息。
result = bucket.get_object_tagging(src_object_name)
for key in result.tag_set.tagging_rule:
    print('src tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

# 查看目标文件的标签信息。
result = bucket.get_object_tagging(dest_object_name)
for key in result.tag_set.tagging_rule:
    print('dest tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

为软链接文件设置标签

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

# -*- coding: utf-8 -*-

import oss2
from oss2.headers import OSS_OBJECT_TAGGING
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 填写目标Object完整路径，Object完整路径中不能包含Bucket名称。例如exampledir/exampleobject.txt。
object_name = 'exampledir/exampleobject.txt'
# 填写软链接完整路径，例如shortcut/myobject.txt。
symlink_name = 'shortcut/myobject.txt'

# 设置tagging字符串。
tagging = "k1=v1&k2=v2&k3=v3"

# 如果标签中包含了任意字符，则需要对标签的Key和Value做URL编码。
k4 = "k4+-="
v4 = "+-=._:/"
tagging += "&" + oss2.urlquote(k4) + "=" + oss2.urlquote(v4)

# 在HTTP header中设置标签信息。
headers = dict()
headers[OSS_OBJECT_TAGGING] = tagging

# 添加软链接。
# 调用put_symlink接口时指定headers，将会给软链接文件添加标签。
result = bucket.put_symlink(object_name, symlink_name, headers=headers)
print('http response status: ', result.status)

# 查看软链接文件的标签信息。
result = bucket.get_object_tagging(symlink_name)
for key in result.tag_set.tagging_rule:
    print('tagging key: {}, value: {}'.format(key, result.tag_set.tagging_rule[key]))

相关文档

  • 关于设置对象标签的完整示例代码，请参见GitHub示例。

  • 关于设置对象标签的API接口说明，请参见PutObjectTagging。

上一篇：对象标签下一篇：获取对象标签
文档推荐