diff --git a/doc/common/entities/openstack.ent b/doc/common/entities/openstack.ent index 2c289c5129..88ea72a585 100644 --- a/doc/common/entities/openstack.ent +++ b/doc/common/entities/openstack.ent @@ -9,6 +9,14 @@ + +COPY'> +GET'> +HEAD'> +PUT'> +POST'> +DELETE'> + $ swift post CONTAINER - To list all containers: run the following command: + To list all containers, run the following command: $ swift list @@ -116,10 +116,11 @@ X-Timestamp: 1392684036.33306 $ swift list CONTAINER - To download an object from a container:, run the following - command: + To download an object from a container, run the + following command: $ swift download CONTAINER OBJECT_FILENAME + diff --git a/doc/user-guide/section_object-api-versioning.xml b/doc/user-guide/section_object-api-versioning.xml new file mode 100644 index 0000000000..55e91de8c2 --- /dev/null +++ b/doc/user-guide/section_object-api-versioning.xml @@ -0,0 +1,171 @@ + + +%openstack; +]> +
+ Object versioning + You can store multiple versions of your content so that you + can recover from unintended overwrites. Object versioning is + an easy way to implement version control, which you can use + with any type of content. + + You cannot version a large-object manifest file, but the + large-object manifest file can point to versioned + segments. + + We strongly recommended that you put non-current objects in + a different container than the container where current object + versions reside. + + To enable and use object versioning + + To enable object versioning, ask your cloud provider + to set the option to + TRUE in the container + configuration file. + + + Create an archive container to + store older versions of objects: + # curl -i $publicURL/archive -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + HTTP/1.1 201 Created +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx46f8c29050834d88b8d7e-0052e1859d +Date: Thu, 23 Jan 2014 21:11:57 GMT + + + Create a current container to + store current versions of objects. + Include the X-Versions-Location + header. This header defines the container that holds + the non-current versions of your objects. You must + UTF-8-encode and then URL-encode the container name + before you include it in the + X-Versions-Location header. This + header enables object versioning for all objects in + the current container. Changes to + objects in the current container + automatically create non-current versions in the + archive container. + # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive" + HTTP/1.1 201 Created +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: txb91810fb717347d09eec8-0052e18997 +Date: Thu, 23 Jan 2014 21:28:55 GMT + + + Create the first version of an object in the + current container: + # curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + HTTP/1.1 201 Created +Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT +Content-Length: 0 +Etag: d41d8cd98f00b204e9800998ecf8427e +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a +Date: Thu, 23 Jan 2014 21:31:22 GMT + Nothing is written to the non-current version + container when you initially &PUT; an object in the + current container. However, + subsequent &PUT; requests that edit an object trigger + the creation of a version of that object in the + archive container. + These non-current versions are named as + follows: + <length><object_name><timestamp> + Where length is the 3-character, zero-padded + hexadecimal character length of the object, + <object_name> is the object name, and + <timestamp> is the time when the object was + initially created as a current version. + + + Create a second version of the object in the + current container: + # curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + HTTP/1.1 201 Created +Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT +Content-Length: 0 +Etag: d41d8cd98f00b204e9800998ecf8427e +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c +Date: Thu, 23 Jan 2014 21:41:32 GMT + + + Issue a &GET; request to a versioned object to get + the current version of the object. You do not have to + do any request redirects or metadata lookups. + List older versions of the object in the + archive container: + # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token" + HTTP/1.1 200 OK +Content-Length: 30 +X-Container-Object-Count: 1 +Accept-Ranges: bytes +X-Timestamp: 1390513280.79684 +X-Container-Bytes-Used: 0 +Content-Type: text/plain; charset=utf-8 +X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e +Date: Thu, 23 Jan 2014 21:45:50 GMT + +009my_object/1390512682.92052 + + A &POST; request to a versioned object updates + only the metadata for the object and does not + create a new version of the object. New versions + are created only when the content of the object + changes. + + + + Issue a &DELETE; request to a versioned object to + remove the current version of the object and replace + it with the next-most current version in the + non-current container. + # curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token" + HTTP/1.1 204 No Content +Content-Length: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd +Date: Thu, 23 Jan 2014 21:51:25 GMT + List objects in the archive + container to show that the archived object was moved + back to the current + container: + # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token" + HTTP/1.1 204 No Content +Content-Length: 0 +X-Container-Object-Count: 0 +Accept-Ranges: bytes +X-Timestamp: 1390513280.79684 +X-Container-Bytes-Used: 0 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed +Date: Thu, 23 Jan 2014 21:51:41 GMT + This next-most current version carries with it any + metadata last set on it. If you want to completely + remove an object and you have five versions of it, you + must &DELETE; it five times. + + + To disable object versioning for the + current container, remove its + X-Versions-Location metadata + header by sending an empty key value. + # curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: " + HTTP/1.1 202 Accepted +Content-Length: 76 +Content-Type: text/html; charset=UTF-8 +X-Trans-Id: txe2476de217134549996d0-0052e19038 +Date: Thu, 23 Jan 2014 21:57:12 GMT + +<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html> + + +