doc-exports/docs/obs/api-ref/obs_04_0172.html

<a name="obs_04_0172"></a><a name="obs_04_0172"></a>

<h1 class="topictitle1">Adding Object Tags</h1>
<div id="body0000001449405729"><div class="section" id="obs_04_0172__section5584184924715"><h4 class="sectiontitle">Functions</h4><p class="msonormal" id="obs_04_0172__p51265933">This operation adds or updates the tag information for an object. An object tag is a key-value pair.</p>
<p id="obs_04_0172__p1893383131220">If you do not specify a version ID in a request, make sure that you have the <strong id="obs_04_0172__b107309166593">PutObjectTagging</strong> permission. If you do specify a version ID in a request, make sure that you have the <strong id="obs_04_0172__b451418218598">PutObjectTagging</strong> and <strong id="obs_04_0172__b9138145435918">PutObjectVersionTagging</strong> 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.</p>
<p id="obs_04_0172__p52949414437">Tags are added to the current version of an object by default. You can use the <strong id="obs_04_0172__b1474031184413">versionId</strong> parameter to add tags to any other version. If the version you are adding tags to is a delete marker, OBS returns <strong id="obs_04_0172__b57703573235">404 Not Found</strong>.</p>
<div class="note" id="obs_04_0172__note1324115561185"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><ul id="obs_04_0172__ul348262051913"><li id="obs_04_0172__li18802751439">Tags cannot be set for files in parallel file systems.</li><li id="obs_04_0172__li13482820131917">An object can have up to 10 tags.</li><li id="obs_04_0172__li231365192618">Constraints on the tag key and value:<p id="obs_04_0172__p618229112610"><a name="obs_04_0172__li231365192618"></a><a name="li231365192618"></a>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: =*&lt;&gt;\,|/?!;</p>
<p id="obs_04_0172__p835961912267">A tag value is case sensitive and can be left blank. It cannot exceed 255 characters. The following characters are not allowed: =*&lt;&gt;\,|?!;</p>
</li></ul>
</div></div>
</div>
<div class="section" id="obs_04_0172__section58740215"><h4 class="sectiontitle">Request Syntax</h4><pre class="screen" id="obs_04_0172__screen32023046">PUT /objectname?tagging&amp;versionId=versionid HTTP/1.1
Host: <em id="obs_04_0172__i1378765511335">bucketname</em>.obs.region.example.com
Date: date
Authorization: authorization string
Content-MD5: md5
&lt;?xml version="1.0" encoding="UTF-8"&gt;
&lt;Tagging&gt;
    &lt;TagSet&gt;
        &lt;Tag&gt;
            &lt;Key&gt;Key&lt;/Key&gt;
            &lt;Value&gt;Value&lt;/Value&gt;
        &lt;/Tag&gt;
     &lt;/TagSet&gt; 
&lt;/Tagging&gt;</pre>
</div>
<div class="section" id="obs_04_0172__section56492397319"><h4 class="sectiontitle">Request Parameters</h4><p class="msonormal" id="obs_04_0172__p58025057"><a href="#obs_04_0172__table416285709507">Table 1</a> describes the parameters in the request.</p>

<div class="tablenoborder"><a name="obs_04_0172__table416285709507"></a><a name="table416285709507"></a><table cellpadding="4" cellspacing="0" summary="" id="obs_04_0172__table416285709507" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Request parameters</caption><thead align="left"><tr id="obs_04_0172__row57198952"><th align="left" class="cellrowborder" valign="top" width="22.220000000000002%" id="mcps1.3.3.3.2.4.1.1"><p id="obs_04_0172__p2603527">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="62.56%" id="mcps1.3.3.3.2.4.1.2"><p id="obs_04_0172__p18923573">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="15.22%" id="mcps1.3.3.3.2.4.1.3"><p id="obs_04_0172__p37967849">Mandatory</p>
</th>
</tr>
</thead>
<tbody><tr id="obs_04_0172__row36854813"><td class="cellrowborder" valign="top" width="22.220000000000002%" headers="mcps1.3.3.3.2.4.1.1 "><p id="obs_04_0172__p32449872">tagging</p>
</td>
<td class="cellrowborder" valign="top" width="62.56%" headers="mcps1.3.3.3.2.4.1.2 "><p id="obs_04_0172__p11193984">Indicates an object tagging request.</p>
<p id="obs_04_0172__p33636994">Type: string</p>
</td>
<td class="cellrowborder" valign="top" width="15.22%" headers="mcps1.3.3.3.2.4.1.3 "><p id="obs_04_0172__p40241975">Yes</p>
</td>
</tr>
<tr id="obs_04_0172__row26633461"><td class="cellrowborder" valign="top" width="22.220000000000002%" headers="mcps1.3.3.3.2.4.1.1 "><p id="obs_04_0172__p105131831133810">versionId</p>
</td>
<td class="cellrowborder" valign="top" width="62.56%" headers="mcps1.3.3.3.2.4.1.2 "><p id="obs_04_0172__p57765051">ID of the object version that the tag will be added to. Its response header is <strong id="obs_04_0172__b510216511010">x-obs-version-id</strong>.</p>
<p id="obs_04_0172__p50123418">Type: string</p>
</td>
<td class="cellrowborder" valign="top" width="15.22%" headers="mcps1.3.3.3.2.4.1.3 "><p id="obs_04_0172__p33465090">No</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="obs_04_0172__section60336990"><h4 class="sectiontitle">Request Headers</h4><p class="msonormal" id="obs_04_0172__p30257291"><a href="#obs_04_0172__table1385212317506">Table 2</a> describes the headers in the request.</p>

<div class="tablenoborder"><a name="obs_04_0172__table1385212317506"></a><a name="table1385212317506"></a><table cellpadding="4" cellspacing="0" summary="" id="obs_04_0172__table1385212317506" frame="border" border="1" rules="all"><caption><b>Table 2 </b>Request headers</caption><thead align="left"><tr id="obs_04_0172__row385242395013"><th align="left" class="cellrowborder" valign="top" width="22.220000000000002%" id="mcps1.3.4.3.2.4.1.1"><p id="obs_04_0172__p11852823175015">Header</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="62.56%" id="mcps1.3.4.3.2.4.1.2"><p id="obs_04_0172__p1285218239505">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="15.22%" id="mcps1.3.4.3.2.4.1.3"><p id="obs_04_0172__p10852162314507">Mandatory</p>
</th>
</tr>
</thead>
<tbody><tr id="obs_04_0172__row1385212318502"><td class="cellrowborder" valign="top" width="22.220000000000002%" headers="mcps1.3.4.3.2.4.1.1 "><p id="obs_04_0172__p9852102320501">Content-MD5</p>
</td>
<td class="cellrowborder" valign="top" width="62.56%" headers="mcps1.3.4.3.2.4.1.2 "><p id="obs_04_0172__p1115521520519">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.</p>
<p id="obs_04_0172__p11155151515512">Type: string</p>
<p id="obs_04_0172__p15155171585116">Example: <strong id="obs_04_0172__b52512151188">n58IG6hfM7vqI4K0vnWpog==</strong></p>
</td>
<td class="cellrowborder" valign="top" width="15.22%" headers="mcps1.3.4.3.2.4.1.3 "><p id="obs_04_0172__p885211233507">Yes</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="obs_04_0172__section6162005"><h4 class="sectiontitle">Request Elements</h4><p class="msonormal" id="obs_04_0172__p45858078">In this request body, you need to configure the object tags in XML. <a href="#obs_04_0172__table1181123018399">Table 3</a> describes the tag elements to be configured.</p>

<div class="tablenoborder"><a name="obs_04_0172__table1181123018399"></a><a name="table1181123018399"></a><table cellpadding="4" cellspacing="0" summary="" id="obs_04_0172__table1181123018399" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Object tag elements</caption><thead align="left"><tr id="obs_04_0172__row2018917307393"><th align="left" class="cellrowborder" valign="top" width="22.430000000000003%" id="mcps1.3.5.3.2.4.1.1"><p id="obs_04_0172__p19190143043913">Header</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="53.260000000000005%" id="mcps1.3.5.3.2.4.1.2"><p id="obs_04_0172__p019273012397">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="24.310000000000002%" id="mcps1.3.5.3.2.4.1.3"><p id="obs_04_0172__p2195113033915">Mandatory</p>
</th>
</tr>
</thead>
<tbody><tr id="obs_04_0172__row7197230193913"><td class="cellrowborder" valign="top" width="22.430000000000003%" headers="mcps1.3.5.3.2.4.1.1 "><p id="obs_04_0172__p125361017184212">Tagging</p>
</td>
<td class="cellrowborder" valign="top" width="53.260000000000005%" headers="mcps1.3.5.3.2.4.1.2 "><p id="obs_04_0172__p6536111718422">Root element for TagSet and Tag</p>
<p id="obs_04_0172__p85368172423">Type: container</p>
<p id="obs_04_0172__p125365178429">Parent: none</p>
</td>
<td class="cellrowborder" valign="top" width="24.310000000000002%" headers="mcps1.3.5.3.2.4.1.3 "><p id="obs_04_0172__p553681720423">Yes</p>
</td>
</tr>
<tr id="obs_04_0172__row12641636422"><td class="cellrowborder" valign="top" width="22.430000000000003%" headers="mcps1.3.5.3.2.4.1.1 "><p id="obs_04_0172__p3911152616425">TagSet</p>
</td>
<td class="cellrowborder" valign="top" width="53.260000000000005%" headers="mcps1.3.5.3.2.4.1.2 "><p id="obs_04_0172__p591252604217">A collection for a set of tags.</p>
<p id="obs_04_0172__p391202634216">Type: container</p>
<p id="obs_04_0172__p4912142604210">Parent: Tagging</p>
</td>
<td class="cellrowborder" valign="top" width="24.310000000000002%" headers="mcps1.3.5.3.2.4.1.3 "><p id="obs_04_0172__p3912326144211">Yes</p>
</td>
</tr>
<tr id="obs_04_0172__row944320444211"><td class="cellrowborder" valign="top" width="22.430000000000003%" headers="mcps1.3.5.3.2.4.1.1 "><p id="obs_04_0172__p163325395428">Tag</p>
</td>
<td class="cellrowborder" valign="top" width="53.260000000000005%" headers="mcps1.3.5.3.2.4.1.2 "><p id="obs_04_0172__p8333639114218">Information element of Tag</p>
<p id="obs_04_0172__p1233323919429">Type: container</p>
<p id="obs_04_0172__p0333163974214">Parent: TagSet</p>
</td>
<td class="cellrowborder" valign="top" width="24.310000000000002%" headers="mcps1.3.5.3.2.4.1.3 "><p id="obs_04_0172__p333319390424">Yes</p>
</td>
</tr>
<tr id="obs_04_0172__row1314615104218"><td class="cellrowborder" valign="top" width="22.430000000000003%" headers="mcps1.3.5.3.2.4.1.1 "><p id="obs_04_0172__p11495174818425">Key</p>
</td>
<td class="cellrowborder" valign="top" width="53.260000000000005%" headers="mcps1.3.5.3.2.4.1.2 "><p id="obs_04_0172__p74952488427">Tag name</p>
<p id="obs_04_0172__p1349514814423">Type: string</p>
<p id="obs_04_0172__p149512481428">Parent: Tag</p>
</td>
<td class="cellrowborder" valign="top" width="24.310000000000002%" headers="mcps1.3.5.3.2.4.1.3 "><p id="obs_04_0172__p18495154864216">Yes</p>
</td>
</tr>
<tr id="obs_04_0172__row13866105154213"><td class="cellrowborder" valign="top" width="22.430000000000003%" headers="mcps1.3.5.3.2.4.1.1 "><p id="obs_04_0172__p196161654134219">Value</p>
</td>
<td class="cellrowborder" valign="top" width="53.260000000000005%" headers="mcps1.3.5.3.2.4.1.2 "><p id="obs_04_0172__p19616854174215">Tag value</p>
<p id="obs_04_0172__p7616135414424">Type: string</p>
<p id="obs_04_0172__p2616105415423">Parent: Tag</p>
</td>
<td class="cellrowborder" valign="top" width="24.310000000000002%" headers="mcps1.3.5.3.2.4.1.3 "><p id="obs_04_0172__p11616115484210">Yes</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="obs_04_0172__section52164611437"><h4 class="sectiontitle">Response Syntax</h4><div class="codecoloring" codetype="Xml" id="obs_04_0172__screen58137431151033"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span></pre></div></td><td class="code"><div><pre><span></span>HTTP/1.1<span class="w"> </span>status_code
x-obs-request-id:<span class="w"> </span>request<span class="w"> </span>id
x-obs-id-2:<span class="w"> </span>id
Content-Length:<span class="w"> </span>length
Date:<span class="w"> </span>date
</pre></div></td></tr></table></div>
</div>
</div>
<div class="section" id="obs_04_0172__section1253385718430"><h4 class="sectiontitle">Response Headers</h4><p id="obs_04_0172__p1610494415574">This response uses common headers. For details, see <a href="obs_04_0013.html#obs_04_0013__d0e686">Table 1</a>.</p>
</div>
<div class="section" id="obs_04_0172__section7363166184419"><h4 class="sectiontitle">Response Elements</h4><p id="obs_04_0172__p1281810185018">This response contains no elements.</p>
</div>
<div class="section" id="obs_04_0172__section8123191694414"><h4 class="sectiontitle">Error Responses</h4><p id="obs_04_0172__p45601120165018">In addition to common error codes, this API also returns others. <a href="#obs_04_0172__table12876123320500">Table 4</a> lists the common errors and possible causes.</p>

<div class="tablenoborder"><a name="obs_04_0172__table12876123320500"></a><a name="table12876123320500"></a><table cellpadding="4" cellspacing="0" summary="" id="obs_04_0172__table12876123320500" frame="border" border="1" rules="all"><caption><b>Table 4 </b>Error codes of object tagging</caption><thead align="left"><tr id="obs_04_0172__row6301134115016"><th align="left" class="cellrowborder" valign="top" width="33.67%" id="mcps1.3.9.3.2.4.1.1"><p id="obs_04_0172__p183043420504">Error Code</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="51.019999999999996%" id="mcps1.3.9.3.2.4.1.2"><p id="obs_04_0172__p2303340505">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="15.310000000000002%" id="mcps1.3.9.3.2.4.1.3"><p id="obs_04_0172__p330834115019">HTTP Status Code</p>
</th>
</tr>
</thead>
<tbody><tr id="obs_04_0172__row5311834135013"><td class="cellrowborder" valign="top" width="33.67%" headers="mcps1.3.9.3.2.4.1.1 "><p id="obs_04_0172__p5311234185014">InvalidTag</p>
</td>
<td class="cellrowborder" valign="top" width="51.019999999999996%" headers="mcps1.3.9.3.2.4.1.2 "><p id="obs_04_0172__p1231143405016">The provided object tag was invalid.</p>
</td>
<td class="cellrowborder" valign="top" width="15.310000000000002%" headers="mcps1.3.9.3.2.4.1.3 "><p id="obs_04_0172__p631134165012">400</p>
</td>
</tr>
<tr id="obs_04_0172__row173123414508"><td class="cellrowborder" valign="top" width="33.67%" headers="mcps1.3.9.3.2.4.1.1 "><p id="obs_04_0172__p261410266118">BadRequest</p>
</td>
<td class="cellrowborder" valign="top" width="51.019999999999996%" headers="mcps1.3.9.3.2.4.1.2 "><p id="obs_04_0172__p352143810111">The number of object tags exceeded the upper limit.</p>
</td>
<td class="cellrowborder" valign="top" width="15.310000000000002%" headers="mcps1.3.9.3.2.4.1.3 "><p id="obs_04_0172__p12323342506">400</p>
</td>
</tr>
<tr id="obs_04_0172__row117591042161110"><td class="cellrowborder" valign="top" width="33.67%" headers="mcps1.3.9.3.2.4.1.1 "><p id="obs_04_0172__p55551601122">MalformedXML</p>
</td>
<td class="cellrowborder" valign="top" width="51.019999999999996%" headers="mcps1.3.9.3.2.4.1.2 "><p id="obs_04_0172__p755513051220">The XML file was malformed.</p>
</td>
<td class="cellrowborder" valign="top" width="15.310000000000002%" headers="mcps1.3.9.3.2.4.1.3 "><p id="obs_04_0172__p127594425112">400</p>
</td>
</tr>
<tr id="obs_04_0172__row19456102595911"><td class="cellrowborder" valign="top" width="33.67%" headers="mcps1.3.9.3.2.4.1.1 "><p id="obs_04_0172__p045652516598">EntityTooLarge</p>
</td>
<td class="cellrowborder" valign="top" width="51.019999999999996%" headers="mcps1.3.9.3.2.4.1.2 "><p id="obs_04_0172__p174567254595">The request body was too long.</p>
</td>
<td class="cellrowborder" valign="top" width="15.310000000000002%" headers="mcps1.3.9.3.2.4.1.3 "><p id="obs_04_0172__p17456142585913">400</p>
</td>
</tr>
<tr id="obs_04_0172__row24101846111110"><td class="cellrowborder" valign="top" width="33.67%" headers="mcps1.3.9.3.2.4.1.1 "><p id="obs_04_0172__p08055913127">AccessDenied</p>
</td>
<td class="cellrowborder" valign="top" width="51.019999999999996%" headers="mcps1.3.9.3.2.4.1.2 "><p id="obs_04_0172__p148059961215">No permission to configure object tags.</p>
</td>
<td class="cellrowborder" valign="top" width="15.310000000000002%" headers="mcps1.3.9.3.2.4.1.3 "><p id="obs_04_0172__p14101461118">403</p>
</td>
</tr>
<tr id="obs_04_0172__row774519135122"><td class="cellrowborder" valign="top" width="33.67%" headers="mcps1.3.9.3.2.4.1.1 "><p id="obs_04_0172__p5498211125">MethodNotAllowed</p>
</td>
<td class="cellrowborder" valign="top" width="51.019999999999996%" headers="mcps1.3.9.3.2.4.1.2 "><p id="obs_04_0172__p249172110120">Method not allowed, because the corresponding feature was not enabled.</p>
</td>
<td class="cellrowborder" valign="top" width="15.310000000000002%" headers="mcps1.3.9.3.2.4.1.3 "><p id="obs_04_0172__p1974581310120">405</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="obs_04_0172__section14819157124617"><h4 class="sectiontitle">Sample Request</h4><div class="codecoloring" codetype="Xml" id="obs_04_0172__screen42901510155312"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span></pre></div></td><td class="code"><div><pre><span></span>PUT<span class="w"> </span>/objectname?tagging<span class="err">&amp;</span>versionId=G001018455096CE600005306000000DD<span class="w"> </span>HTTP/1.1
User-Agent:<span class="w"> </span>curl/7.29.0
Host:<span class="w"> </span>examplebucket.obs.region.example.com
Accept:<span class="w"> </span>*/*
Date:<span class="w"> </span>Wed,<span class="w"> </span>27<span class="w"> </span>Jun<span class="w"> </span>2018<span class="w"> </span>13:22:50<span class="w"> </span>GMT
Authorization:<span class="w"> </span>OBS<span class="w"> </span>H4IPJX0TQTHTHEBQQCEC:Pf1ZyGvVYg2BzOjokZ/BAeR1mEQ=
Content-MD5:<span class="w"> </span>MnAEvkfQIGnBpchOE2U6Og==
Content-Length:<span class="w"> </span>182
<span class="nt">&lt;Tagging</span><span class="w"> </span><span class="na">xmlns=</span><span class="s">&quot;http://obs.region.example.com/doc/2015-06-30/&quot;</span><span class="nt">&gt;</span>
<span class="w">  </span><span class="nt">&lt;TagSet&gt;</span>
<span class="w">    </span><span class="nt">&lt;Tag&gt;</span>
<span class="w">      </span><span class="nt">&lt;Key&gt;</span>TagName1<span class="nt">&lt;/Key&gt;</span>
<span class="w">      </span><span class="nt">&lt;Value&gt;</span>TageSetVaule1<span class="nt">&lt;/Value&gt;</span>
<span class="w">    </span><span class="nt">&lt;/Tag&gt;</span>
<span class="w">  </span><span class="nt">&lt;/TagSet&gt;</span>
<span class="nt">&lt;/Tagging&gt;</span>
</pre></div></td></tr></table></div>
</div>
</div>
<div class="section" id="obs_04_0172__section13755536443"><h4 class="sectiontitle">Sample Response</h4><div class="codecoloring" codetype="Xml" id="obs_04_0172__screen18548202314552"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span></pre></div></td><td class="code"><div><pre><span></span>HTTP/1.1<span class="w"> </span>200<span class="w"> </span>OK
Server:<span class="w"> </span>OBS
x-obs-request-id:<span class="w"> </span>BF26000001643FEBA09B1ED46932CD07
x-obs-id-2:<span class="w"> </span>32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSEZp87iEirC6DggPB5cN49pSvHBWClg
Date:<span class="w"> </span>Wed,<span class="w"> </span>27<span class="w"> </span>Jun<span class="w"> </span>2018<span class="w"> </span>13:22:50<span class="w"> </span>GMT
</pre></div></td></tr></table></div>
</div>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="obs_04_0079.html">Operations on Objects</a></div>
</div>
</div>