531 lines
26 KiB
XML
531 lines
26 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE chapter [
|
||
<!-- Useful for describing APIs -->
|
||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
||
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
||
<!ENTITY HEAD '<command xmlns="http://docbook.org/ns/docbook">HEAD</command>'>
|
||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
||
]>
|
||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||
xml:id="examples">
|
||
<?dbhtml stop-chunking?>
|
||
<title>Object Storage API examples</title>
|
||
<para>This section introduces the cURL command language and
|
||
demonstrates how to use cURL commands to make Object Storage
|
||
API calls.</para>
|
||
<note>
|
||
<para>For more examples, see <link
|
||
xlink:href="http://api.openstack.org/api-ref-objectstorage.html"
|
||
>Object Storage API v1</link>.</para>
|
||
</note>
|
||
<xi:include href="section_object-api-curl-commands.xml"/>
|
||
<section xml:id="auth_examples">
|
||
<title>Authenticate</title>
|
||
<para>The following examples show you how to authenticate with
|
||
the Identity Service or Tempauth.</para>
|
||
<section xml:id="get_auth_token_keystone">
|
||
<title>Authenticate with the Identity Service</title>
|
||
<para>This section provides an overview of the
|
||
authentication process. For request and response
|
||
details, see <link
|
||
xlink:href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/POST_authenticate_v2.0_tokens_.html"
|
||
>Authenticate</link> in the <citetitle>OpenStack
|
||
Identity Service API v2.0
|
||
Reference</citetitle>.</para>
|
||
<procedure>
|
||
<title>To authenticate with the Identity
|
||
Service</title>
|
||
<step>
|
||
<para>Send your credentials and a tenant ID or
|
||
tenant name to the Identity Service.</para>
|
||
<para>The response includes an authentication
|
||
token and service catalog.</para>
|
||
</step>
|
||
<step>
|
||
<para>Select the service catalog entry where
|
||
<literal>type</literal> is
|
||
<literal>object-store</literal>. Use the
|
||
<literal>publicURL</literal> endpoint,
|
||
which contains a URL with the full path to the
|
||
Object Storage account. The URL has the
|
||
format,
|
||
<uri>https://<replaceable>hostname</replaceable>/v1/<replaceable>account</replaceable></uri>.</para>
|
||
</step>
|
||
</procedure>
|
||
</section>
|
||
<section xml:id="get_auth_token_tempauth">
|
||
<title>Authenticate with Tempauth</title>
|
||
<procedure>
|
||
<title>To authenticate with Tempauth</title>
|
||
<step>
|
||
<para>Supply your user name and API access key in
|
||
headers, as follows:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>X-Auth-User</literal>
|
||
header. Specify your Object Storage
|
||
user name.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>X-Auth-Key</literal> header.
|
||
Specify your access key.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>The following example shows a sample
|
||
request:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl -i https://storage.clouddrive.com/v1/auth \
|
||
-H "X-Auth-User: jdoe" -H "X-Auth-Key: jdoepassword"</userinput></screen>
|
||
</step>
|
||
<step>
|
||
<para>When authentication succeeds, you receive a
|
||
<returnvalue>204</returnvalue>
|
||
<errortext>No Content</errortext> status code.
|
||
Any
|
||
<returnvalue>2<replaceable>nn</replaceable></returnvalue>
|
||
response indicates success.</para>
|
||
<para>The <literal>X-Auth-Token</literal> response
|
||
header contains the authentication token. The
|
||
<literal>X-Storage-Url</literal> response
|
||
header contains a URL that includes a full
|
||
path to the Object Storage account. The URL
|
||
has the format,
|
||
<uri>https://<replaceable>hostname</replaceable>/v1/<replaceable>account</replaceable></uri>.</para>
|
||
<para>The following example shows a sample
|
||
response:</para>
|
||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||
Date: Mon, 12 Nov 2010 15:32:21
|
||
Server: Apache
|
||
X-Storage-Url: $publicURL
|
||
X-Auth-Token: $token
|
||
Content-Length: 0
|
||
Content-Type: text/plain; charset=UTF-8</computeroutput></screen>
|
||
</step>
|
||
</procedure>
|
||
</section>
|
||
</section>
|
||
<section xml:id="accounts">
|
||
<title>Account services</title>
|
||
<section xml:id="show-storage-usage">
|
||
<title>Show storage usage</title>
|
||
<para>To show how much data you have stored in the system
|
||
and the number of containers that you are using, send
|
||
a &HEAD; request to the Object Storage service.</para>
|
||
<para>Use the <parameter>-X</parameter> switch to specify
|
||
the &HEAD; method.</para>
|
||
<para>Use the <parameter>-i</parameter> switch to send the
|
||
HTTP response to terminal output.</para>
|
||
<para>Include the authentication token in the
|
||
<literal>X-Auth-Token</literal> header.</para>
|
||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL -X HEAD -H "X-Auth-Token: $token"</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||
Content-Length: 0
|
||
X-Account-Object-Count: 1
|
||
X-Account-Meta-Book: MobyDick
|
||
X-Timestamp: 1389453423.35964
|
||
X-Account-Bytes-Used: 14
|
||
X-Account-Container-Count: 2
|
||
Content-Type: text/plain; charset=utf-8
|
||
Accept-Ranges: bytes
|
||
X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4
|
||
Date: Fri, 17 Jan 2014 16:09:56 GMT</computeroutput></screen>
|
||
<para>The <literal>X-Account-Bytes-Used</literal> response
|
||
header shows the total bytes stored for the entire
|
||
account.</para>
|
||
<para>The <literal>X-Account-Container-Count</literal>
|
||
response header shows the number of containers in this
|
||
storage account.</para>
|
||
</section>
|
||
<section xml:id="list-containers">
|
||
<title>Show account details</title>
|
||
<para>This example shows account details, lists
|
||
containers, and asks for a JSON response:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 200 OK
|
||
Content-Length: 96
|
||
X-Account-Object-Count: 1
|
||
X-Timestamp: 1389453423.35964
|
||
X-Account-Meta-Subject: Literature
|
||
X-Account-Bytes-Used: 14
|
||
X-Account-Container-Count: 2
|
||
Content-Type: application/json; charset=utf-8
|
||
Accept-Ranges: bytes
|
||
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
|
||
Date: Fri, 17 Jan 2014 15:59:33 GMT </computeroutput></screen>
|
||
<programlisting language="json">[
|
||
{
|
||
"count":0,
|
||
"bytes":0,
|
||
"name":"janeausten"
|
||
},
|
||
{
|
||
"count":1,
|
||
"bytes":14,
|
||
"name":"marktwain"
|
||
}
|
||
]</programlisting>
|
||
<para>This example shows account details, lists
|
||
containers, and asks for an XML response:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token"</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 200 OK
|
||
Content-Length: 262
|
||
X-Account-Object-Count: 1
|
||
X-Timestamp: 1389453423.35964
|
||
X-Account-Meta-Subject: Literature
|
||
X-Account-Bytes-Used: 14
|
||
X-Account-Container-Count: 2
|
||
Content-Type: application/xml; charset=utf-8
|
||
Accept-Ranges: bytes
|
||
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
|
||
Date: Fri, 17 Jan 2014 16:03:23 GMT </computeroutput></screen>
|
||
<programlisting language="xml"><xi:include parse="text" href="samples/container-get-details-resp.xml"/></programlisting>
|
||
</section>
|
||
</section>
|
||
<section xml:id="containers">
|
||
<title>Container services</title>
|
||
<section xml:id="acls">
|
||
<title>Container ACLs</title>
|
||
<para>The <literal>X-Container-Read</literal> metadata
|
||
header defines the access control list (ACL)
|
||
permissions for who can read objects in a container.
|
||
Before you set this header, only users with a valid
|
||
authentication token for the account can read objects
|
||
in that container.</para>
|
||
<para>List containers to show the absence of the
|
||
<literal>X-Container-Read</literal> header:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/jerry</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||
X-Container-Object-Count: 0
|
||
X-Container-Bytes-Used: 0
|
||
Accept-Ranges: bytes
|
||
X-Trans-Id: tx3aa52e951fc64b63bc1fda27902b9bd3
|
||
Content-Length: 0
|
||
Date: Tue, 15 Nov 2011 03:29:22 GMT</computeroutput></screen>
|
||
<para>Set the <literal>X-Container-Read</literal> header
|
||
to enable read and list access to everyone:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i \
|
||
-H "X-Auth-Token: $token" \
|
||
-H "X-Container-Read: .r:*,.rlistings" \
|
||
$publicURL/jerry</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 202 Accepted
|
||
Content-Length: 58
|
||
Content-Type: text/html; charset=UTF-8
|
||
X-Trans-Id: txf2befb56b1854a50995f710f2db48089
|
||
Date: Tue, 15 Nov 2011 03:33:16 GMT
|
||
|
||
202 Accepted
|
||
|
||
The request is accepted for processing.</computeroutput></screen>
|
||
<para>For a list of valid
|
||
<literal>X-Container-Read</literal> header values,
|
||
see <link
|
||
xlink:href="http://swift.openstack.org/misc.html#acls"
|
||
> ACLs</link>.</para>
|
||
<para>To see the metadata change:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/jerry</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||
X-Container-Object-Count: 0
|
||
X-Container-Read: .r:*,.rlistings
|
||
X-Container-Bytes-Used: 0
|
||
Accept-Ranges: bytes
|
||
X-Trans-Id: txb40eb86d949345f7bc66b01e8b63c3a5
|
||
Content-Length: 0
|
||
Date: Tue, 15 Nov 2011 03:33:36 GMT</computeroutput></screen>
|
||
<para>After you give everyone read access, anyone can
|
||
access any object in the container from a browser. To
|
||
do so, a user appends the object name to the
|
||
<literal>X-Storage-URL</literal> header value used
|
||
in the session. For example:</para>
|
||
<screen><userinput>$publicURL/jerry/cereal.jpg</userinput></screen>
|
||
</section>
|
||
<section xml:id="create_containers">
|
||
<title>Create a container</title>
|
||
<para>To create a container, issue a &PUT; request. You do
|
||
not need to check if a container already exists before
|
||
you issue a &PUT; request. The operation creates a
|
||
container or updates an existing container, as
|
||
appropriate.</para>
|
||
<para>Example requests and responses:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Create a container with no metadata:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 201 Created
|
||
Content-Length: 0
|
||
Content-Type: text/html; charset=UTF-8
|
||
X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
|
||
Date: Tue, 14 Jan 2014 19:09:10 GMT</computeroutput></screen>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Create a container with metadata:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer"</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 201 Created
|
||
Content-Length: 0
|
||
Content-Type: text/html; charset=UTF-8
|
||
X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
|
||
Date: Tue, 14 Jan 2014 19:25:43 GMT</computeroutput></screen>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>For a complete description of HTTP 1.1 header
|
||
definitions, see <link
|
||
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14"
|
||
>Header Field Definitions</link>.</para>
|
||
</section>
|
||
<section xml:id="large_list_containers_example">
|
||
<title>Page through large lists of containers</title>
|
||
<note>
|
||
<para>You can also use this technique to page through
|
||
large lists of objects.</para>
|
||
</note>
|
||
<para>For more information about how to page through large
|
||
lists of containers and objects, see <xref
|
||
linkend="large-lists"/>.</para>
|
||
<para>For a list of five container names, if you specify a
|
||
<parameter>limit</parameter> of two, two items are
|
||
returned. You can assume there are more names to list,
|
||
so make another request with a
|
||
<parameter>marker</parameter> of the last item
|
||
returned.</para>
|
||
<para>For example, assume the following list of container
|
||
names:</para>
|
||
<literallayout class="monospaced">apples
|
||
bananas
|
||
kiwis
|
||
oranges
|
||
pears</literallayout>
|
||
<procedure>
|
||
<title>To page through a large list of
|
||
containers</title>
|
||
<step>
|
||
<para>Use a <parameter>limit</parameter> of
|
||
two:</para>
|
||
<screen><userinput>GET $publicURL?limit=2
|
||
Host: storage.swiftdrive.com
|
||
X-Auth-Token: $token</userinput></screen>
|
||
<screen><computeroutput>apples
|
||
bananas</computeroutput></screen>
|
||
<para>Because two container names are returned,
|
||
there are more names to list.</para>
|
||
</step>
|
||
<step>
|
||
<para>Make another request with a
|
||
<parameter>marker</parameter> parameter
|
||
set to the name of the last item
|
||
returned:</para>
|
||
<screen><userinput>GET $publicURL?limit=2&marker=bananas
|
||
Host: storage.swiftdrive.com
|
||
X-Auth-Token: $token</userinput></screen>
|
||
<screen><computeroutput>kiwis
|
||
oranges</computeroutput></screen>
|
||
<para>Again, two items are returned, and there
|
||
might be more.</para>
|
||
</step>
|
||
<step>
|
||
<para>Make another request with a
|
||
<parameter>marker</parameter> of the last
|
||
item returned:</para>
|
||
<screen><userinput>GET $publicURL?limit=2&marker=oranges
|
||
Host: storage.swiftdrive.com
|
||
X-Auth-Token: $token</userinput></screen>
|
||
|
||
<screen><computeroutput>pears</computeroutput></screen>
|
||
<para>You now receive a one-item response, which
|
||
is fewer than the <parameter>limit</parameter>
|
||
number of names. This indicates that this is
|
||
the end of the list.</para>
|
||
</step>
|
||
<step>
|
||
<para>Use the <parameter>end_marker</parameter>
|
||
parameter to limit the result set to object
|
||
names that are less than the
|
||
<parameter>end_marker</parameter>
|
||
parameter value:</para>
|
||
<screen><userinput>GET $publicURL/?end_marker=oranges
|
||
Host: storage.swiftdrive.com
|
||
X-Auth-Token: $token</userinput></screen>
|
||
<screen><computeroutput>apples
|
||
bananas
|
||
kiwis</computeroutput></screen>
|
||
</step>
|
||
</procedure>
|
||
</section>
|
||
<section xml:id="retrieve-copy-retrieve-objects">
|
||
<title>Get, copy, and delete objects</title>
|
||
<para>Now, retrieve an object that you previously
|
||
uploaded. First, remove the local copy:</para>
|
||
<screen><prompt>#</prompt> <userinput>ls -l</userinput></screen>
|
||
<screen><computeroutput>total 504
|
||
-rw-r--r--@ 1 petecj2 staff 44765 Nov 7 14:49 JingleRocky.jpg
|
||
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
|
||
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput></screen>
|
||
<screen><prompt>#</prompt> <interfacename>rm JingleRocky.jpg</interfacename>
|
||
<prompt>#</prompt> <userinput>ls -l</userinput></screen>
|
||
<screen><computeroutput>total 416
|
||
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
|
||
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput> </screen>
|
||
<para>Be sure not to use -i switch here because you want
|
||
the raw data, which you pipe to a file:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X GET -H "X-Auth-Token: $token" $publicURL/dogs/JingleRocky.jpg > JingleRocky.jpg</userinput></screen>
|
||
<screen><prompt>#</prompt> <userinput>ls -l</userinput></screen>
|
||
<screen><computeroutput>total 504
|
||
-rw-r--r-- 1 petecj2 staff 44765 Nov 7 15:11 JingleRocky.jpg
|
||
-rw-r--r--@ 1 petecj2 staff 100864 Nov 7 14:47 RockyAndBuster.jpg
|
||
-rw-r--r--@ 1 petecj2 staff 107103 Nov 7 14:47 SittingBuster.jpg</computeroutput></screen>
|
||
<para>Next, Object Storage provides a facility to copy
|
||
objects from one container to another entirely on the
|
||
server side. To do this, you do a &PUT; with the
|
||
destination container and new object name while
|
||
passing a special X-Copy-From header and a
|
||
Content-Length of zero:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X PUT -i -H "X-Auth-Token: $token" -H "X-Copy-From: /dogs/JingleRocky.jpg" -H "Content-Length: 0" $publicURL/elaine/JingleRocky.jpg</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 201 Created
|
||
Content-Length: 118
|
||
Content-Type: text/html; charset=UTF-8
|
||
Etag: f7d40eceffdd9c2ecab226105737b2a6
|
||
X-Copied-From: dogs/JingleRocky.jpg
|
||
Last-Modified: Mon, 07 Nov 2011 23:23:53 GMT
|
||
X-Trans-Id: tx244cd14df1b94d8c91ec5dcf8c5f9da4
|
||
Date: Mon, 07 Nov 2011 23:23:54 GMT
|
||
|
||
<html><head><title>201 Created</title></head><body><h1>201 Created</h1><br /><br /></body></html></computeroutput></screen>
|
||
<para>You can then confirm the new location of the object.
|
||
Issue a &GET; request with the destination
|
||
container:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/elaine/</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 200 OK
|
||
X-Container-Object-Count: 1
|
||
X-Container-Bytes-Used: 44765
|
||
Accept-Ranges: bytes
|
||
Content-Length: 16
|
||
Content-Type: text/plain; charset=utf-8
|
||
X-Trans-Id: tx46986b4a09b34790924fd43842b2b0dd
|
||
Date: Mon, 07 Nov 2011 23:24:05 GMT
|
||
|
||
JingleRocky.jpg</computeroutput></screen>
|
||
<para>To delete an object from its container:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X DELETE -i -H "X-Auth-Token: $token" $publicURL/elaine/JingleRocky.jpg</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||
Content-Length: 0
|
||
Content-Type: text/html; charset=UTF-8
|
||
X-Trans-Id: txd45f04422b034e6f8447de400b78cbf3
|
||
Date: Mon, 07 Nov 2011 23:32:39 GMT</computeroutput></screen>
|
||
<para>List containers to confirm the deletion:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X GET -i -H "X-Auth-Token: $token" $publicURL/elaine/</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||
X-Container-Object-Count: 0
|
||
X-Container-Bytes-Used: 0
|
||
Accept-Ranges: bytes
|
||
X-Trans-Id: txc9b43bf4d896405eb9a88ca468bf7b2d
|
||
Content-Length: 0
|
||
Date: Mon, 07 Nov 2011 23:32:41 GMT</computeroutput></screen>
|
||
</section>
|
||
<section xml:id="container-metadata-and-delete-containers">
|
||
<title>Get container metadata and delete
|
||
containers</title>
|
||
<para>You can get at container metadata directly simply by
|
||
appending the name of the container to a HEAD
|
||
request:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X HEAD -i \
|
||
-H "X-Auth-Token: $token" \
|
||
$publicURL/dogs</userinput>
|
||
<computeroutput>HTTP/1.1 204 No Content
|
||
X-Container-Object-Count: 0
|
||
X-Container-Bytes-Used: 0
|
||
Accept-Ranges: bytes
|
||
X-Trans-Id: tx3dd984f9482341dd97546e9d49d65e90
|
||
Content-Length: 0
|
||
Date: Mon, 07 Nov 2011 20:39:41 GMT</computeroutput></screen>
|
||
<para>To delete a container:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X DELETE -i \
|
||
-H "X-Auth-Token: $token" \
|
||
$publicURL/george</userinput>
|
||
<computeroutput>HTTP/1.1 204 No Content
|
||
Content-Length: 0
|
||
Content-Type: text/html; charset=UTF-8
|
||
X-Trans-Id: tx3fa3857f266f44319d9b8f4bf7ce7fc8
|
||
Date: Mon, 07 Nov 2011 20:42:58 GMT</computeroutput></screen>
|
||
<para>Then let's confirm the delete by listing the
|
||
containers again:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X GET -i \
|
||
-H "X-Auth-Token: $token" \
|
||
$publicURL</userinput>
|
||
<computeroutput>HTTP/1.1 200 OK
|
||
X-Account-Object-Count: 0
|
||
X-Account-Bytes-Used: 0
|
||
X-Account-Container-Count: 4
|
||
Accept-Ranges: bytes
|
||
Content-Length: 24
|
||
Content-Type: text/plain; charset=utf-8
|
||
X-Trans-Id: tx2475741852b849ce9403e382fe3f8015
|
||
Date: Mon, 07 Nov 2011 20:43:08 GMT
|
||
|
||
cosmo
|
||
dogs
|
||
elaine
|
||
jerry</computeroutput></screen>
|
||
</section>
|
||
</section>
|
||
<section xml:id="objects">
|
||
<title>Object services</title>
|
||
<section xml:id="static-large-objects-example">
|
||
<title>Create static large objects</title>
|
||
<para>To create a static large object:</para>
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>Split the content into pieces.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Upload each piece into a segment
|
||
object.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Create a manifest object.</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
<para>This example places the segment objects into the
|
||
<literal>segments</literal> container and the
|
||
manifest object into the <literal>images</literal>
|
||
container. Using a dedicated container for segment
|
||
objects is convenient.</para>
|
||
<para>Assuming you have already split the image into three
|
||
files, you can upload them. You have removed
|
||
non-essential response headers so you can see the
|
||
important details.</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece1 $publicURL/segments/terrier-jpg-one</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 201 Created
|
||
Content-Length: 4000000
|
||
Etag: f7365c1419b4f349592c00bd0cfb9b9a</computeroutput></screen>
|
||
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece2 $publicURL/segments/terrier-jpg-two</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 201 Created
|
||
Content-Length: 2000000
|
||
Etag: ad81e97b10e870613aecb5ced52adbaa</computeroutput></screen>
|
||
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./piece3 $publicURL/segments/terrier-jpg-three</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 201 Created
|
||
Content-Length: 1000
|
||
Etag: 00b046c9d74c3e8f93b320c5e5fdc2c3</computeroutput></screen>
|
||
<para>At this stage, you can create the manifest listing.
|
||
Notice that the size and ETag are copied from the
|
||
previous uploads. Create a file called
|
||
<filename>manifest.json</filename> with the
|
||
following content:</para>
|
||
<programlisting language="json"><xi:include parse="text" href="samples/manifest.json"/></programlisting>
|
||
<para>The final operation is to upload this content into a
|
||
manifest object. To indicate that this is a manifest
|
||
object, you must specify the
|
||
<parameter>multipart-manifest=put</parameter>
|
||
query parameter.</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X &PUT; -i -H "X-Auth-Token: $token" -T ./manifest.json $publicURL/images/terrier-jpg?multipart-manifest=put</userinput></screen>
|
||
<para>Examine the static large object. Notice that its
|
||
size is the total size of all the segments:</para>
|
||
<screen><prompt>#</prompt> <userinput>curl –X HEAD -i -H "X-Auth-Token: $token" $publicURL/images/terrier-jpg</userinput></screen>
|
||
<screen><computeroutput>HTTP/1.1 200 OK
|
||
Content-Length: 6001000
|
||
Etag: "0c922c37f915efb1c9b97e6328b3e660"</computeroutput></screen>
|
||
</section>
|
||
</section>
|
||
</chapter>
|