文档首页/ 对象存储服务 OBS/ 用户指南/ 对象管理/ 管理对象/ 对象标签
更新时间：2026-09-09 GMT+08:00
查看PDF
分享

对象标签

OBS支持为桶内对象设置自定义标签，用于实现数据的精细化分类管理。您可在上传对象时同步添加标签，也可为已有对象追加标签。基于对象标签，既可结合生命周期规则按标签自动转储或清理对象，也可在权限体系中按标签维度控制访问范围，为数据治理、成本优化与安全管控提供统一支撑。

标签规则

OBS支持使用对象标签对桶中的对象进行分类，您可以在上传对象时添加标签，也可以为已有对象添加标签。

对象标签使用一组键值对（Key-Value）标记对象，规则如下：

  • 每个对象最多能设置10个标签。
  • 键名(Key)约束：
    • 指定多个标签时，每个标签的键必须唯一。
    • 标签键最大长度为128个字符，键名不能包含,/|<>=*\这些特殊字符以及ASCII码0x00-0x1F的控制字符，且首尾字符不能为空格，区分大小写，不可重复，不能为空。在发送到服务器之前，必须将键名进行UrlEncode编码。
  • 键值（Value）约束：

    标签值最大长度为255个字符，不能包含,/|<>=*\这些特殊字符以及ASCII码0x00-0x1F的控制字符，且首尾字符不能为空格，区分大小写，可以为空。在发送到服务器之前，必须将键值进行UrlEncode编码。

注意事项

  • 对象标签功能目前在公测阶段，免费使用；公测结束后，将收取费用。
  • 用户读写对象标签必须拥有对应标签操作权限，当前可通过设置桶策略授权给其他用户。默认情况下只有对象的所有者可以执行此操作。
  • 用户可在PUT上传、分段上传、上传、复制对象过程中设置标签，也可以对已上传的对象设置标签。
  • 设置或更改对象标签不会改变对象的Lastmodified时间。
  • 并行文件系统不支持给文件添加标签。

权限控制

只有对象拥有者和被授予以下权限的用户才能进行对象标签相关操作。您可以使用IAM或桶策略进行授权，授权操作请参见创建IAM自定义策略或自定义创建桶策略。

  • 桶未开启多版本控制时需要获取的权限：
    • 设置对象标签：obs:object:PutObjectTagging
    • 获取对象标签：obs:object:GetObjectTagging
    • 删除对象标签：obs:object:DeleteObjectTagging
  • 桶开启了多版本控制时需要获取的权限：
    • 设置对象标签：obs:object:PutObjectVersionTagging
    • 获取对象标签：obs:object:GetObjectVersionTagging
    • 删除对象标签：obs:object:DeleteObjectVersionTagging

如果您在 IAM 用户或角色策略中拥有设置对象标签的权限或授权，但是设置失败，可能是SCP策略或桶策略中该权限里包含了Deny语句。请先放开该权限，然后再进行对象标签相关操作。

例如：允许用户访问具有特定标签的对象，其权限配置策略见授权IAM用户操作指定标签的对象。

使用场景

对象标签结合生命周期：

针对周期性产生的临时文件，建议在上传时为其添加对象标签，再由生命周期规则按标签匹配定期删除，实现空间自动释放与存储费用优化。在桶生命周期配置中，可以指定筛选条件以选择该规则适用的一部分对象。可以基于键名前缀、对象标签或两者指定筛选条件。例如以下规则适用于桶中前缀为texta/，标签为（Key等于key1,Value等于value1）、（Key等于key2,Value等于value2）的对象，对象在创建120天后被删除。 
<LifecycleConfiguration>
    <Rule>
        <ID>sample-rule</ID>  
        <Filter>
            <And>
                <Prefix>texta/</Prefix>
                <Tag>
                    <Key>key1</Key>
                    <Value>value1</Value>
                </Tag>
                <Tag>
                    <Key>key2</Key>
                    <Value>value2</Value>
                </Tag>
            </And>
        </Filter>
        <Status>Enabled</Status>
        <Expiration>
            <Days>120</Days>
        </Expiration>
    </Rule>
</LifecycleConfiguration>
  • 授权IAM用户操作指定标签的对象。

    对象标签可用于管理权限的精细访问控制。例如，您可以通过IAM Policy授权IAM用户访问Key为key2、Value为value2的所有Object，IAM Policy配置示例如下：

    {
	"Statement": [{
		"Effect": "Allow",
		"Action": ["GetObject"],
		"Resource": "*",
		"Condition": {
			"StringEquals": {
				"ExistingObjectTag/key2":["value2"]
			}
		}
	}]
}

使用方式

OBS支持通过管理控制台、API、SDK、obsutil方式配置对象标签，不支持通过OBS Browser+方式配置对象标签。

使用OBS控制台

OBS管理控制台支持在上传对象时为对象添加标签，具体请参见上传对象；同时也支持为已有对象添加标签，具体步骤如下：

  1. 在OBS管理控制台左侧导航栏选择“桶列表”。
  2. 在桶列表中，单击待操作的桶，进入“对象”页面。
  3. 单击待添加标签的对象名称，进入“基本信息”页签。
  4. 切换至“标签”页签，单击“添加标签”。
  5. 在“添加标签”对话框，填写标签键和标签值。

    表1 参数说明

    参数

    说明

    标签键

    输入标签的键，同一个对象标签的键不能重复，并且不能为空。可以自定义，也可以选择预先在标签管理服务（TMS）创建好的标签。

    命名规则如下：

    • 键名(Key)约束：
      • 指定多个标签时，每个标签的键必须唯一。
      • 标签键最大长度为128个字符，键名不能包含,/|<>=*\这些特殊字符以及ASCII码0x00-0x1F的控制字符，且首尾字符不能为空格，区分大小写，不可重复，不能为空。在发送到服务器之前，必须将键名进行UrlEncode编码。

    标签值

    输入标签的值，标签的值可以重复，并且可以为空。

    命名规则如下：

    • 键值（Value）约束：

      标签值最大长度为255个字符，不能包含,/|<>=*\这些特殊字符以及ASCII码0x00-0x1F的控制字符，且首尾字符不能为空格，区分大小写，可以为空。在发送到服务器之前，必须将键值进行UrlEncode编码。

  6. 单击“确定”。

使用API

设置对象标签

获取对象标签

删除对象标签

使用SDK

Java

PHP

Python

C

GO

BrowserJS

.NET暂不支持

Android暂不支持

iOS暂不支持

Node.js

使用命令行工具obsutil

命令结构

  • Windows操作系统
    • 设置单个对象标签 
      obsutil object-tagging obs://bucket -method=put -tag key1=value1 -tag keyX=valueX [-tag keyN=valueN] [-versionId=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • 批量设置对象标签 
      obsutil object-tagging obs://bucket -method=put -r [-f] [-v] -tag key1=value1 -tag keyX=valueX [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • macOS/Linux操作系统
    • 设置单个对象标签 
      ./obsutil object-tagging obs://bucket -method=put -tag key1=value1 -tag keyX=valueX [-tag keyN=valueN] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
    • 批量设置对象标签 
      ./obsutil object-tagging obs://bucket -method=put -r [-f] [-v] -tag key1=value1 -tag keyX=valueX [-o=xxx] [-j=1] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

运行示例

  • 以Windows操作系统为例，运行obsutil object-tagging obs://test-bucket/key -method=put -tag key1=value1 -tag key2=value2，指定给桶test-bucket下的对象key设置对象标签，分别是key1 value1和 key2 value2。 
    obsutil object-tagging obs://test-bucket/key -method=put -tag key1=value1 -tag key2=value2 

Start at 2024-09-30 07:59:28.8675681 +0000 UTC

Put tagging object [key] in the bucket [test-bucket] successfully, cost [570] ms, request id [0000019AB61D183F40171C3A0980ACD3]

参数说明

参数

约束

描述

bucket

必选

桶名。

key

可选

待设置对象标签的对象名或对象名前缀。

method

必选

指定方法，设置桶的对象标签时该值为put。

tag

必选

指定对象的标签键值对，格式为key=value。

versionId

附加参数，可选

设置单个对象标签时可指定的对象版本号。

r

附加参数，批量匹配时必选

按设置对象名前缀批量匹配对象。

f

附加参数，批量匹配时可选

强制操作，不进行询问提示。

j

附加参数，批量匹配时可选

批量设置对象标签时的最大并发数，默认为配置文件中的defaultJobs。

说明：

工具会保证该值至少为1。

o

附加参数，可选

生成结果清单文件的文件夹，命令执行完成后，会在该文件夹下生成结果清单文件（可能包含成功结果和失败结果两个文件），默认为运行obsutil命令的用户目录的子文件夹.obsutil_output。

说明：
  • 结果清单文件命名规则：rm_{succeed| failed}_report_时间_TaskId.txt。
  • 单个结果清单文件默认情况下最大为30MB且最大可保留的文件个数为1024，可在配置文件中通过recordMaxLogSize和recordBackups分别配置。
  • 当涉及多文件/文件夹时，如需确认失败任务的具体错误信息，可参考结果清单文件夹下的失败结果清单文件“cp_failed_report_时间_TaskId.txt”和日志路径下的日志文件。

config

附加参数，可选

运行当前命令时的自定义配置文件。可支持的配置参数请参考配置参数说明。

e

附加参数，可选

指定终端节点。

i

附加参数，可选

指定用户的AK。

k

附加参数，可选

指定用户的SK。

t

附加参数，可选

指定用户的securitytoken。

日志与监控

为帮助用户及时感知并处理删除操作，OBS提供了从实时感知到事后审计的完整管控能力。用户可以配置桶日志里对象标签相关的Operation（设置/获取/删除对象标签：REST.PUT.TAGGING/REST.GET.TAGGING/REST.DEL.TAGGING）及CTS支持对象标签相关的操作事件（设置/获取/删除对象标签：setBucketTagging/getBucketTagging/deleteBucketTagging），系统会记录所有对象标签相关操作的详细日志，供用户审计或进一步分析。了解配置监控日志相关操作，请参见使用桶日志记录OBS日志信息。

相关操作

您可以单击“编辑”，修改标签的“值”；也可以单击“删除”，删除标签。

相关文档

  • 用户可通过设定生命周期规则管理对象，了解更多生命周期相关信息，请参见生命周期管理。
  • 用户可通过桶策略设置用户访问指定标签的对象，了解更多桶策略相关信息，请参见配置桶策略。
父主题： 管理对象

相关文档