doc-exports/docs/obs/s3api/en-us_topic_0125560444.html

<a name="EN-US_TOPIC_0125560444"></a><a name="EN-US_TOPIC_0125560444"></a>

<h1 class="topictitle1">PUT Bucket versioning</h1>
<div id="body39379979"><p id="EN-US_TOPIC_0125560444__p13848147142614">You can use this operation to enable or suspend versioning for a bucket.</p>
<p class="msonormal" id="EN-US_TOPIC_0125560444__p24721334">Versioning can be used to restore an object that is incorrectly overwritten or deleted. You can use versioning to save, query, and restore objects of different versions. Versioning allows you to easily recover data lost due to misoperations or program faults. Versioning can also be used for retaining and archiving data.</p>
<p class="msonormal" id="EN-US_TOPIC_0125560444__p21165417">By default, versioning is disabled for a bucket.</p>
<p class="msonormal" id="EN-US_TOPIC_0125560444__p62515791">Once WORM is enabled for a bucket, OBS automatically enables versioning for the bucket and the versioning cannot be suspended for that bucket.</p>
<p class="msonormal" id="EN-US_TOPIC_0125560444__p36677197">After the versioning state is set to <strong id="EN-US_TOPIC_0125560444__b18875499">Enabled</strong>:</p>
<ul id="EN-US_TOPIC_0125560444__ul61659320"><li id="EN-US_TOPIC_0125560444__li35661763">OBS creates a unique version ID for each uploaded object. Namesake objects are not overwritten and are distinguished by their own version IDs.</li><li id="EN-US_TOPIC_0125560444__li52520413">Objects can be downloaded by version ID. By default, the latest object is downloaded if the version ID is not specified.</li><li id="EN-US_TOPIC_0125560444__li2921675">Objects can be deleted by version ID. If an object is deleted with no version ID specified, the object is only attached with a deletion mark and a unique version ID but is not physically deleted.</li><li id="EN-US_TOPIC_0125560444__li26295076">The latest objects in a bucket are returned by default after a <strong id="EN-US_TOPIC_0125560444__b35329099">GET Object</strong> request. You can also send a request to obtain a bucket's objects with all version IDs.</li><li id="EN-US_TOPIC_0125560444__li49526440">Except deletion marks and object metadata, storage space occupied by objects with all version IDs is billed.</li></ul>
<p class="msonormal" id="EN-US_TOPIC_0125560444__p18062974">After the versioning state is set to <strong id="EN-US_TOPIC_0125560444__b43084780">Suspended</strong>:</p>
<ul id="EN-US_TOPIC_0125560444__ul28349038"><li id="EN-US_TOPIC_0125560444__li52218704">Existing objects with version IDs are not affected.</li><li id="EN-US_TOPIC_0125560444__li206293">OBS creates version ID <strong id="EN-US_TOPIC_0125560444__b1856645">null</strong> to an uploaded object and the object will be overwritten after a namesake one is uploaded.</li><li id="EN-US_TOPIC_0125560444__li16709807">Objects can be downloaded by version ID. By default, the latest object is downloaded if the version ID is not specified.</li><li id="EN-US_TOPIC_0125560444__li16170542">Objects can be deleted by version ID. If an object is deleted with no version ID specified, the object is only attached with a deletion mark and version ID <strong id="EN-US_TOPIC_0125560444__b11317154">null</strong>. Objects with version ID <strong id="EN-US_TOPIC_0125560444__b34745524">null</strong> are physically deleted.</li><li id="EN-US_TOPIC_0125560444__li44274261">Except deletion marks and object metadata, storage space occupied by objects with all version IDs is billed.</li></ul>
<p class="msonormal" id="EN-US_TOPIC_0125560444__p53814755">Only the bucket owner can set the bucket versioning state.</p>
<div class="section" id="EN-US_TOPIC_0125560444__section11440597"><h4 class="sectiontitle">Request Syntax</h4><pre class="screen" id="EN-US_TOPIC_0125560444__screen1290134121014">PUT /?versioning HTTP/1.1 
 User-Agent: agent
 Host: bucketname.obs.example.com
 Accept: */* 
 Date: date 
 Authorization: authorization 
 Content-Length: length 
 Expect: expect

&lt;VersioningConfiguration&gt; 
 &lt;Status&gt;status&lt;/Status&gt; 
&lt;/VersioningConfiguration&gt;</pre>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section35856517"><h4 class="sectiontitle">Request Parameters</h4><p id="EN-US_TOPIC_0125560444__p59271898">This request involves no parameters.</p>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section54273197"><h4 class="sectiontitle">Request Headers</h4><p id="EN-US_TOPIC_0125560444__p36294438">This request uses common headers. For details about common request headers, see section <a href="en-us_topic_0125560462.html">Common Request Headers</a>.</p>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section15363155315813"><h4 class="sectiontitle">Request Elements</h4><p id="EN-US_TOPIC_0125560444__p25561231">This request contains elements to configure the bucket versioning in the XML format. <a href="#EN-US_TOPIC_0125560444__table62924030">Table 1</a> describes the elements.</p>

<div class="tablenoborder"><a name="EN-US_TOPIC_0125560444__table62924030"></a><a name="table62924030"></a><table cellpadding="4" cellspacing="0" summary="" id="EN-US_TOPIC_0125560444__table62924030" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Elements for configuring bucket versioning</caption><thead align="left"><tr id="EN-US_TOPIC_0125560444__row27526859"><th align="left" class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.3.13.3.2.4.1.1"><p id="EN-US_TOPIC_0125560444__p15083110">Element</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.3.13.3.2.4.1.2"><p id="EN-US_TOPIC_0125560444__p13772373">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.3.13.3.2.4.1.3"><p id="EN-US_TOPIC_0125560444__p41820417">Remarks</p>
</th>
</tr>
</thead>
<tbody><tr id="EN-US_TOPIC_0125560444__row32010577"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.13.3.2.4.1.1 "><p id="EN-US_TOPIC_0125560444__p42719917">VersioningConfiguration</p>
</td>
<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.13.3.2.4.1.2 "><p id="EN-US_TOPIC_0125560444__p37761278">Indicates the container for the versioning state configuration.</p>
<p id="EN-US_TOPIC_0125560444__p4307190">Ancestor: None</p>
</td>
<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.13.3.2.4.1.3 "><p id="EN-US_TOPIC_0125560444__p13338129">Mandatory</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0125560444__row52934302"><td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.13.3.2.4.1.1 "><p id="EN-US_TOPIC_0125560444__p59820093">Status</p>
</td>
<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.13.3.2.4.1.2 "><p id="EN-US_TOPIC_0125560444__p13589360">Specifies the versioning state of the bucket.</p>
<p id="EN-US_TOPIC_0125560444__ole_link9">Type: Enumeration</p>
<p id="EN-US_TOPIC_0125560444__p26996384">Ancestor: VersioningConfiguration</p>
<p id="EN-US_TOPIC_0125560444__p41640866">Valid Values: Enabled, Suspended</p>
</td>
<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.13.3.2.4.1.3 "><p id="EN-US_TOPIC_0125560444__p17466967">Mandatory</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section44303172"><h4 class="sectiontitle">Response Syntax</h4><pre class="screen" id="EN-US_TOPIC_0125560444__screen23982562121029">HTTP/1.1 status_code 
 Server: Server Name 
 x-amz-request-id: request id 
 x-amz-id-2: id 
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc 
 Date: date  
 Content-Length: length</pre>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section63184231"><h4 class="sectiontitle">Response Headers</h4><p id="EN-US_TOPIC_0125560444__p11363535">This response uses common headers. For details about common response headers, see section <a href="en-us_topic_0125560484.html">Common Response Headers</a>.</p>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section31787174"><h4 class="sectiontitle">Response elements</h4><p id="EN-US_TOPIC_0125560444__p65314517">This response involves no elements.</p>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section17649112"><h4 class="sectiontitle">Error Responses</h4><p id="EN-US_TOPIC_0125560444__p55984556">No special error responses are returned. For details about error responses, see <a href="en-us_topic_0125560440.html#EN-US_TOPIC_0125560440__table30733758">Table 1</a>.</p>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section5291760"><h4 class="sectiontitle">Sample Request</h4><pre class="screen" id="EN-US_TOPIC_0125560444__screen4672990121047">PUT /?versioning HTTP/1.1 
User-Agent: curl/7.29.0
 Host: bucketname.obs.example.com
 Accept: */*
 Date: Mon, 13 Jan 2014 07:33:22 +0000 
 Authorization: AWS C5780CDE717D50F4CDAA:MxAazqX4BdUfCXpbNd1VpZqyDD4= 
 Content-Length: 80
 Expect: 100-continue 

&lt;VersioningConfiguration&gt; 
 &lt;Status&gt;Enabled&lt;/Status&gt; 
&lt;/VersioningConfiguration&gt;</pre>
</div>
<div class="section" id="EN-US_TOPIC_0125560444__section47625841"><h4 class="sectiontitle">Sample Response</h4><pre class="screen" id="EN-US_TOPIC_0125560444__screen31587236121056">HTTP/1.1 200 OK 
 Server: OBS 
 x-amz-request-id: DCD2FC9CAB78000001438A84E693000F 
 x-amz-id-2: iRQ+xOfSLXxasHqbPqqtDcXRKHXzrz9cNrrW4wjNum2DGHAgr359+tU6QCcwiT0y
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc 
 Date: Mon, 13 Jan 2014 07:33:22 GMT 
 Content-Length: 0</pre>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="en-us_topic_0125560493.html">Operations on Buckets</a></div>
</div>
</div>