Adding Object Tags

Updated on 2025-03-11 GMT+08:00

View PDF

Functions

This operation adds or updates the tag information for an object. An object tag is a key-value pair.

If you do not specify a version ID in a request, make sure that you have the PutObjectTagging permission. If you do specify a version ID in a request, make sure that you have the PutObjectTagging and PutObjectVersionTagging permissions. By default, only the object owner can perform this operation. The object owner can grant this permission to others by using a bucket or user policy.

Tags are added to the current version of an object by default. You can use the versionId parameter to add tags to any other version. If the version you are adding tags to is a delete marker, OBS returns 404 Not Found.

NOTE:

Tags cannot be set for files in parallel file systems.
An object can have up to 10 tags.
Constraints on the tag key and value:
A tag key is case sensitive and must be unique. It cannot be left blank or exceed 128 characters. The following characters are not allowed: =*<>\,|/?!;

A tag value is case sensitive and can be left blank. It cannot exceed 255 characters. The following characters are not allowed: =*<>\,|?!;

Request Syntax

PUT /objectname?tagging&versionId=versionid HTTP/1.1
Date: date
Authorization: authorization string
Content-MD5: md5
<?xml version="1.0" encoding="UTF-8">
<Tagging>
    <TagSet>
        <Tag>
            <Key>Key</Key>
            <Value>Value</Value>
        </Tag>
     </TagSet> 
</Tagging>

Request Parameters

Table 1 describes the parameters in the request.

**Table 1** Request parameters
Parameter	Description	Mandatory
tagging	Indicates an object tagging request. Type: string	Yes
versionId	ID of the object version that the tag will be added to. Its response header is x-obs-version-id. Type: string	No

Request Headers

Table 2 describes the headers in the request.

**Table 2** Request headers
Header	Description	Mandatory
Content-MD5	Base64-encoded 128-bit MD5 digest of the message according to RFC 1864. You can also configure the Content-SHA256 header whose value is the Base64-encoded SHA-256 digest of the message. Configure either Content-MD5 or Content-SHA256. Type: string Example: n58IG6hfM7vqI4K0vnWpog==	Yes

Request Elements

In this request body, you need to configure the object tags in XML. Table 3 describes the tag elements to be configured.

**Table 3** Object tag elements
Header	Description	Mandatory
Tagging	Root element for TagSet and Tag Type: container Parent: none	Yes
TagSet	A collection for a set of tags. Type: container Parent: Tagging	Yes
Tag	Information element of Tag Type: container Parent: TagSet	Yes
Key	Tag name Type: string Parent: Tag	Yes
Value	Tag value Type: string Parent: Tag	Yes

Response Syntax

    
       HTTP/1.1 status_code
x-obs-request-id: request id
x-obs-id-2: id
Content-Length: length
Date: date

Response Headers

This response uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

Error Responses

In addition to common error codes, this API also returns others. Table 4 lists the common errors and possible causes.

**Table 4** Error codes of object tagging
Error Code	Description	HTTP Status Code
InvalidTag	The provided object tag was invalid.	400
BadRequest	The number of object tags exceeded the upper limit.	400
MalformedXML	The XML file was malformed.	400
EntityTooLarge	The request body was too long.	400
AccessDenied	No permission to configure object tags.	403
MethodNotAllowed	Method not allowed, because the corresponding feature was not enabled.	405

Sample Request

    
     
       
       PUT /objectname?tagging&versionId=G001018455096CE600005306000000DD HTTP/1.1
User-Agent: curl/7.29.0
Accept: */*
Date: Wed, 27 Jun 2018 13:22:50 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:Pf1ZyGvVYg2BzOjokZ/BAeR1mEQ=
Content-SHA256: ogX9qClMrVJUBiUSIKDFM0qO41jJM0I5SCN55/OtMyI=
Content-Length: 182
  <TagSet>
    <Tag>
      <Key>TagName1</Key>
      <Value>TageSetVaule1</Value>
    </Tag>
  </TagSet>
</Tagging>

      

    
   

Sample Response

    
       HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF26000001643FEBA09B1ED46932CD07
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSEZp87iEirC6DggPB5cN49pSvHBWClg
Date: Wed, 27 Jun 2018 13:22:50 GMT