调用PutObjectTagging接口设置或更新对象的标签信息_对象存储(OSS)-阿里云帮助中心

调用 PutObjectTagging 接口设置或更新对象（Object）的标签（Tagging）信息。对象标签使用一组键值对（Key-Value）标记对象。

注意事项

单个 Object 最多能设置 10 个标签，Key 不能重复。
每个 Key 长度不能超过 128 字符，每个 Value 长度不能超过 256 字符。
Key 和 Value 区分大小写。
标签的合法字符集包括大小写字母、数字、空格和以下符号：

+‑=._:/

通过 HTTP Header 的方式设置标签且标签中包含任意字符时，您需要对标签的 Key 和 Value 进行 URL 编码。
更改标签信息不会更新 Object 的 Last‑Modified 时间。

关于对象标签的更多信息，请参见对象标签。

版本控制

调用 PutObjectTagging 接口时，默认设置 Object 当前版本的标签信息。您可以通过指定 versionId 参数来设置指定 Object 版本的标签信息。如果 Object 的对应版本为删除标记（Delete Marker），则 OSS 将返回 404 Not Found。

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的 RAM 用户或 RAM 角色默认没有任何权限，需要阿里云账号或账号管理员通过 RAM Policy 或 Bucket Policy 授予操作权限。

API	Action	说明
PutObjectTagging	oss:PutObjectTagging	设置或更新 Object 的标签（Tagging）信息。
PutObjectTagging	oss:PutObjectVersionTagging	设置或更新指定版本 Object 的标签（Tagging）信息。

请求语法

PUT /objectname?tagging
Content‐Length: 114
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: Mon, 18 Mar 2019 08:25:17 GMT
Authorization: SignatureValue
<Tagging>
  <TagSet>
      <Key>Key</Key>
      <Value>Value</Value>
  </TagSet>
</Tagging>

当您在 OSS ON 云盒中调用该接口时，您需要将 Host 替换为云盒 Endpoint。更多信息，请参见云盒 Endpoint 。

请求元素

名称	类型	是否必选	示例值	描述
Tagging	容器	是	不涉及	标签集合。子节点：TagSet
TagSet	容器	是	不涉及	标签集合。父节点：Tagging 子节点：Tag
Tag	容器	否	不涉及	标签集合。父节点：TagSet 子节点：Key、Value
Key	字符串	否	a	标签键。父节点：Tag 子节点：无
Value	字符串	否	1	标签值。父节点：Tag 子节点：无

此接口还涉及其他公共请求头。更多信息，请参见公共请求头（Common Request Headers）。

示例

未开启版本控制

在未开启版本控制情况下，针对存储空间 bucketname 中的对象 objectname，通过 PUT 请求设置{a:1}和{b:2}两个标签。标签设置成功后返回 200 (OK)。

请求示例

PUT /objectname?tagging
Content‐Length: 114
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: Mon, 18 Mar 2019 08:25:17 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<Tagging>
  <TagSet>
      <Key>a</Key>
      <Value>1</Value>
      <Key>b</Key>
      <Value>2</Value>
  </TagSet>
</Tagging>

返回示例

200 (OK)
content‐length: 0
server: AliyunOSS
connection: keep-alive
x‐oss‐request‐id: 5C8F55ED461FB4A64C00****
date: Mon, 18 Mar 2019 08:25:17 GMT

已启用版本控制

在启用了版本控制的情况下，针对存储空间 bucketname 中的对象 objectname 的指定版本（即请求示例中的 versionId），通过 PUT 请求设置{age:18}标签。标签设置成功后返回 200 (OK)。

请求示例

PUT /objectname?tagging&versionId=CAEQExiBgID.jImWlxciIDQ2ZjgwODIyNDk5MTRhNzBiYmQwYTZkMTYzZjM0****
Content-Length: 90
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 24 Jun 2020 08:58:15 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<Tagging>
  <TagSet>
      <Key>age</Key>
      <Value>18</Value>
  </TagSet>
</Tagging>

返回示例

200 (OK)
content-length: 0
server: AliyunOSS
connection: keep-alive
x-oss-request-id: 5EF315A7FBD3EC3232B4****
date: Wed, 24 Jun 2020 08:58:15 GMT
x-oss-version-id: CAEQExiBgID.jImWlxciIDQ2ZjgwODIyNDk5MTRhNzBiYmQwYTZkMTYzZjM0****

SDK

PutObjectTagging 接口对应的各语言 SDK 示例如下：

命令行工具 ossutil

PutObjectTagging 接口所对应的 ossutil 命令，请参见 put-object-tagging 。