Update Object Storage API Reference
Point to WADL files that generate the API Reference
page so that the method descriptions and request
and response parameters are consistent between
these two docs:
http://api.openstack.org/api-ref-objectstorage.html
(API Reference page for Object Storage)
http://docs.openstack.org/api/openstack-object-storage/1.0/
(API Reference (or spec) for Object Storage)
Add descriptions of ACLs, FormPOST, TempURLs,
StaticWeb, Bulk Upload, Bulk Delete, the OPTIONS operation
(though this is implicit in CORS support)
Validate all code examples
Remove duplication.
Co-Author: Donagh McCabe
Closes-Bug: #1187119
Closes-Bug: #1214139
Closes-Bug: #1074198
Partial-Bug: #1255770
Change-Id: I94054b046a94260ba8825bdb42439adfcaf9fdce
author: diane fleming
This commit is contained in:
Diane Fleming
parent
b98907be31
commit
ed4f3c4db9
15
.gitignore
vendored
15
.gitignore
vendored
@ -1,16 +1,23 @@
|
||||
.DS_Store?
|
||||
.DS_Store
|
||||
*.xpr
|
||||
.idea
|
||||
|
||||
# Build results
|
||||
target/
|
||||
publish-docs/
|
||||
|
||||
# NetBeans user-specific build actions
|
||||
nbactions.xml
|
||||
# Ignore Vagrant Related Files
|
||||
acceptance_config.yml
|
||||
boxes/*
|
||||
/.vagrant
|
||||
|
||||
# Testenvironment
|
||||
.tox
|
||||
.tox/
|
||||
|
||||
# Editors
|
||||
*~
|
||||
.*.swp
|
||||
.bak
|
||||
|
||||
# NetBeans user-specific build actions
|
||||
nbactions.xml
|
||||
|
||||
@ -1,30 +1,6 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||||
]>
|
||||
<book xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
@ -67,13 +43,24 @@
|
||||
Application Programming Interface (API) v1.</para>
|
||||
</abstract>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<date>2014-02-03</date>
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Rewrote introduction and validated all code
|
||||
examples.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
</revision>
|
||||
<revision>
|
||||
<date>2014-01-24</date>
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Added information about form &POST; and
|
||||
temporary URL middleware.</para>
|
||||
<para>Added information about form &POST; and temporary
|
||||
URL middleware.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
@ -159,7 +146,7 @@
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Fixed bugs 890435 and 907563 - Add/Update
|
||||
<para>Fixed bugs 890435 and 907563; Add/Update
|
||||
Container Metadata and Expiring Objects. Changed to
|
||||
Maven 1.0.10.</para>
|
||||
</listitem>
|
||||
@ -196,9 +183,9 @@
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Removed references to ACL (Access Control List).
|
||||
Fixed error in examples referring to X-Auth-Key where
|
||||
it should be X-Auth-Token. Added section
|
||||
<para>Removed references to Access Control List (ACL).
|
||||
Fixed error in examples referring to <literal>X-Auth-Key</literal> where
|
||||
it should be <literal>X-Auth-Token</literal>. Added section
|
||||
numbers.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
@ -210,7 +197,7 @@
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Expanded authentication information for UK
|
||||
release. Added "delimiter" as a Query Parameter and
|
||||
release. Added <literal>delimiter</literal> as a query parameter and
|
||||
server-side object copy example.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
@ -221,7 +208,7 @@
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Initial Release.</para>
|
||||
<para>Initial release.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
@ -230,7 +217,7 @@
|
||||
</info>
|
||||
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
|
||||
<xi:include href="preface.xml"/>
|
||||
<xi:include href="ch_object-api-general.xml"/>
|
||||
<xi:include href="ch_object-api-storage-services.xml"/>
|
||||
<xi:include href="ch_object-api-troubleshooting-examples.xml"/>
|
||||
<xi:include href="ch_object-api-concepts-and-features.xml"/>
|
||||
<xi:include href="ch_object-api-operations.xml"/>
|
||||
<xi:include href="ch_object-api-examples.xml"/>
|
||||
</book>
|
||||
|
||||
@ -0,0 +1,27 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<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="ch_object-storage-dev-general-api">
|
||||
<title>Object Storage API concepts and features</title>
|
||||
<xi:include href="section_object-api-overview.xml"/>
|
||||
<xi:include href="section_object-api-env-vars.xml"/>
|
||||
<xi:include href="section_object-api-discoverability.xml"/>
|
||||
<xi:include href="section_object-api-authentication.xml"/>
|
||||
<xi:include href="section_object-api-response-formats.xml"/>
|
||||
<xi:include href="section_object-api-versioning.xml"/>
|
||||
<xi:include href="section_object-api-create-large-objects.xml"/>
|
||||
<xi:include href="section_object-api-cors-headers.xml"/>
|
||||
<xi:include href="section_object-api-compress-files.xml"/>
|
||||
<xi:include href="section_object-api-browser-bypass.xml"/>
|
||||
<xi:include href="section_object-api-expire-objects.xml"/>
|
||||
<xi:include href="section_object-api-pseudo-hier-folders.xml"/>
|
||||
<xi:include href="section_object-api-large-lists.xml"/>
|
||||
<xi:include href="section_object-api-archive-auto-extract.xml"/>
|
||||
<xi:include href="section_object-api-bulk-delete.xml"/>
|
||||
<xi:include href="section_object-api-container-sync.xml"/>
|
||||
<xi:include href="section_object-api-container-quotas.xml"/>
|
||||
<xi:include href="section_object-api-tempurl.xml"/>
|
||||
<xi:include href="section_object-api-formpost.xml"/>
|
||||
<xi:include href="section_object-api-create-website.xml"/>
|
||||
</chapter>
|
||||
530
openstack-object-storage-dev/ch_object-api-examples.xml
Normal file
530
openstack-object-storage-dev/ch_object-api-examples.xml
Normal file
@ -0,0 +1,530 @@
|
||||
<?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>
|
||||
@ -1,192 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE chapter [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<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="ch_object-storage-dev-general-api">
|
||||
<title>General API Information</title>
|
||||
<section xml:id="authentication-object-dev-guide">
|
||||
<title>Authentication</title>
|
||||
<para>Client authentication is provided via a ReST interface
|
||||
using the &GET; method, with <code>v1.0</code> supplied as
|
||||
the path. Additionally, two headers are required,
|
||||
<code>X-Auth-User</code> and <code>X-Auth-Key</code>
|
||||
with values for the username and API Access Key
|
||||
respectively.</para>
|
||||
<para>Each ReST request against the OpenStack Object Storage
|
||||
system requires the inclusion of a specific authorization
|
||||
token HTTP x-header, defined as <code>X-Auth-Token</code>.
|
||||
Clients obtain this token, along with the Cloud Servers
|
||||
API URL, by first using an authentication service and
|
||||
supplying a valid username and API access key.</para>
|
||||
<simplesect>
|
||||
<title>Request</title>
|
||||
<para>To authenticate, you must supply your username and
|
||||
API access key in x-headers:</para>
|
||||
<para>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Use your OpenStack Object Storage
|
||||
(Swift) username as the username for the
|
||||
API. Place it in the
|
||||
<code>X-Auth-User</code> x-header.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Get your API access key from
|
||||
authentication service you chose when
|
||||
installing. You have some options for
|
||||
auth, including tempauth (which is
|
||||
included with Swift), swauth (an auth
|
||||
service for Swift as WSGI middleware that
|
||||
uses Swift itself as a backing store that
|
||||
is provided via download from Github), the
|
||||
OpenStack Identity Service (project named
|
||||
Keystone), or you can use your own
|
||||
authentication system. Place your access
|
||||
key in the <code>X-Auth-Key</code>
|
||||
x-header.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para> </para>
|
||||
<example>
|
||||
<title>Authentication HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/auth-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</simplesect>
|
||||
<simplesect>
|
||||
<title>Response</title>
|
||||
<para>When authentication is successful, an HTTP status
|
||||
204 (No Content) is returned with the
|
||||
<code>X-Storage-Url</code> and
|
||||
<code>X-Auth-Token</code> headers. Any 2xx
|
||||
response is a good response. For example, a 202
|
||||
response means the request has been accepted. Also,
|
||||
additional <code>X-</code> headers may be returned.
|
||||
These additional headers are related to other
|
||||
Rackspace services and can be ignored. An HTTP status
|
||||
of 401 (Unauthorized) is returned upon authentication
|
||||
failure. All subsequent container/object operations
|
||||
against OpenStack Object Storage should be made
|
||||
against the URI specified in
|
||||
<code>X-Storage-Url</code> and must include the
|
||||
<code>X-Auth-Token</code> header.</para>
|
||||
<example>
|
||||
<title>Authentication HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/auth-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>The <code>X-Storage-Url</code> will need to be
|
||||
parsed and used in the connection and request line of
|
||||
all subsequent requests against Object Storage. In the
|
||||
example response above, users connecting to OpenStack
|
||||
Object Storage would send most container/object
|
||||
requests with a host header of
|
||||
<code>storage.swiftdrive.com</code> and the
|
||||
request line's version and account as
|
||||
<code>/v1/CF_xer7_34</code>. Note that
|
||||
authentication tokens are valid for a 24 hour period
|
||||
for many authentication configurations.</para>
|
||||
</simplesect>
|
||||
</section>
|
||||
|
||||
<section xml:id="overview-object-api">
|
||||
<title>Overview of API Operations</title>
|
||||
<para>The OpenStack Object Storage API is implemented as a set
|
||||
of ReSTful (Representational State Transfer) web services.
|
||||
All authentication and container/object operations can be
|
||||
performed with standard HTTP calls. See the <link
|
||||
xlink:href="http://en.wikipedia.org/wiki/Representational_State_Transfer"
|
||||
>Representational State Transfer</link> on ReST for
|
||||
more information</para>
|
||||
<para>The following constraints apply to the ReST API's HTTP
|
||||
requests:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Maximum number of HTTP headers per request:
|
||||
90</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Maximum length of all HTTP headers: 4096
|
||||
bytes</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Maximum length per HTTP request line: 8192
|
||||
bytes</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Maximum length of HTTP request: 5
|
||||
gigabytes</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Maximum length of container name: 256
|
||||
bytes</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Maximum length of object name: 1024 bytes</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>Container and object names must be UTF-8 encoded and then should be properly
|
||||
URL-encoded prior to interacting with the ReST interface. You may be using an API
|
||||
binding that performs the URL-encoding on your behalf. If so, do not URL-encode before
|
||||
calling the API binding otherwise you will double-encode container and object names. The
|
||||
length restrictions should be checked against the URL-encoded string.</para>
|
||||
<para>Each ReST request against the OpenStack Object Storage
|
||||
system requires the inclusion of a specific
|
||||
<firstterm>authorization token</firstterm> HTTP header
|
||||
defined as <code>X-Auth-Token</code>. Clients obtain this
|
||||
token, along with the OpenStack Object Storage URLs, by
|
||||
first using the Authentication service and supplying a
|
||||
valid Username and API Access Key.</para>
|
||||
<para><!--There are actually two different sets of ReST services that make up the full OpenStack Object Storage product. -->
|
||||
The ReST service identified with
|
||||
<code>X-Storage-Url</code> is used for managing the
|
||||
data stored in the system. Example operations are creating
|
||||
containers and uploading objects.
|
||||
<!--The second ReST service is for managing the CDN feature of OpenStack Object Storage and is identified by <code>X-CDN-Management-Url</code>.--></para>
|
||||
<para>In the following sections, the purpose of each HTTP
|
||||
method depends upon which service the call is made
|
||||
against. For example, a &PUT; request against
|
||||
<code>X-Storage-Url</code> can be used to create a
|
||||
container or upload an
|
||||
object.<!--, while a &PUT; request against the <code>X-CDN-Management-Url</code> is used to CDN-enable a container--></para>
|
||||
<para>The language-specific APIs mask this system separation
|
||||
from the programmer. They simply create a container and
|
||||
mark it <emphasis>public</emphasis> and it handles calling
|
||||
out to the appropriate back-end services using the
|
||||
appropriate ReST API.</para>
|
||||
<note>
|
||||
<para>All requests to authenticate and operate against
|
||||
OpenStack Object Storage are performed using SSL over
|
||||
HTTP (HTTPS) on TCP port 443.</para>
|
||||
</note>
|
||||
</section>
|
||||
<xi:include href="section_object_api_tempurl.xml"/>
|
||||
<xi:include href="section_object_api_formpost.xml"/>
|
||||
</chapter>
|
||||
59
openstack-object-storage-dev/ch_object-api-operations.xml
Normal file
59
openstack-object-storage-dev/ch_object-api-operations.xml
Normal file
@ -0,0 +1,59 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<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="api-operations" role="api-reference">
|
||||
<title>Object Storage API operations</title>
|
||||
<para>Manage the accounts, containers, and objects in the Object
|
||||
Storage system.</para>
|
||||
<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 xml:id="storage_account_services">
|
||||
<title>Accounts</title>
|
||||
<para>List containers for a specified account. Create, update,
|
||||
and delete account metadata. Show account metadata.</para>
|
||||
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
||||
<wadl:resource
|
||||
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#account">
|
||||
<wadl:method href="#showAccountDetails"/>
|
||||
<wadl:method href="#updateAccountMeta"/>
|
||||
<wadl:method href="#showAccountMeta"/>
|
||||
</wadl:resource>
|
||||
</wadl:resources>
|
||||
</section>
|
||||
<section xml:id="storage_container_services">
|
||||
<title>Containers</title>
|
||||
<para>List objects in a specified container. Create, show
|
||||
details for, and delete containers. Create, update, show,
|
||||
and delete container metadata.</para>
|
||||
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
||||
<wadl:resource
|
||||
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#container">
|
||||
<wadl:method href="#showContainerDetails"/>
|
||||
<wadl:method href="#createContainer"/>
|
||||
<wadl:method href="#deleteContainer"/>
|
||||
<wadl:method href="#updateContainerMeta"/>
|
||||
<wadl:method href="#showContainerMeta"/>
|
||||
</wadl:resource>
|
||||
</wadl:resources>
|
||||
</section>
|
||||
<section xml:id="storage_object_services">
|
||||
<title>Objects</title>
|
||||
<para>Create, replace, show details for, and delete objects.
|
||||
Copy objects with another object with a new or different name.
|
||||
Update object metadata.</para>
|
||||
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
||||
<wadl:resource
|
||||
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#object">
|
||||
<wadl:method href="#getObject"/>
|
||||
<wadl:method href="#createOrReplaceObject"/>
|
||||
<wadl:method href="#copyObject"/>
|
||||
<wadl:method href="#deleteObject"/>
|
||||
<wadl:method href="#showObjectMeta"/>
|
||||
<wadl:method href="#updateObjectMeta"/>
|
||||
</wadl:resource>
|
||||
</wadl:resources>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,82 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<!DOCTYPE chapter [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<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="ch_object-storage-dev-api-storage">
|
||||
<title>API Operations for Storage Services</title>
|
||||
<para>Use the ReST API to interact with the storage component of
|
||||
OpenStack Object Storage. All requests are directed to the host
|
||||
and URL described in the <code>X-Storage-Url</code> HTTP header
|
||||
obtained during successful authentication.</para>
|
||||
<para>Review the following requirements for using storage
|
||||
services:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Container names cannot exceed 256 bytes and cannot contain
|
||||
the <literal>/</literal> character.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Object names cannot exceed 1024 bytes, and have no
|
||||
character restrictions.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Object and container names must be UTF-8 encoded and then
|
||||
URL-encoded to interact with the ReST API.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para><!--<info>Added paragraph to forecast info structure -\- dsh -2012-03-09 </info>-->The
|
||||
following sections describe the actions that you can perform in
|
||||
the storage system.</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="storage-account-services"/>. Actions that
|
||||
you can perform at the account level of the storage system.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="storage-container-services"/>. Actions that
|
||||
you can perform on containers.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="Create_Static_Website-dle4000"/>. How to
|
||||
use your swift account to create a static website.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="storage-object-services"/>. Actions that
|
||||
you can perform on objects.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<xi:include href="section_object-api-storage_account_svc.xml"/>
|
||||
<xi:include href="section_object-api-storage-container-svc.xml"/>
|
||||
<xi:include href="section_object-api-create-website.xml"/>
|
||||
<xi:include href="section_object-api-storage-object-svc.xml"/>
|
||||
</chapter>
|
||||
@ -1,993 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<!DOCTYPE chapter [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<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="ch_object-storage-dev-troubleshooting">
|
||||
<title>Troubleshooting and Examples</title>
|
||||
<para>This section introduces a command-line utility, cURL, and
|
||||
demonstrates interacting with the ReST interfaces through that
|
||||
utility.</para>
|
||||
<section xml:id="using-curl-cli">
|
||||
<title>Using cURL</title>
|
||||
<para>cURL is a command-line tool which is available on most
|
||||
UNIX®-like environments and Mac OS X® and can be
|
||||
downloaded for Windows®. For more information on cURL,
|
||||
visit <link xlink:href="http://curl.haxx.se/"
|
||||
>http://curl.haxx.se/</link>.</para>
|
||||
<para>cURL allows you to transmit and receive HTTP requests
|
||||
and responses from the command-line or from within a shell
|
||||
script. This makes it possible to work with the ReST API
|
||||
directly without using one of the client APIs.</para>
|
||||
<para>The following cURL command-line options will be
|
||||
used</para>
|
||||
<variablelist>
|
||||
<title>cURL Command-Line Options</title>
|
||||
<varlistentry>
|
||||
<term><option>-X METHOD</option></term>
|
||||
<listitem>
|
||||
<para>Specify the HTTP method to request (&HEAD;,
|
||||
&GET;, etc.)</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-i</option></term>
|
||||
<listitem>
|
||||
<para>Dump HTTP response headers to stdout.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>-H HEADER</option></term>
|
||||
<listitem>
|
||||
<para>Specify an HTTP header in the
|
||||
request.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</section>
|
||||
<section xml:id="authentication-examples-curl">
|
||||
<title>Authentication</title>
|
||||
<para>To use the ReST API, you must obtain a authorization
|
||||
token, which you pass to each request in the
|
||||
<code>X-Auth-Token</code> header. The following
|
||||
example demonstrates how to use cURL to obtain the
|
||||
authorization token and the URL of the storage
|
||||
system.</para>
|
||||
<example>
|
||||
<title>cURL Authenticate</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>-i</option> \
|
||||
<option>-H "X-Auth-Key: jdoesecretpassword"</option> \
|
||||
<option>-H "X-Auth-User: jdoe"</option> \
|
||||
<uri>https://auth.api.yourcloud.com/v1.0</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||||
Date: Thu, 09 Jul 2009 15:31:39 GMT
|
||||
Server: Apache/2.2.3
|
||||
X-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_343
|
||||
X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae
|
||||
Content-Length: 0
|
||||
Connection: close
|
||||
Content-Type: application/octet-stream</computeroutput></screen>
|
||||
</example>
|
||||
<para>The storage URL and authentication token are returned in
|
||||
the headers of the response. After authentication, you can
|
||||
use cURL to perform &HEAD;, &GET;, &DELETE;, &POST; and
|
||||
&PUT; requests on the storage service.</para>
|
||||
</section>
|
||||
<section xml:id="determining-storage-useage">
|
||||
<title>Determining Storage Usage</title>
|
||||
<para>A &HEAD; request can be sent to the storage service to
|
||||
determine how much data you have stored in the system and
|
||||
the number of containers you are using. Use the
|
||||
<code>-X</code> switch to specify the correct HTTP
|
||||
method and the <code>-i</code> to dump the HTTP response
|
||||
headers to terminal output (stdout).</para>
|
||||
<example>
|
||||
<title>cURL Get Storage Space</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||||
Date: Thu, 09 Jul 2009 15:38:14 GMT
|
||||
Server: Apache
|
||||
X-Account-Container-Count: 22
|
||||
X-Account-Bytes-Used: 9891628380
|
||||
Content-Type: text/plain</computeroutput></screen>
|
||||
</example>
|
||||
<para>The HTTP request must include a header to specify the
|
||||
authentication token. The HTTP headers in the response
|
||||
indicate the number of containers in this storage account
|
||||
and the total bytes stored for the entire account.</para>
|
||||
</section>
|
||||
<section xml:id="listing-and-creating-storage-containers">
|
||||
<title>Listing and Creating Containers</title>
|
||||
<para>The simplest operation for Object Storage is to simply
|
||||
list the containers you have, which when you don't have
|
||||
any containers yet isn't terribly exciting:</para>
|
||||
<example>
|
||||
<title>cURL List Storage Container</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 204 No Content
|
||||
X-Account-Object-Count: 0
|
||||
X-Account-Bytes-Used: 0
|
||||
X-Account-Container-Count: 0
|
||||
Accept-Ranges: bytes
|
||||
X-Trans-Id: txe8ca5138ac8643ec84070543a0c9c91e
|
||||
Content-Length: 0
|
||||
Date: Mon, 07 Nov 2011 17:07:01 GMT</computeroutput></screen>
|
||||
</example>
|
||||
<para>So, you take the X-Auth-Token obtained from the
|
||||
authentication operation, pass it as a header value,
|
||||
execute the operation against the URL obtained from the
|
||||
authentication operation, and force the GET verb with the
|
||||
-X switch. What you get back tells you there aren't any
|
||||
containers.</para>
|
||||
<para>Next, let's create a container and then do the listing
|
||||
again:</para>
|
||||
<example>
|
||||
<title>cURL Create Storage Container</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/george</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 18
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: txb25576385284476d9fa6c73835f21650
|
||||
Date: Mon, 07 Nov 2011 17:44:20 GMT
|
||||
|
||||
201 Created</computeroutput></screen>
|
||||
</example>
|
||||
<para>Append the container name to the URL and force the PUT
|
||||
verb. That creates a container, which we can now see when
|
||||
we do a listing:</para>
|
||||
<example>
|
||||
<title>cURL List Storage Container After a
|
||||
Creation</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Account-Object-Count: 0
|
||||
X-Account-Bytes-Used: 0
|
||||
X-Account-Container-Count: 1
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 7
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: txaedd6b080626453399c9f5febbddb73b
|
||||
Date: Mon, 07 Nov 2011 17:44:23 GMT
|
||||
|
||||
george</computeroutput></screen>
|
||||
</example>
|
||||
<para>You may have noticed the account metadata that comes
|
||||
back from the listing call. As you'd guess, it'll tell you
|
||||
how many objects you have, how much space you are using,
|
||||
and how many containers you are using.</para>
|
||||
</section>
|
||||
<section xml:id="paging-containers">
|
||||
<title>Paging Lists of Containers</title>
|
||||
<para>If you have a large number of containers, it is
|
||||
sometimes more convenient to page through them than
|
||||
getting some big long list of them. If I create more
|
||||
containers and then do a regular listing, here's what it
|
||||
looks like with five containers:</para>
|
||||
<example>
|
||||
<title>cURL List Storage Container (long list)</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Account-Object-Count: 0
|
||||
X-Account-Bytes-Used: 0
|
||||
X-Account-Container-Count: 5
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 31
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: txb28795cc25b04f0dbce408dfa5a3cfc9
|
||||
Date: Mon, 07 Nov 2011 19:03:06 GMT
|
||||
|
||||
cosmo
|
||||
dogs
|
||||
elaine
|
||||
george
|
||||
jerry</computeroutput></screen>
|
||||
</example>
|
||||
<para>Suppose I want a page size of 2, all I do is append a
|
||||
""?limit=2"" to my URL:</para>
|
||||
<example>
|
||||
<title>cURL List Storage Container with Paging (first
|
||||
page)</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?limit=2</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Account-Object-Count: 0
|
||||
X-Account-Bytes-Used: 0
|
||||
X-Account-Container-Count: 5
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 11
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx940ee02c1a65451e96a2a2532e3a7ce7
|
||||
Date: Mon, 07 Nov 2011 19:05:30 GMT
|
||||
|
||||
cosmo
|
||||
dogs</computeroutput></screen>
|
||||
</example>
|
||||
<para>Not surprisingly, I only get two containers. To get the
|
||||
next page, you tell the system which item you last saw
|
||||
with the "marker=" specifier:</para>
|
||||
<example>
|
||||
<title>cURL List Storage Container with Paging (later
|
||||
pages)</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?marker=dogs\&limit=2</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Account-Object-Count: 0
|
||||
X-Account-Bytes-Used: 0
|
||||
X-Account-Container-Count: 5
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 14
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx2a69f7ec38c34078a185c5875a4c0e34
|
||||
Date: Mon, 07 Nov 2011 19:15:00 GMT
|
||||
|
||||
elaine
|
||||
george</computeroutput></screen>
|
||||
</example>
|
||||
<para>Notice that I had to use \& so that my bash shell
|
||||
didn't try to interpret the & as wanting to run
|
||||
something in its own thread. With that in place, you get
|
||||
the next page of items that appear after the
|
||||
marker.</para>
|
||||
</section>
|
||||
<section xml:id="serialized-output">
|
||||
<title>Serialized Output</title>
|
||||
<para>In other situations, like if you are working on a
|
||||
language binding on top of the REST API, you might want
|
||||
more structured data back from the method calls. By
|
||||
appending a "format=" and then choosing either json or
|
||||
xml, you can get that structured data back you've been
|
||||
dreaming about.</para>
|
||||
<example>
|
||||
<title>cURL List Storage Container (JSON output)</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?format=json</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Account-Object-Count: 0
|
||||
X-Account-Bytes-Used: 0
|
||||
X-Account-Container-Count: 5
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 187
|
||||
Content-Type: application/json; charset=utf-8
|
||||
X-Trans-Id: txd408573a51d2423c848cba191fbede9b
|
||||
Date: Mon, 07 Nov 2011 19:17:33 GMT
|
||||
|
||||
[{"name":"cosmo", "count":0,"bytes":0},
|
||||
{"name":"dogs","count":0,"bytes":0},
|
||||
{"name":"elaine","count":0,"bytes":0},
|
||||
{"name":"george","count":0,"bytes":0},
|
||||
{"name":"jerry","count":0,"bytes":0}]</computeroutput></screen>
|
||||
</example>
|
||||
<example>
|
||||
<title>cURL List Storage Container (XML output)</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343?format=xml</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Account-Object-Count: 0
|
||||
X-Account-Bytes-Used: 0
|
||||
X-Account-Container-Count: 5
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 479
|
||||
Content-Type: application/xml; charset=utf-8
|
||||
X-Trans-Id: tx5e5685a15d0b406799b6a425b1150e4c
|
||||
Date: Mon, 07 Nov 2011 19:17:38 GMT
|
||||
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<account name="AUTH_a23f73d2-abfb-4656-af94-32ddec35dab8">
|
||||
<container><name>cosmo</name><count>0</count><bytes>0</bytes></container>
|
||||
<container><name>dogs</name><count>0</count><bytes>0</bytes></container>
|
||||
<container><name>elaine</name><count>0</count><bytes>0</bytes></container>
|
||||
<container><name>george</name><count>0</count><bytes>0</bytes></container>
|
||||
<container><name>jerry</name><count>0</count><bytes>0</bytes></container>
|
||||
</account></computeroutput></screen>
|
||||
</example>
|
||||
<para>The remainder of the examples in this document will use
|
||||
the standard, non-serialized output but all operations
|
||||
accept the format argument. You might notice that when you
|
||||
use one of the formats, you get more information about the
|
||||
containers. That's the per-container metadata, which is
|
||||
covered in the next section.</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="container-metadata-and-delete-containers">
|
||||
<title>Container Metadata and Deleting Containers</title>
|
||||
<para>You can get at container metadata directly simply by
|
||||
appending the name of the container to a HEAD
|
||||
request:</para>
|
||||
<example>
|
||||
<title>cURL List Container Metadata</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs</uri></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: tx3dd984f9482341dd97546e9d49d65e90
|
||||
Content-Length: 0
|
||||
Date: Mon, 07 Nov 2011 20:39:41 GMT</computeroutput></screen>
|
||||
</example>
|
||||
<para>Not very exciting without any objects in the container,
|
||||
but you get the idea. While you cannot update or delete
|
||||
container metadata, you can delete a container:</para>
|
||||
<example>
|
||||
<title>cURL Delete Storage Container</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X DELETE</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/george</uri></userinput></screen>
|
||||
<screen><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>
|
||||
</example>
|
||||
<para>Then let's confirm the delete by listing the containers
|
||||
again:</para>
|
||||
<example>
|
||||
<title>cURL List Containers After a Delete</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343</uri></userinput></screen>
|
||||
<screen><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>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="special-metadata-acls">
|
||||
<title>Special Metadata: Container ACLs</title>
|
||||
<para>A particularly important metadata element for containers
|
||||
is X-Container-Read, which establishes the ACL permissions
|
||||
on who can read objects in the container. Prior to being
|
||||
set, the ACL logic default to only be accessible to
|
||||
someone with a valid X-Auth-Token for the account in
|
||||
question. Doing a simple listing of a container shows us
|
||||
the absence of X-Container-Read in this default
|
||||
situation:</para>
|
||||
<example>
|
||||
<title>cURL List Container Showing Lack of ACL</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry</uri></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>
|
||||
</example>
|
||||
<para>Now we'll set the X-Container-Read. For a full
|
||||
explanation of valid values, see:
|
||||
http://swift.openstack.org/misc.html#acls but for our
|
||||
simple needs, we'll enable read access and listing access
|
||||
to anybody:</para>
|
||||
<example>
|
||||
<title>cURL Setting an ACL on a Container</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<option>-H "X-Container-Read: .r:*,.rlistings"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry</uri></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>
|
||||
</example>
|
||||
<para>To see the metadata change, do a listing again:</para>
|
||||
<example>
|
||||
<title>cURL List Container Showing with an ACL</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry</uri></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>
|
||||
</example>
|
||||
<para>The side effect of giving anybody read access is that
|
||||
any object in the container is now accessible from a
|
||||
browser simply by entering the X-Storage-URL used
|
||||
throughout the session and append the object name. For
|
||||
example:</para>
|
||||
<para>https://storage.swiftdrive.com/v1/CF_xer7_343/jerry/cereal.jpg</para>
|
||||
<para>would be the URL of an object named "cereal.jpg" in the
|
||||
container "jerry" that has been made publicly accessible
|
||||
using this method.</para>
|
||||
</section>
|
||||
<section xml:id="creating-objects">
|
||||
<title>Creating Objects</title>
|
||||
<para>Enough with containers already, let's start to upload
|
||||
some objects. Suppose you had a local directory full of
|
||||
dog pictures:</para>
|
||||
<example>
|
||||
<title>Sample File Listing</title>
|
||||
<screen><prompt>$</prompt> <userinput>ls -l</userinput>
|
||||
<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>
|
||||
</example>
|
||||
<para>In order to put one of them in a container called "dogs"
|
||||
with cURL, you'd do this:</para>
|
||||
<example>
|
||||
<title>Creating and Uploading an Object to a
|
||||
Container</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<option>-T JingleRocky.jpg</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 118
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
Etag: f7d40eceffdd9c2ecab226105737b2a6
|
||||
Last-Modified: Mon, 07 Nov 2011 22:51:29 GMT
|
||||
X-Trans-Id: txd131cc897c78403daf5fad010d4d7152
|
||||
Date: Mon, 07 Nov 2011 22:51:30 GMT
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>201 Created</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>201 Created</h1>
|
||||
<br /><br />
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html></computeroutput></screen>
|
||||
</example>
|
||||
<para>The object gets named from whatever we append to the URL
|
||||
path beyond the container name and the -T switch lets us
|
||||
name a file to push with the operation as the request
|
||||
body. We can confirm the upload by checking the container
|
||||
again:</para>
|
||||
<example>
|
||||
<title>cURL List Container Showing Newly Uploaded
|
||||
Object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Container-Object-Count: 1
|
||||
X-Container-Read: .r:*,.rlistings
|
||||
X-Container-Bytes-Used: 44765
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 16
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx83be89d4e1a34eacbfeebcdfc7a7f2e7
|
||||
Date: Mon, 07 Nov 2011 22:56:25 GMT
|
||||
|
||||
JingleRocky.jpg</computeroutput></screen>
|
||||
</example>
|
||||
<para>Notice that the container metadata now reflects the
|
||||
number of objects and the bytes match what we saw when we
|
||||
did the directory listing. After uploading the other two
|
||||
similarly, we get a full object listing:</para>
|
||||
<example>
|
||||
<title>cURL List Container Showing Multiple Newly Uploaded
|
||||
Objects</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Container-Object-Count: 3
|
||||
X-Container-Read: .r:*,.rlistings
|
||||
X-Container-Bytes-Used: 252732
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 53
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: txae17dfa78da64117aaf07585a1b02115
|
||||
Date: Mon, 07 Nov 2011 23:00:56 GMT
|
||||
|
||||
JingleRocky.jpg
|
||||
RockyAndBuster.jpg
|
||||
SittingBuster.jpg</computeroutput></screen>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="create_static_large_objects">
|
||||
<title>Creating Static Large Objects</title>
|
||||
<para>Creation of a static large object is done in several
|
||||
steps. First we divide the content into pieces and upload
|
||||
each piece into a segment object. Then we create a
|
||||
manifest object. In this example, we will place the
|
||||
segment objects into the "segments" container and the
|
||||
manifest object into the "images" container. We are not
|
||||
required to do this, but using a dedicated container for
|
||||
segment objects is convenient.</para>
|
||||
<para>Assuming we've already divided our image into three
|
||||
files, let's upload them. We have removed non-essential
|
||||
response headers so you can see the important
|
||||
details.</para>
|
||||
<example>
|
||||
<title>Uploading first segment</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./piece1</option>
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-one</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 4000000
|
||||
Etag: f7365c1419b4f349592c00bd0cfb9b9a</computeroutput></screen>
|
||||
</example>
|
||||
<example>
|
||||
<title>Uploading second segment</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./piece2</option>
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-two</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 2000000
|
||||
Etag: ad81e97b10e870613aecb5ced52adbaa</computeroutput></screen>
|
||||
</example>
|
||||
<example>
|
||||
<title>Uploading final segment</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./piece3</option>
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/segments/terrier-jpg-three</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 1000
|
||||
Etag: 00b046c9d74c3e8f93b320c5e5fdc2c3</computeroutput></screen>
|
||||
</example>
|
||||
<para>At this stage we are ready to create the manifest
|
||||
listing. Notice that the size and ETag are copied from
|
||||
uploads above. Lets use an editor to create a file called
|
||||
<code>manifest.json</code> with the following
|
||||
content:</para>
|
||||
<example>
|
||||
<title>Manifest List Example</title>
|
||||
<screen><computeroutput> [
|
||||
{
|
||||
"path": "segments/terrier-jpg-one",
|
||||
"etag": "f7365c1419b4f349592c00bd0cfb9b9a",
|
||||
"size_bytes": 4000000
|
||||
},
|
||||
{
|
||||
"path": "segments/terrier-jpg-two",
|
||||
"etag": "ad81e97b10e870613aecb5ced52adbaa",
|
||||
"size_bytes": 2000000
|
||||
},
|
||||
"path": "segments/terrier-jpg-three",
|
||||
"etag": "00b046c9d74c3e8f93b320c5e5fdc2c3",
|
||||
"size_bytes": 1000
|
||||
{
|
||||
}
|
||||
]</computeroutput></screen>
|
||||
</example>
|
||||
<para>The final operation is to upload this content into a
|
||||
manifest object. To indicate that this is a manifest
|
||||
object, you need to specify the
|
||||
<code>?multipart-manifest=put</code> query
|
||||
string.</para>
|
||||
<example>
|
||||
<title>Uploading manifest object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option> <option>-T ./manifest.json</option>
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg?multipart-manifest=put</uri></userinput></screen>
|
||||
</example>
|
||||
<para>We can now examine our static large object. Notice that
|
||||
the size is the total size of all the segments.</para>
|
||||
<example>
|
||||
<title>Examining a manifest object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> <option>-H "X-Auth-Token: 12345"</option>
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/images/terrier-jpg</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
Content-Length: 6001000
|
||||
Etag: "0c922c37f915efb1c9b97e6328b3e660"</computeroutput></screen>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="paging-objects">
|
||||
<title>Paging Lists of Objects</title>
|
||||
<para>Exactly like listing containers, objects can be listed
|
||||
in pages at a time using markers to denote pages. From the
|
||||
previous example with 3 objects in the container "dogs",
|
||||
the list can be paged with the "limit" query string
|
||||
variable:</para>
|
||||
<example>
|
||||
<title>cURL List Objects (first page)</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?limit=2</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Container-Object-Count: 3
|
||||
X-Container-Read: .r:*,.rlistings
|
||||
X-Container-Bytes-Used: 252732
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 35
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx5e00fa9fa895423198bc814cb0c6162d
|
||||
Date: Tue, 15 Nov 2011 03:53:51 GMT
|
||||
|
||||
JingleRocky.jpg
|
||||
RockyAndBuster.jpg</computeroutput></screen>
|
||||
</example>
|
||||
<para>And the second page fetched with:</para>
|
||||
<example>
|
||||
<title>cURL List Objects with Paging (later pages)</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs?marker=RockyAndBuster.jpg\&limit=2</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Container-Object-Count: 3
|
||||
X-Container-Read: .r:*,.rlistings
|
||||
X-Container-Bytes-Used: 252732
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 18
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: txe1287a7179dc4dfd98610850a0fff157
|
||||
Date: Tue, 15 Nov 2011 03:54:21 GMT
|
||||
|
||||
SittingBuster.jpg</computeroutput></screen>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="retrieve-copy-retrieve-objects">
|
||||
<title>Retrieve, Copy, and Delete Objects</title>
|
||||
<para>Now we'll retrieve an object previously uploaded. First,
|
||||
we'll remove the local copy:</para>
|
||||
<example>
|
||||
<title>Removing Local Copies</title>
|
||||
<screen><prompt>$</prompt> <userinput>ls -l</userinput>
|
||||
<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
|
||||
$ rm JingleRocky.jpg
|
||||
$ ls -l
|
||||
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>
|
||||
</example>
|
||||
<para>Be sure not to use -i switch here since what we want is
|
||||
the raw data, which we'll then pipe to a file:</para>
|
||||
<example>
|
||||
<title>cURL Retrieve an Object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg > JingleRocky.jpg</uri></userinput></screen>
|
||||
<screen><prompt>$</prompt> <userinput>ls -l</userinput>
|
||||
<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>
|
||||
</example>
|
||||
<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>
|
||||
<example>
|
||||
<title>cURL Server-side Copy an Object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<option>-H "X-Copy-From: /dogs/JingleRocky.jpg"</option> \
|
||||
<option>-H "Content-Length: 0"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg</uri></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>
|
||||
</example>
|
||||
<para>You can then confirm the new location of the object. To
|
||||
do this, you do a GET with the destination container to
|
||||
see the listing of the object:</para>
|
||||
<example>
|
||||
<title>cURL Confirming the Server-side Copy an
|
||||
Object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/</uri></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>
|
||||
</example>
|
||||
<para>To delete an object from its container, simply use the
|
||||
DELETE verb:</para>
|
||||
<example>
|
||||
<title>cURL Delete an Object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X DELETE</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/JingleRocky.jpg</uri></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>
|
||||
</example>
|
||||
<para>Confirming the deletion by doing a container
|
||||
listing:</para>
|
||||
<example>
|
||||
<title>cURL Confirming the Delete an Object</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/elaine/</uri></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>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="object-metadata">
|
||||
<title>Object Metadata</title>
|
||||
<para>Objects can have whatever metadata keys/values you
|
||||
choose. Simply POST an HTTP Header to the object in the
|
||||
form of X-Object-Meta-<key>: <value>. Like
|
||||
this:</para>
|
||||
<example>
|
||||
<title>cURL Set Object Metadata</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X POST</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<option>-H "X-Object-Meta-Breed: Terrier pit bull mix""</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg</uri></userinput></screen>
|
||||
<screen><computeroutput> <html>
|
||||
<head>
|
||||
<title>202 Accepted</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>202 Accepted</h1>
|
||||
The request is accepted for processing.<br /><br />
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html></computeroutput></screen>
|
||||
</example>
|
||||
<para>And then read the object metadata with a HEAD on the
|
||||
object path:</para>
|
||||
<example>
|
||||
<title>cURL Reading Object Metadata</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X HEAD</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/dogs/JingleRocky.jpg</uri></userinput></screen>
|
||||
<screen><computeroutput> HTTP/1.1 200 OK
|
||||
X-Object-Meta-Breed: Terrier pit bull mix
|
||||
Last-Modified: Tue, 08 Nov 2011 01:26:49 GMT
|
||||
Etag: f7d40eceffdd9c2ecab226105737b2a6
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 44765
|
||||
Content-Type: image/jpeg
|
||||
X-Trans-Id: txa8bff9ad7ef844829103c1f9b8c20781
|
||||
Date: Tue, 08 Nov 2011 01:29:35 GMT</computeroutput></screen>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="folders-directories">
|
||||
<title>Pseudo-Hierarchical Folders/Directories</title>
|
||||
<para>For the last section, we come to the most confusing
|
||||
concept in Object Storage. In most storage systems, you
|
||||
have the ability to create custom hierarchies of files so
|
||||
that you can better organize them. On its surface, Object
|
||||
Storage only gives you one level of hierarchy in the form
|
||||
of containers. However, it turns out that you can get
|
||||
creative with naming your objects to give yourself the
|
||||
same effect as having hierarchical containers.</para>
|
||||
<para>Let's start with a fresh container without any objects
|
||||
in it:</para>
|
||||
<example>
|
||||
<title>cURL Create New Container for Folders</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 18
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: txc78254a41b374b6ea10590d90874f769
|
||||
Date: Wed, 16 Nov 2011 00:06:22 GMT
|
||||
|
||||
201 Created</computeroutput></screen>
|
||||
</example>
|
||||
<para>Now list the new container:</para>
|
||||
<example>
|
||||
<title>cURL Listing the New Container</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos</uri></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: tx49112200f7934c2bab1de3ae103c368e
|
||||
Content-Length: 0
|
||||
Date: Wed, 16 Nov 2011 00:06:26 GMT</computeroutput></screen>
|
||||
</example>
|
||||
<para>Next, add an object but prefix the name with the
|
||||
hierarchy desired:</para>
|
||||
<example>
|
||||
<title>cURL Upload an Object with a Prefix</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<option>-T JingleRocky.jpg</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos/terriers/JingleRocky.jpg</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 118
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
Etag: f7d40eceffdd9c2ecab226105737b2a6
|
||||
Last-Modified: Wed, 16 Nov 2011 00:09:18 GMT
|
||||
X-Trans-Id: txe34fdf2704f044e3a7102256386b1cb7
|
||||
Date: Wed, 16 Nov 2011 00:09:19 GMT
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>201 Created</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>201 Created</h1>
|
||||
<br /><br />
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html></computeroutput></screen>
|
||||
</example>
|
||||
<para>Do it again with a different object and prefix:</para>
|
||||
<example>
|
||||
<title>cURL Upload a Different Object with a Different
|
||||
Prefix</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X PUT</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<option>-T SittingBuster.jpg</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos/chihuahuas/SittingBuster.jpg</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 201 Created
|
||||
Content-Length: 118
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
Etag: e692e744c7180ee368166a24f1a2fa9b
|
||||
Last-Modified: Wed, 16 Nov 2011 00:52:25 GMT
|
||||
X-Trans-Id: txe229d03af5ea4d2ea1071def213c3f02
|
||||
Date: Wed, 16 Nov 2011 00:52:25 GMT
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>201 Created</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>201 Created</h1>
|
||||
<br /><br />
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html></computeroutput></screen>
|
||||
</example>
|
||||
<para>Now list the container, revealing the prefixes:</para>
|
||||
<example>
|
||||
<title>cURL Listing a Container with Object Prefix</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Container-Object-Count: 2
|
||||
X-Container-Bytes-Used: 151868
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 54
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx8544a17e8b1e4da693145fb5f2e6db43
|
||||
Date: Wed, 16 Nov 2011 00:53:43 GMT
|
||||
|
||||
chihuahuas/SittingBuster.jpg
|
||||
terriers/JingleRocky.jpg</computeroutput></screen>
|
||||
</example>
|
||||
<para>If you want to perform hierarchical listings, with the
|
||||
prefixes in place, you can use the "path" query string
|
||||
variable:</para>
|
||||
<example>
|
||||
<title>cURL Listing a Container with a Path</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos?path=terriers</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Container-Object-Count: 2
|
||||
X-Container-Bytes-Used: 151868
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 25
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx3f1b9575d4de4a7d97ba3f9ad81923cc
|
||||
Date: Wed, 16 Nov 2011 00:55:12 GMT
|
||||
|
||||
terriers/JingleRocky.jpg</computeroutput></screen>
|
||||
</example>
|
||||
<para>If you wanted to see what prefixes were in place, you
|
||||
can use the "delimiter" query string variable to
|
||||
distinguish prefix paths from object names:</para>
|
||||
<example>
|
||||
<title>cURL Listing a Container with a Delimiter</title>
|
||||
<screen><prompt>$</prompt> <userinput><command>curl</command> <option>–X GET</option> <option>-i</option> \
|
||||
<option>-H "X-Auth-Token: fc81aaa6-98a1-9ab0-94ba-aba9a89aa9ae"</option> \
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/photos?delimiter=/</uri></userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
X-Container-Object-Count: 2
|
||||
X-Container-Bytes-Used: 151868
|
||||
Accept-Ranges: bytes
|
||||
Content-Length: 22
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
X-Trans-Id: tx7222a3dd73fe44b888db4e58cc647d1e
|
||||
Date: Wed, 16 Nov 2011 00:57:40 GMT
|
||||
|
||||
chihuahuas/
|
||||
terriers/</computeroutput></screen>
|
||||
</example>
|
||||
<para>Using these in combination allows you to discover
|
||||
directories within a particular path and then further
|
||||
drill down based on the results.</para>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
@ -4,7 +4,7 @@
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!ENTITY nbsp " ">
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
||||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||||
@ -35,15 +35,14 @@ format="SVG" scale="60"/>
|
||||
storage system is designed to provide a safe, secure,
|
||||
automatically re-sizing and network-accessible way to store
|
||||
data. You can store an unlimited quantity of files and each
|
||||
file can be as large as 5 GBs, plus with large object
|
||||
file can be as large as 5 GB, plus with large object
|
||||
creation, you can upload and store objects of virtually any
|
||||
size.</para>
|
||||
<para>OpenStack Object Storage allows users to store and retrieve
|
||||
files and content through a simple Web Service interface
|
||||
(ReST: Representational State Transfer). There are also
|
||||
language-specific APIs that utilize the ReSTful API but make
|
||||
it much easier for developers to integrate into their
|
||||
applications.</para>
|
||||
<para>OpenStack Object Storage enables you to store and get files
|
||||
and content through the Representational State Transfer (REST)
|
||||
interface. There are also language-specific APIs that utilize
|
||||
the RESTful API but make it much easier for developers to
|
||||
integrate into their applications.</para>
|
||||
<para>For more details on the OpenStack Object Storage service,
|
||||
please refer to <link
|
||||
xlink:href="http://docs.openstack.org/developer/swift/"
|
||||
@ -56,7 +55,7 @@ format="SVG" scale="60"/>
|
||||
<title>Intended Audience</title>
|
||||
<para>This guide is intended to assist software developers who
|
||||
want to develop applications using the OpenStack Object
|
||||
Storage API. It fully documents the ReST application
|
||||
Storage API. It fully documents the REST application
|
||||
programming interface (API) that allows developers to
|
||||
interact with the storage components of the OpenStack
|
||||
Object Storage system. To use the information provided
|
||||
@ -66,7 +65,7 @@ format="SVG" scale="60"/>
|
||||
be familiar with:</para>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>ReSTful web services</para>
|
||||
<para>RESTful web services</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>HTTP/1.1</para>
|
||||
@ -74,12 +73,12 @@ format="SVG" scale="60"/>
|
||||
</itemizedlist>
|
||||
<para>You can also find language-specific APIs in several
|
||||
popular programming languages such as C#/.NET, Java, PHP,
|
||||
Python, and Ruby. These APIs utilize the ReST API and are
|
||||
Python, and Ruby. These APIs utilize the REST API and are
|
||||
provided to help developers rapidly integrate OpenStack
|
||||
Object Storage support into their applications without
|
||||
needing to write at the ReST interface. Each API includes
|
||||
needing to write at the REST interface. Each API includes
|
||||
its own documentation in its native format. For example,
|
||||
the Java API includes Javadoc documentation.</para>
|
||||
</section>
|
||||
<xi:include href="section_object-api-dochistory.xml"/>
|
||||
<xi:include href="section_object-api-dochistory.xml"/>
|
||||
</preface>
|
||||
|
||||
11
openstack-object-storage-dev/samples/bulk-delete-request.xml
Normal file
11
openstack-object-storage-dev/samples/bulk-delete-request.xml
Normal file
@ -0,0 +1,11 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<delete>
|
||||
<number_deleted>2</number_deleted>
|
||||
<number_not_found>4</number_not_found>
|
||||
<errors>
|
||||
<object>
|
||||
<name>/v1/12345678912345/mycontainer</name>
|
||||
<status>409 Conflict</status>
|
||||
</object>
|
||||
</errors>
|
||||
</delete>
|
||||
@ -0,0 +1,11 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<delete>
|
||||
<number_deleted>2</number_deleted>
|
||||
<number_not_found>4</number_not_found>
|
||||
<errors>
|
||||
<object>
|
||||
<name>/v1/12345678912345/mycontainer</name>
|
||||
<status>409 Conflict</status>
|
||||
</object>
|
||||
</errors>
|
||||
</delete>
|
||||
@ -1,13 +1,13 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<account name="MichaelBarton">
|
||||
<account name="my_account">
|
||||
<container>
|
||||
<name>test_container_1</name>
|
||||
<count>2</count>
|
||||
<bytes>78</bytes>
|
||||
<name>janeausten</name>
|
||||
<count>0</count>
|
||||
<bytes>0</bytes>
|
||||
</container>
|
||||
<container>
|
||||
<name>test_container_2</name>
|
||||
<name>marktwain</name>
|
||||
<count>1</count>
|
||||
<bytes>17</bytes>
|
||||
<bytes>14</bytes>
|
||||
</container>
|
||||
</account>
|
||||
</account>
|
||||
|
||||
@ -0,0 +1,13 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<account name="MichaelBarton">
|
||||
<container>
|
||||
<name>test_container_1</name>
|
||||
<count>2</count>
|
||||
<bytes>78</bytes>
|
||||
</container>
|
||||
<container>
|
||||
<name>test_container_2</name>
|
||||
<count>1</count>
|
||||
<bytes>17</bytes>
|
||||
</container>
|
||||
</account>
|
||||
17
openstack-object-storage-dev/samples/manifest.json
Normal file
17
openstack-object-storage-dev/samples/manifest.json
Normal file
@ -0,0 +1,17 @@
|
||||
[
|
||||
{
|
||||
"path":"segments/terrier-jpg-one",
|
||||
"etag":"f7365c1419b4f349592c00bd0cfb9b9a",
|
||||
"size_bytes":4000000
|
||||
},
|
||||
{
|
||||
"path":"segments/terrier-jpg-two",
|
||||
"etag":"ad81e97b10e870613aecb5ced52adbaa",
|
||||
"size_bytes":2000000
|
||||
},
|
||||
{
|
||||
"path":"segments/terrier-jpg-three",
|
||||
"etag":"00b046c9d74c3e8f93b320c5e5fdc2c3",
|
||||
"size_bytes":1000
|
||||
}
|
||||
]
|
||||
@ -1,5 +1 @@
|
||||
PUT /<api version>/<account>/<container>/<object> HTTP/1.1
|
||||
Host: storage.clouddrive.com
|
||||
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
||||
Content-Type: image/jpeg
|
||||
X-Delete-At: 1339429105
|
||||
curl -i $publicURL/marktwain/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H "Content-Type: application/octet-stream"
|
||||
25
openstack-object-storage-dev/samples/server-post-req.xml
Normal file
25
openstack-object-storage-dev/samples/server-post-req.xml
Normal file
@ -0,0 +1,25 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<server xmlns="http://docs.openstack.org/compute/api/v1.1"
|
||||
imageRef="3afe97b2-26dc-49c5-a2cc-a2fc8d80c001" flavorRef="2"
|
||||
name="api-test-server-xml2">
|
||||
<metadata>
|
||||
<meta key="My Server Name">API Test Server XML</meta>
|
||||
</metadata>
|
||||
<personality>
|
||||
<file path="/etc/banner.txt">
|
||||
ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
|
||||
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
|
||||
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
|
||||
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
|
||||
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
|
||||
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
|
||||
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
|
||||
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
|
||||
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==</file>
|
||||
</personality>
|
||||
<networks>
|
||||
<uuid>0ef47ac7-6797-4e01-8a47-ed26ec3aaa56</uuid>
|
||||
<uuid>00000000-0000-0000-0000-000000000000</uuid>
|
||||
<uuid>11111111-1111-1111-1111-111111111111</uuid>
|
||||
</networks>
|
||||
</server>
|
||||
15
openstack-object-storage-dev/samples/server-post-resp.xml
Normal file
15
openstack-object-storage-dev/samples/server-post-resp.xml
Normal file
@ -0,0 +1,15 @@
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<server
|
||||
xmlns:OS-DCF="http://docs.openstack.org/compute/ext/disk_config/api/v1.1"
|
||||
xmlns:atom="http://www.w3.org/2005/Atom"
|
||||
xmlns="http://docs.openstack.org/compute/api/v1.1"
|
||||
id="ed5c7754-29b6-45fa-96cb-ab64958c8c0a" adminPass="Dd5pNZtpVVQ3"
|
||||
OS-DCF:diskConfig="AUTO">
|
||||
<metadata/>
|
||||
<atom:link
|
||||
href="https://dfw.servers.api.rackspacecloud.com/v2/010101/servers/ed5c7754-29b6-45fa-96cb-ab64958c8c0a"
|
||||
rel="self"/>
|
||||
<atom:link
|
||||
href="https://dfw.servers.api.rackspacecloud.com/010101/servers/ed5c7754-29b6-45fa-96cb-ab64958c8c0a"
|
||||
rel="bookmark"/>
|
||||
</server>
|
||||
@ -0,0 +1,114 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||||
]>
|
||||
<section 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="archive-auto-extract">
|
||||
<title>Auto-extract archive files</title>
|
||||
<para>To discover whether your Object Storage system supports
|
||||
this feature, see <xref linkend="discoverability"
|
||||
/>. Alternatively, check with your service provider.</para>
|
||||
<para>Use the auto-extract archive feature to upload a tar(1)
|
||||
archive file.</para>
|
||||
<para>The Object Storage system extracts files from the archive
|
||||
file and creates an object.</para>
|
||||
<section xml:id="archive-auto-extract-put">
|
||||
<title>Auto-extract archive PUT request</title>
|
||||
<para>To upload an archive file, you make a &PUT; request. Add
|
||||
the
|
||||
<parameter>extract-archive=<replaceable>format</replaceable></parameter>
|
||||
query parameter to indicate that you are uploading a
|
||||
tar(1) archive file instead of normal content.</para>
|
||||
<para>Valid values for the <replaceable>format</replaceable>
|
||||
variable are <literal>tar</literal>,
|
||||
<literal>tar.gz</literal>, or
|
||||
<literal>tar.bz2</literal>.</para>
|
||||
<para>The path you specify in the &PUT; request is a prefix
|
||||
for the resulting object names.</para>
|
||||
<para>For example, if the first object in the tar(1) archive
|
||||
is <filename>/home/file1.txt</filename> and you specify
|
||||
the
|
||||
<filename>/v1/12345678912345/mybackup/castor/</filename>
|
||||
path, the operation creates the
|
||||
<filename>castor/home/file1.txt</filename> object in
|
||||
the <literal>mybackup</literal> container in the
|
||||
<literal>12345678912345</literal> account.</para>
|
||||
<para>In the &PUT; request, you can specify the path
|
||||
for:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>An account</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Optionally, a specific container</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Optionally, a specific object prefix</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="archive-auto-extract-create">
|
||||
<title>Create an archive for auto-extract</title>
|
||||
<para>You must use the tar(1) utility to create the tar(1)
|
||||
archive file.</para>
|
||||
<para>You can upload regular files but you cannot upload other
|
||||
items, such as empty directories, symbolic links, and so
|
||||
on.</para>
|
||||
<para>You must UTF-8-encode the member names.</para>
|
||||
<para>The archive auto-extract feature supports these
|
||||
formats:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The POSIX.1-1988 Ustar format.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The GNU tar format. Includes the long name, long
|
||||
link, and sparse extensions.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The POSIX.1-2001 pax format.</para>
|
||||
<para>Use gzip(1) or bzip2(1) to compress the
|
||||
archive.</para>
|
||||
<para>Use the <parameter>extract-archive</parameter>
|
||||
query parameter to specify the format. Valid
|
||||
values for this parameter are <literal>tar</literal>,
|
||||
<literal>tar.gz</literal>, or
|
||||
<literal>tar.bz2</literal>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="archive-auto-extract-response">
|
||||
<title>Auto-extract archive response: JSON</title>
|
||||
<para>When Object Storage processes the request, it performs
|
||||
multiple sub-operations. Even if all sub-operations fail,
|
||||
the operation returns a <returnvalue>201</returnvalue>
|
||||
<literal>Created</literal> status. You must examine the
|
||||
response body to determine which members failed to result
|
||||
in an object creation.</para>
|
||||
<para>You can set the <literal>Accept</literal> request header
|
||||
to one of these values, which defines the response format:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>text/plain</literal>. Formats response
|
||||
as plain text. If you omit the
|
||||
<literal>Accept</literal> header,
|
||||
<literal>text/plain</literal> is the
|
||||
default.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>application/json</literal>. Formats
|
||||
response as JSON.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>application/xml</literal> or
|
||||
<literal>text/xml</literal>. Formats response
|
||||
as XML.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>For more information, see <xref
|
||||
linkend="archive-auto-extract-response"/>.</para>
|
||||
</section>
|
||||
</section>
|
||||
@ -0,0 +1,96 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section 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="authentication">
|
||||
<title>Authentication</title>
|
||||
<para>The <emphasis role="italic">owner</emphasis> of an Object
|
||||
Storage account controls access to that account and its
|
||||
containers and objects. An owner is the user who has the
|
||||
<literal>admin</literal> role for that tenant. The tenant
|
||||
is also known as the project or account. As the account owner,
|
||||
you can modify account metadata and create, modify, and delete
|
||||
containers and objects.</para>
|
||||
<para>To identify yourself as the account owner, include an
|
||||
authentication token in the <literal>X-Auth-Token</literal>
|
||||
header in the API request.</para>
|
||||
<para>Depending on the token value in the
|
||||
<literal>X-Auth-Token</literal> header, one of the
|
||||
following actions occur:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>X-Auth-Token</literal> contains the token
|
||||
for the account owner.</para>
|
||||
<para>The request is permitted and has full access to make
|
||||
changes to the account.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The <literal>X-Auth-Token</literal> header is
|
||||
omitted or it contains a token for a non-owner or a
|
||||
token that is not valid.</para>
|
||||
<para>The request fails with a <errorcode>401</errorcode>
|
||||
<errortext>Unauthorized</errortext> or
|
||||
<errorcode>403</errorcode>
|
||||
<errortext>Forbidden</errortext> response.</para>
|
||||
<para>You have no access to accounts or containers, unless
|
||||
an access control list (ACL) explicitly grants
|
||||
access.</para>
|
||||
<para>The account owner can grant account and container
|
||||
access to users through access control lists (ACLs).
|
||||
For more information about ACLs, see <xref
|
||||
linkend="acls"/>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The following table describes the authentication services
|
||||
that you can use with Object Storage:</para>
|
||||
<informaltable rules="all">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Authentication service</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<para>OpenStack Identity Service
|
||||
(Keystone)</para></td>
|
||||
<td><para>The Object Storage account is synonymous
|
||||
with the project or tenant ID.</para>
|
||||
<para>For information about the Identity Service,
|
||||
see <xref linkend="get_auth_token_keystone"
|
||||
/>.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<para>Tempauth middleware</para></td>
|
||||
<td><para>Object Storage includes this middleware.
|
||||
User and account management is performed in
|
||||
the Object Storage system itself.</para>
|
||||
<para>For information about Tempauth, see <xref
|
||||
linkend="get_auth_token_tempauth"
|
||||
/>.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<para>swauth (in GitHub) or other custom
|
||||
middleware</para></td>
|
||||
<td><para>This custom middleware is modeled on
|
||||
Tempauth, so usage is typically similar to
|
||||
Tempauth.</para><para>Specifically, you use
|
||||
the <literal>X-Auth-Token</literal> header to
|
||||
pass an authentication token to an API
|
||||
request.</para>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<para>Authentication tokens expire after a time period that the
|
||||
authentication service defines. When a token expires, use of
|
||||
the token causes requests to fail with a
|
||||
<errorcode>401</errorcode>
|
||||
<errortext>Unauthorized</errortext> response. To continue, you
|
||||
must obtain a new token.</para>
|
||||
</section>
|
||||
@ -0,0 +1,28 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section 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="content-disposition">
|
||||
<title>Use the Content-Disposition metadata</title>
|
||||
<para>To override the default behavior for a browser, use the
|
||||
<literal>Content-Disposition</literal> header to specify
|
||||
the override behavior and assign this header to an object. For
|
||||
example, this header might specify that the browser use a
|
||||
download program to save this file rather than show the file,
|
||||
which is the default.</para>
|
||||
<example>
|
||||
<title>Override browser default behavior request: HTTP</title>
|
||||
<para>This example assigns an attachment type to the
|
||||
<literal>Content-Disposition</literal> header. This
|
||||
attachment type indicates that the file is to be
|
||||
downloaded as <literal>goodbye.txt</literal>:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "Content-Length: 14" -H "Content-Type: application/octet-stream" -H "Content-Disposition: attachment; filename=goodbye.txt"</userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 202 Accepted
|
||||
Content-Length: 76
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
X-Trans-Id: txa9b5e57d7f354d7ea9f57-0052e17e13
|
||||
Date: Thu, 23 Jan 2014 20:39:47 GMT
|
||||
|
||||
<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html></computeroutput></screen>
|
||||
</example>
|
||||
</section>
|
||||
162
openstack-object-storage-dev/section_object-api-bulk-delete.xml
Normal file
162
openstack-object-storage-dev/section_object-api-bulk-delete.xml
Normal file
@ -0,0 +1,162 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||||
]>
|
||||
<section 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="bulk-delete">
|
||||
<title>Bulk delete</title>
|
||||
<para>To discover whether your Object Storage system supports
|
||||
this feature, see <xref linkend="discoverability"
|
||||
/>. Alternatively, check with your service provider.</para>
|
||||
<para>With bulk delete, you can delete up to 10,000 (configurable)
|
||||
objects or containers in one request. The objects to be
|
||||
deleted are listed in the body of a &POST; operation. Use
|
||||
the <parameter>bulk-delete</parameter> query parameter to
|
||||
indicate that you are performing a bulk delete operation
|
||||
instead of a normal delete.</para>
|
||||
<section xml:id="bulk-delete-request">
|
||||
<title>Bulk delete request body</title>
|
||||
<para>To perform a bulk delete operation, add the
|
||||
<parameter>bulk-delete</parameter> query parameter to
|
||||
the path. The path should be the account, such as
|
||||
<literal>/v1/12345678912345</literal>), that contains
|
||||
the objects and containers. You must set the
|
||||
<literal>Content-Type</literal> request header to
|
||||
<literal>text/plain</literal>.</para>
|
||||
<para>In the request body, specify a list of objects or
|
||||
containers names that are separated by a newline
|
||||
character.</para>
|
||||
<para>In addition:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>You must UTF-8-encode and then URL-encode the
|
||||
names.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>To indicate an object, specify the container and
|
||||
object name as:
|
||||
<literal><replaceable>CONTAINER_NAME</replaceable>/<replaceable>OBJECT_NAME</replaceable></literal></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>To indicate a container, specify the container
|
||||
name as:
|
||||
<literal><replaceable>CONTAINER_NAME</replaceable></literal></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>A container must be empty. If it contains
|
||||
objects, Object Storage does not delete the
|
||||
container.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>You can include a maximum of 10,000 items in the
|
||||
list. You can configure the maximum number of
|
||||
items value.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="bulk-delete-response">
|
||||
<title>Bulk delete response</title>
|
||||
<para>When Object Storage processes the request, it performs
|
||||
multiple sub-operations. Even if all sub-operations fail,
|
||||
the operation returns a <returnvalue>200</returnvalue>
|
||||
status. You must examine the response body to determine
|
||||
which members failed to result in an object
|
||||
deletion.</para>
|
||||
<para>You can set the <literal>Accept</literal> request header
|
||||
to one of these values, which defines the response
|
||||
format:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>text/plain</literal>. Formats response
|
||||
as plain text. If you omit the
|
||||
<literal>Accept</literal> header,
|
||||
<literal>text/plain</literal> is the
|
||||
default.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>application/json</literal>. Formats
|
||||
response as JSON.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>application/xml</literal> or
|
||||
<literal>text/xml</literal>. Formats response
|
||||
as XML.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>For more information, see <xref
|
||||
linkend="response-body-bulk-delete"/>.</para>
|
||||
</section>
|
||||
<section xml:id="response-body-bulk-delete">
|
||||
<title>Response body for bulk operations</title>
|
||||
<para>Some bulk operations, such as bulk delete and
|
||||
auto-extract archive files, perform multiple
|
||||
sub-operations. Some sub-operations might succeed while
|
||||
others fail. The bulk operation returns a response body
|
||||
that contains details that indicate which sub-operations
|
||||
have succeeded and failed.</para>
|
||||
<para>You can set the <literal>Accept</literal> request header
|
||||
to define the response format.</para>
|
||||
<para>The response body contains the following
|
||||
information:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The number of files actually deleted or created,
|
||||
depending on context.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The number of not found objects. For bulk delete
|
||||
only.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Errors. A list of object names and associated
|
||||
error statuses for the objects that failed to
|
||||
create or delete. The format depends on the value
|
||||
you set in the <literal>Accept</literal>
|
||||
header.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The following auto-extract archive files example shows a
|
||||
<literal>text/plain</literal> response body where no
|
||||
failures occurred:</para>
|
||||
<screen><computeroutput>Number Files Created: 10
|
||||
Errors:</computeroutput></screen>
|
||||
<para>The following auto-extract archive files example shows a
|
||||
<literal>text/plain</literal> response where some
|
||||
failures occurred. In this example, the Object Storage
|
||||
system is configured to reject certain character strings
|
||||
so that the <errorcode>400</errorcode>
|
||||
<errortext>Bad Request</errortext> error occurs for any
|
||||
objects that use the restricted strings.</para>
|
||||
<screen><computeroutput>Number Files Created: 8
|
||||
Errors:
|
||||
/v1/12345678912345/mycontainer/home/xx%3Cyy, 400 Bad Request
|
||||
/v1/12345678912345/mycontainer/../image.gif, 400 Bad Request</computeroutput></screen>
|
||||
<para>The following example shows the failure response in
|
||||
<literal>application/json</literal> format. This
|
||||
example output has been reformatted with whitespace to
|
||||
make it easier to read. The actual response has no such
|
||||
whitespace.</para>
|
||||
<programlisting language="json">{
|
||||
"Number Files Created":1,
|
||||
"Errors":[
|
||||
[
|
||||
"/v1/12345678912345/mycontainer/home/xx%3Cyy",
|
||||
"400 Bad Request"
|
||||
],
|
||||
[
|
||||
"/v1/12345678912345/mycontainer/../image.gif",
|
||||
"400 Bad Request"
|
||||
]
|
||||
]
|
||||
}</programlisting>
|
||||
<para>The following bulk delete example response is in
|
||||
<literal>application/xml</literal> format. In this
|
||||
example, the <literal>mycontainer</literal> container is
|
||||
not empty, so it cannot be deleted.</para>
|
||||
<programlisting language="xml"><xi:include parse="text" href="samples/bulk-delete-response.xml"/></programlisting>
|
||||
</section>
|
||||
</section>
|
||||
@ -0,0 +1,20 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section 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="file-compression">
|
||||
<title>Use Content-Encoding metadata</title>
|
||||
<para>When you create an object or update its metadata, you can
|
||||
optionally set the <literal>Content-Encoding</literal>
|
||||
metadata. This metadata enables you to indicate that the
|
||||
object content is compressed without losing the identity of
|
||||
the underlying media type (<literal>Content-Type</literal>) of
|
||||
the file, such as a video.</para>
|
||||
<example>
|
||||
<title>Content-Encoding header request: HTTP</title>
|
||||
<para>This example assigns an attachment type to the
|
||||
<literal>Content-Encoding</literal> header that
|
||||
indicates how the file is downloaded:</para>
|
||||
<programlisting><xi:include href="samples/content-encoding-header-req.txt" parse="text"/></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
@ -0,0 +1,51 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
]>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
||||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||||
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
|
||||
xml:id="container-quotas">
|
||||
<title>Container quotas</title>
|
||||
<para>You can set quotas on the size and number of objects stored
|
||||
in a container by setting the following metadata:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>X-Container-Meta-Quota-Bytes</literal>. The
|
||||
size, in bytes, of objects that can be stored in a
|
||||
container.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>X-Container-Meta-Quota-Count</literal>. The
|
||||
number of objects that can be stored in a container.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>When you exceed a container quota, subsequent requests to
|
||||
create objects fail with a <errorcode>413</errorcode>
|
||||
<errortext>Request Entity Too Large</errortext> error.</para>
|
||||
<para>The Object Storage system uses an <emphasis role="italic"
|
||||
>eventual consistency</emphasis> model. When you create a
|
||||
new object, the container size and object count might not be
|
||||
immediately updated. Consequently, you might be allowed to
|
||||
create objects even though you have actually exceeded the
|
||||
quota.</para>
|
||||
<para>At some later time, the system updates the container size
|
||||
and object count to the actual values. At this time,
|
||||
subsequent requests fails. In addition, if you are currently
|
||||
under the <literal>X-Container-Meta-Quota-Bytes</literal>
|
||||
limit and a request uses chunked transfer encoding, the system
|
||||
cannot know if the request will exceed the quota so the system
|
||||
allows the request. However, once the quota is exceeded, any
|
||||
subsequent uploads that use chunked transfer encoding
|
||||
fail.</para>
|
||||
</section>
|
||||
@ -0,0 +1,104 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
]>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
||||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||||
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
|
||||
xml:id="container-sync">
|
||||
<?dbhtml stop-chunking?>
|
||||
<title>Container synchronization</title>
|
||||
<para>To discover whether your Object Storage system supports
|
||||
container synchronization, see <xref linkend="discoverability"
|
||||
/>. Alternatively, check with your service provider.</para>
|
||||
<para>Container synchronization enables you to synchronize the
|
||||
contents of a source container with a destination container.
|
||||
After you set up container synchronization, the system
|
||||
automatically copies objects from the source container to the
|
||||
destination container. Also, the system deletes objects in the
|
||||
destination container that were deleted in the source
|
||||
container.</para>
|
||||
<para>The system copies objects in a way that object metadata is
|
||||
retained, such as <literal>Last-Modified</literal> and any
|
||||
custom metadata you might have set for the object.</para>
|
||||
<para>You can configure the source and destination containers, as
|
||||
follows:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The source container can be on a different or the
|
||||
same Object Storage system that the destination
|
||||
container is on.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The destination container can be a source container
|
||||
for synchronization for another destination container.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The destination container can be the original source
|
||||
container: both containers synchronize with each
|
||||
other. Any object that you add to or delete from a
|
||||
container is automatically copied to or deleted from
|
||||
the other container.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The Object Storage system performs the synchronization in
|
||||
the background, and makes no guarantees about performance or
|
||||
timeliness.</para>
|
||||
<para>Some Object Storage features, such as large object creation,
|
||||
might require the use of several containers. Container
|
||||
synchronization handles each container separately; if your
|
||||
object segments are located in a different container, they are
|
||||
not transferred unless you also set up container
|
||||
synchronization on that container. However, even if both the
|
||||
manifest and segment containers are synchronized, there is no
|
||||
guarantee that the manifest is transferred before the segment
|
||||
objects. An attempt to download the large object from the
|
||||
destination container might fail, be incomplete, or have
|
||||
jumbled content. Object versioning is not supported.</para>
|
||||
<para>To configure a <emphasis role="italic">source</emphasis>
|
||||
container for synchronization, set the following metadata
|
||||
headers:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>X-Container-Sync-To</literal>. Set this
|
||||
metadata header to the following value:</para>
|
||||
<programlisting>//<replaceable>REALM</replaceable>/<replaceable>SYSTEM</replaceable>/<replaceable>DESTINATION_ACCOUNT</replaceable>/<replaceable>DESTINATION_CONTAINER_NAME</replaceable></programlisting>
|
||||
<para>Your service provider can give you the appropriate
|
||||
values for
|
||||
<literal><replaceable>REALM</replaceable></literal>
|
||||
and
|
||||
<literal><replaceable>SYSTEM</replaceable></literal>.
|
||||
The objects are sent to the
|
||||
<literal><replaceable>DESTINATION_ACCOUNT</replaceable>/<replaceable>DESTINATION_CONTAINER_NAME</replaceable></literal>
|
||||
container. These names can be different from the
|
||||
source account and container names.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>X-Container-Sync-Key</literal>. Set this
|
||||
metadata header to an arbitrary string value. This
|
||||
value serves as a shared secret. Secure this value
|
||||
just as you would a password.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>To configure a <emphasis role="italic"
|
||||
>destination</emphasis> container to receive objects, set
|
||||
the <literal>X-Container-Sync-Key</literal> metadata header to
|
||||
the <literal>X-Container-Sync-Key</literal> value in the
|
||||
source container.</para>
|
||||
<note>
|
||||
<para>To configure a destination container as the source
|
||||
container for another destination container, set the
|
||||
<literal>X-Container-Sync-To</literal> metadata header
|
||||
as you would for a source container.</para>
|
||||
</note>
|
||||
</section>
|
||||
@ -0,0 +1,48 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section 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="cors-headers">
|
||||
<title>Assign CORS headers to requests</title>
|
||||
<para>Cross-Origin Resource Sharing (CORS) is a specification that
|
||||
defines how browsers and servers communicate across origins by
|
||||
using HTTP headers, such as those assigned by Object Storage
|
||||
API requests. The Object Storage API supports these headers.
|
||||
For more information, see <link
|
||||
xlink:href="http://www.w3.org/TR/access-control/"
|
||||
>www.w3.org/TR/access-control/</link>.</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Access-Control-Allow-Credentials</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Access-Control-Allow-Methods</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Access-Control-Allow-Origin</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Access-Control-Expose-Headers</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Access-Control-Max-Age</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Access-Control-Request-Headers</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Access-Control-Request-Method</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Origin</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>You can assign these headers to only objects.</para>
|
||||
<example>
|
||||
<title>Assign CORS header request: HTTP</title>
|
||||
<para>This example assigns the file origin to the
|
||||
<literal>Origin</literal> header, which ensures that
|
||||
the file originated from a reputable source:</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/object-assign-cors-header-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</section>
|
||||
@ -0,0 +1,369 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
<!ENTITY nbsp " ">
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
]>
|
||||
<section 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="large-object-creation">
|
||||
<title>Large objects</title>
|
||||
<para>By default, the content of an object cannot be greater than
|
||||
5 GB. However, you can use segment objects and manifest
|
||||
objects to store more content.</para>
|
||||
<section xml:id="segment-objects">
|
||||
<title>Segment objects</title>
|
||||
<para>You can divide your content into segments, and upload
|
||||
each segment into its own segment object. Segment objects
|
||||
do not have any special features. You create, update,
|
||||
download, and delete segment objects just as you would
|
||||
normal objects.</para>
|
||||
</section>
|
||||
<section xml:id="manifest-objects">
|
||||
<title>Manifest objects</title>
|
||||
<para>A manifest object points to segment objects. When you
|
||||
download a manifest object, Object Storage concatenates
|
||||
the contents of the segment objects and returns this in
|
||||
the response body of the request.</para>
|
||||
<para>This behavior extends to the response headers returned
|
||||
by &GET; and &HEAD; requests. The
|
||||
<literal>Content-Length</literal> response header
|
||||
value is the total size of all segment objects. Object
|
||||
Storage calculates the <literal>ETag</literal> response
|
||||
header value by taking the <literal>ETag</literal> value
|
||||
of each segment, concatenating them together, and
|
||||
returning the MD5 checksum of the result.</para>
|
||||
<note>
|
||||
<para>If you make a © request by using a manifest
|
||||
object as the source, the new object is a normal, and
|
||||
not a segment, object. If the total size of the source
|
||||
segment objects exceeds 5 GB, the © request
|
||||
fails. However, you can make a duplicate of the
|
||||
manifest object and this new object can be larger than
|
||||
5 GB.</para>
|
||||
</note>
|
||||
<para>The manifest object types are:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">Static large
|
||||
objects</emphasis>. The manifest object
|
||||
content is an ordered list of the names of the
|
||||
segment objects in JSON format.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">Dynamic large
|
||||
objects</emphasis>. The manifest object has no
|
||||
content.</para>
|
||||
<para>However, it has
|
||||
<literal>X-Object-Manifest</literal> metadata
|
||||
header. The value of this header is
|
||||
<literal><container>/<prefix></literal>,
|
||||
where <literal><container></literal> is the
|
||||
name of the container where the segment objects
|
||||
are stored, and <literal><prefix></literal> is
|
||||
a string that all segment objects have in
|
||||
common.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>While both types of manifest objects have similar
|
||||
behavior, the following table describes their
|
||||
differences:</para>
|
||||
<table rules="all">
|
||||
<caption>Static and dynamic large objects</caption>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Object type</th>
|
||||
<th>End-to-end integrity</th>
|
||||
<th>Upload order</th>
|
||||
<th>Removal or addition of segment objects</th>
|
||||
<th>Segment object size and number</th>
|
||||
<th>Segment object container name</th>
|
||||
<th>Manifest Object Metadata</th>
|
||||
<th>Making a copy of the manifest object</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><para>Static large object</para></td>
|
||||
<td><para>Assured. The list of segments includes
|
||||
the MD5 checksum (<literal>ETag</literal>)
|
||||
of each segment. You cannot upload the
|
||||
manifest object if the
|
||||
<literal>ETag</literal> in the list
|
||||
differs from the segment object already
|
||||
uploaded. If a segment is somehow lost, an
|
||||
attempt to download the manifest object
|
||||
results in an error.</para></td>
|
||||
<td><para>The segment objects must be uploaded
|
||||
before the manifest object.</para></td>
|
||||
<td><para>You cannot add or remove segment objects
|
||||
from the manifest. However, you can create
|
||||
a completely new manifest object of the
|
||||
same name with a different manifest
|
||||
list.</para></td>
|
||||
<td><para>Segment objects must be at least 1 MB in
|
||||
size (by default). The final segment
|
||||
object can be any size. At most 1000
|
||||
segments are supported (by
|
||||
default).</para></td>
|
||||
<td><para>The manifest list includes the container
|
||||
name of each object. Segment objects can
|
||||
be in different containers.</para></td>
|
||||
<td><para>The object has
|
||||
<literal>X-Static-Large-Object</literal>
|
||||
set to <literal>true</literal>. You do not
|
||||
set this metadata directly. Instead the
|
||||
system sets it when you &PUT; a static
|
||||
manifest object.</para></td>
|
||||
<td><para/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><para>Dynamic large object</para></td>
|
||||
<td><para>Not guaranteed. The eventual consistency
|
||||
model means that although you have
|
||||
uploaded a segment object, it might not
|
||||
appear in the container listing until
|
||||
later. If you download the manifest before
|
||||
it appears in the container, it does not
|
||||
form part of the content returned in
|
||||
response to a &GET; request.</para></td>
|
||||
<td><para>You can upload manifest and segment
|
||||
objects in any order. You are recommended
|
||||
to upload the manifest object after the
|
||||
segments in case a premature download of
|
||||
the manifest occurs. However, this is not
|
||||
enforced.</para></td>
|
||||
<td><para>You can upload new segment objects or
|
||||
remove existing segments. The names must
|
||||
simply match the
|
||||
<literal><prefix></literal>
|
||||
supplied in
|
||||
<literal>X-Object-Manifest</literal>.</para></td>
|
||||
<td><para>Segment objects can be of any
|
||||
size.</para></td>
|
||||
<td><para>All segment objects must be in the same
|
||||
container</para></td>
|
||||
<td><para>The <literal>X-Object-Manifest</literal>
|
||||
value is the
|
||||
<literal><container>/<prefix></literal>
|
||||
indicating where the segment objects are
|
||||
located. You supply this request header in
|
||||
the &PUT; operation</para></td>
|
||||
<td><para>The © operation does not create a
|
||||
manifest object. To duplicate a manifest
|
||||
object, use the &GET; operation to read
|
||||
the value of
|
||||
<literal>X-Object-Manifest</literal>
|
||||
and use this value in the
|
||||
<literal>X-Object-Manifest</literal>
|
||||
request header in a &PUT; operation. This
|
||||
creates a new manifest object that shares
|
||||
the same set of segment objects as the
|
||||
original manifest object.</para></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<section xml:id="dynamic-large-object-creation">
|
||||
<title>Dynamic large objects</title>
|
||||
<para>You must segment objects that are larger than 5 GB
|
||||
before you can upload them. You then upload the
|
||||
segment objects like you would any other object and
|
||||
create a dynamic large manifest object. The manifest
|
||||
object tells Object Storage how to find the segment
|
||||
objects that comprise the large object. The segments
|
||||
remain individually addressable, but retrieving the
|
||||
manifest object streams all the segments concatenated.
|
||||
There is no limit to the number of segments that can
|
||||
be a part of a single large object.</para>
|
||||
<para>To ensure the download works correctly, you must
|
||||
upload all the object segments to the same container
|
||||
and ensure that each object name is prefixed in such a
|
||||
way that it sorts in the order in which it should be
|
||||
concatenated. You also create and upload a manifest
|
||||
file. The manifest file is a zero-byte file with the
|
||||
extra <literal>X-Object-Manifest</literal>
|
||||
<code><container>/<prefix></code> header,
|
||||
where <code><container></code> is the container
|
||||
the object segments are in and
|
||||
<code><prefix></code> is the common prefix
|
||||
for all the segments. You must UTF-8-encode and then
|
||||
URL-encode the container and common prefix in the
|
||||
<literal>X-Object-Manifest</literal>
|
||||
header.</para>
|
||||
<para>It is best to upload all the segments first and then
|
||||
create or update the manifest. With this method, the
|
||||
full object is not available for downloading until the
|
||||
upload is complete. Also, you can upload a new set of
|
||||
segments to a second location and then update the
|
||||
manifest to point to this new location. During the
|
||||
upload of the new segments, the original manifest is
|
||||
still available to download the first set of
|
||||
segments.</para>
|
||||
<example>
|
||||
<title>Upload segment of large object request:
|
||||
HTTP</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/large-object-upload-segment-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>Upload segment of large object response:
|
||||
HTTP</title>
|
||||
<literallayout class="monospaced">s</literallayout>
|
||||
</example>
|
||||
<para>No response body is returned. A status code of
|
||||
<returnvalue>2<replaceable>nn</replaceable></returnvalue>
|
||||
(between 200 and 299, inclusive) indicates a
|
||||
successful write; status <errorcode>411</errorcode>
|
||||
<errortext>Length Required</errortext> denotes a
|
||||
missing <literal>Content-Length</literal> or
|
||||
<literal>Content-Type</literal> header in the request.
|
||||
If the MD5 checksum of the data written to the storage
|
||||
system does NOT match the (optionally) supplied ETag
|
||||
value, a <errorcode>422</errorcode>
|
||||
<errortext>Unprocessable Entity</errortext> response
|
||||
is returned.</para>
|
||||
<para>You can continue uploading segments like this
|
||||
example shows, prior to uploading the manifest.</para>
|
||||
<example>
|
||||
<title>Upload next segment of large object request:
|
||||
HTTP</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/large-object-upload-next-segment-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>Upload next segment of large object response:
|
||||
HTTP</title>
|
||||
<literallayout class="monospaced">w</literallayout>
|
||||
</example>
|
||||
<para>Next, upload the manifest you created that indicates
|
||||
the container the object segments reside within. Note
|
||||
that uploading additional segments after the manifest
|
||||
is created causes the concatenated object to be that
|
||||
much larger but you do not need to recreate the
|
||||
manifest file for subsequent additional
|
||||
segments.</para>
|
||||
<example>
|
||||
<title>Upload manifest request: HTTP</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/upload-manifest-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>Upload manifest response: HTTP</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/upload-manifest-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>The response's <literal>Content-Type</literal> for a
|
||||
&GET; or &HEAD; on the manifest is the same as the
|
||||
<literal>Content-Type</literal> set during the
|
||||
&PUT; request that created the manifest. You can
|
||||
easily change the <literal>Content-Type</literal> by
|
||||
reissuing the &PUT; request.</para>
|
||||
</section>
|
||||
<section xml:id="static-large-objects">
|
||||
<title>Static large objects</title>
|
||||
<procedure>
|
||||
<title>To create a static large object</title>
|
||||
<step>
|
||||
<para>Divide your content into pieces and create
|
||||
(upload) a segment object to contain each
|
||||
piece. You must record the <literal>ETag</literal>
|
||||
response header returned by the&PUT;
|
||||
operation. Alternatively, you can calculate
|
||||
the MD5 checksum of the segment prior to
|
||||
uploading and include this in the
|
||||
<literal>ETag</literal> request header. This
|
||||
ensures that the upload cannot corrupt your
|
||||
data.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>List the name of each segment object along
|
||||
with its size and MD5 checksum in order.
|
||||
Create a manifest object. You indicate that
|
||||
this is a manifest object by including the
|
||||
<parameter>?multipart-manifest=put</parameter> query
|
||||
string at the end of the manifest object
|
||||
name.</para>
|
||||
</step>
|
||||
</procedure>
|
||||
<para>The body of the &PUT; request on the manifest object
|
||||
comprises a json list, where each element contains the
|
||||
following attributes:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><code>path</code>. The container and object
|
||||
name in this format:
|
||||
<code><container-name>/<object-name></code></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><code>etag</code>. The MD5 checksum of the
|
||||
content of the segment object. This value must
|
||||
match the <literal>ETag</literal> of that
|
||||
object.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><code>size_bytes</code>. The size of the
|
||||
segment object. This value must match the
|
||||
<literal>Content-Length</literal> of that
|
||||
object.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<example>
|
||||
<title>Static large object manifest list</title>
|
||||
<para>This example shows three segment objects. You
|
||||
can use several containers and the object names do
|
||||
not have to conform to a specific pattern, in
|
||||
contrast to dynamic large objects.</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/slo-manifest-example.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>The <literal>Content-Length</literal> request header must
|
||||
contain the length of the json content. Not the length
|
||||
of the segment objects. However, after the &PUT;
|
||||
operation completes, the <literal>Content-Length</literal>
|
||||
metadata is set to the total length of all the object
|
||||
segments. A similar situation applies to the
|
||||
<literal>ETag</literal>. If used in the &PUT; operation,
|
||||
it must contain the MD5 checksum of the json content.
|
||||
The <literal>ETag</literal> metadata value is then set to be
|
||||
the MD5 checksum of the concatenated <literal>ETag</literal>
|
||||
values of the object segments. You can also set the
|
||||
<literal>Content-Type</literal> request header and
|
||||
custom object metadata.</para>
|
||||
<para>When the &PUT; operation sees the
|
||||
<parameter>?multipart-manifest=put</parameter>
|
||||
query parameter, it reads the request body and verifies
|
||||
that each segment object exists and that the sizes and
|
||||
ETags match. If there is a mismatch, the
|
||||
&PUT;operation fails.</para>
|
||||
<para>If everything matches, the manifest object is
|
||||
created. The <literal>X-Static-Large-Object</literal>
|
||||
metadata is set to <literal>true</literal> indicating
|
||||
that this is a static object manifest.</para>
|
||||
<para>Normally when you perform a &GET; operation on the
|
||||
manifest object, the response body contains the
|
||||
concatenated content of the segment objects. To
|
||||
download the manifest list, use the
|
||||
<parameter>?multipart-manifest=get</parameter> query parameter.
|
||||
The resulting list is not formatted the same as the
|
||||
manifest you originally used in the &PUT;
|
||||
operation.</para>
|
||||
<para>If you use the &DELETE; operation on a manifest
|
||||
object, the manifest object is deleted. The segment
|
||||
objects are not affected. However, if you add the
|
||||
<parameter>?multipart-manifest=delete</parameter> query parameter,
|
||||
the segment objects are deleted and if all are
|
||||
successfully deleted, the manifest object is also
|
||||
deleted.</para>
|
||||
<para>To change the manifest, use a &PUT; operation with
|
||||
the <parameter>?multipart-manifest=put</parameter>
|
||||
query parameter. This request creates a
|
||||
new manifest object. You can
|
||||
also update the object metadata in the usual
|
||||
way.</para>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
@ -1,56 +1,30 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<section 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="Create_Static_Website-dle4000">
|
||||
<title>Create Static Website</title>
|
||||
<para>You can use your swift account to create a static website.
|
||||
This mode is normally only active for anonymous requests. To
|
||||
use it with authenticated requests, set the header
|
||||
<code>X-Web-Mode</code> to <code>TRUE</code> on the
|
||||
request. The <code>staticweb</code> filter should be added to
|
||||
the pipeline in your <code>/etc/swift/proxy-server.conf</code>
|
||||
file just after any auth middleware. Beneath the pipeline, the
|
||||
<code>staticweb</code> middleware configuration must be
|
||||
added. For example:
|
||||
<literallayout class="monospaced"><xi:include href="samples/proxy-server-excerpt.conf" parse="text"/></literallayout>
|
||||
Your publicly readable containers will be checked for two
|
||||
headers, <code>X-Container-Meta-Web-Index</code> and
|
||||
<code>X-Container-Meta-Web-Error</code>. (The latter
|
||||
xml:id="static-website">
|
||||
<title>Create static website</title>
|
||||
<para>To discover whether your Object Storage system supports
|
||||
this feature, see <xref linkend="discoverability"
|
||||
/>. Alternatively, check with your service provider.</para>
|
||||
<para>You can use your Object Storage account to create a static
|
||||
website. This mode is normally only active for anonymous
|
||||
requests, which provide no authentication token. To use it
|
||||
with authenticated requests, set the header
|
||||
<literal>X-Web-Mode</literal> to <literal>TRUE</literal>
|
||||
on the request. To determine whether the static website
|
||||
feature is enabled, contact your service provider.</para>
|
||||
<para>For example:</para>
|
||||
<programlisting language="ini"><xi:include href="samples/proxy-server-excerpt.conf" parse="text"/></programlisting>
|
||||
<para>Your publicly readable containers are checked for two
|
||||
headers, <literal>X-Container-Meta-Web-Index</literal> and
|
||||
<literal>X-Container-Meta-Web-Error</literal>. (The latter
|
||||
header is discussed below, under <link
|
||||
linkend="Set_Error_Pages_for_Static_Website-dle4005">Set
|
||||
Error Pages for Static Website</link>.) With
|
||||
<code>X-Container-Meta-Web-Index</code>, you determine the
|
||||
index file (or default page served, such as
|
||||
<code>index.html</code>) displays your website. When
|
||||
<literal>X-Container-Meta-Web-Index</literal>, you
|
||||
determine the index file (or default page served, such as
|
||||
<literal>index.html</literal>) displays your website. When
|
||||
someone initially enters your site, they don't have to specify
|
||||
the index file; index.html file displays automatically. If you
|
||||
create sub-directories for your site by creating
|
||||
@ -60,39 +34,41 @@ format="SVG" scale="60"/>
|
||||
visits to the sub-directory return a 404 error.</para>
|
||||
<para>You also have the option of displaying a list of files in
|
||||
your pseudo-directory instead of a web page. You do this by
|
||||
setting the <code>X-Container-Meta-Web-Listings</code> header
|
||||
to <code>TRUE</code>. You may add style to your file listing
|
||||
by setting <code>X-Container-Meta-Web-Listings-CSS:</code> to
|
||||
a style sheet (for example, <code>lists.css</code>).</para>
|
||||
setting the <literal>X-Container-Meta-Web-Listings</literal>
|
||||
header to <literal>TRUE</literal>. You may add style to your
|
||||
file listing by setting
|
||||
<literal>X-Container-Meta-Web-Listings-CSS:</literal> to a
|
||||
style sheet (for example,
|
||||
<literal>lists.css</literal>).</para>
|
||||
<section xml:id="Examples_for_static_web-dle4025">
|
||||
<title>Static Web Middleware through swift</title>
|
||||
<example>
|
||||
<title>Make Container Publicly Readable</title>
|
||||
<para>Make the container publicly readable. Once the
|
||||
container is publicly readable, you may access your
|
||||
objects directly, but you will need to set the index
|
||||
file to browse the main site URL and its
|
||||
objects directly, but you must set the index file to
|
||||
browse the main site URL and its
|
||||
sub-directories.</para>
|
||||
<literallayout class="monospaced">swift post -r '.r:*' container</literallayout>
|
||||
<screen><prompt>$</prompt> <userinput>swift post -r '.r:*' container</userinput></screen>
|
||||
</example>
|
||||
<example>
|
||||
<title>Set Site Index File</title>
|
||||
<para>Set the index file. In this case,
|
||||
<code>index.html</code> is the default file
|
||||
<literal>index.html</literal> is the default file
|
||||
displayed when the site displays.</para>
|
||||
<literallayout class="monospaced">swift post -m 'web-index:index.html' container</literallayout>
|
||||
<screen><prompt>$</prompt> <userinput>swift post -m 'web-index:index.html' container</userinput></screen>
|
||||
</example>
|
||||
<example>
|
||||
<title>Enable File Listing</title>
|
||||
<para>Turn on file listing. If you do not set the index
|
||||
file, list the objects in the container. Instructions
|
||||
on styling the list with the CSS follow.</para>
|
||||
<literallayout class="monospaced">swift post -m 'web-listings: true' container</literallayout>
|
||||
<screen><prompt>$</prompt> <userinput>swift post -m 'web-listings: true' container</userinput></screen>
|
||||
</example>
|
||||
<example>
|
||||
<title>Enable CSS for File Listing</title>
|
||||
<para>Style the file listing.</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/file-listings-css-set-req.txt" parse="text"/></literallayout>
|
||||
<programlisting language="ini"><xi:include href="samples/file-listings-css-set-req.txt" parse="text"/></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="Set_Error_Pages_for_Static_Website-dle4005">
|
||||
@ -100,24 +76,27 @@ format="SVG" scale="60"/>
|
||||
<para>You can create and set custom error pages for visitors
|
||||
to your website; currently, only 401 (Unauthorized) and
|
||||
404 (Not Found) errors are supported. To do this, set the
|
||||
metadata header, <code>X-Container-Meta-Web-Error</code>.</para>
|
||||
metadata header,
|
||||
<literal>X-Container-Meta-Web-Error</literal>.</para>
|
||||
<para>Error pages are served with the <status> code
|
||||
prepended to the name of the error page you set. For
|
||||
pre-pended to the name of the error page you set. For
|
||||
instance, if you set
|
||||
<code>X-Container-Meta-Web-Error</code> to
|
||||
<code>error.html</code>, 401 errors will display the
|
||||
page <code>401error.html</code>. Similarly, 404 errors
|
||||
will display <code>404error.html</code>. You must have
|
||||
both of these pages created in your container when you set
|
||||
the <code>X-Container-Meta-Web-Error</code> metadata, or
|
||||
your site will display generic error pages.</para>
|
||||
<para>Set the <code>X-Container-Meta-Web-Error</code> metadata
|
||||
once for your entire static website.</para>
|
||||
<literal>X-Container-Meta-Web-Error</literal> to
|
||||
<literal>error.html</literal>, 401 errors will display
|
||||
the page <literal>401error.html</literal>. Similarly, 404
|
||||
errors will display <literal>404error.html</literal>. You
|
||||
must have both of these pages created in your container
|
||||
when you set the
|
||||
<literal>X-Container-Meta-Web-Error</literal>
|
||||
metadata, or your site will display generic error
|
||||
pages.</para>
|
||||
<para>Set the <literal>X-Container-Meta-Web-Error</literal>
|
||||
metadata once for your entire static website.</para>
|
||||
<example>
|
||||
<title>Set Error Pages for Static Website Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/error-page-set-req.txt" parse="text"/></literallayout>
|
||||
<programlisting language="ini"><xi:include href="samples/error-page-set-req.txt" parse="text"/></programlisting>
|
||||
</example>
|
||||
<para>Any 2<varname>xx</varname> response indicates success.
|
||||
</para>
|
||||
<para>Any 2<varname>nn</varname> response indicates success.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
@ -0,0 +1,211 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
<!ENTITY plusmn "±">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="figures/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="figures/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<section 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="curl">
|
||||
<title>cURL commands</title>
|
||||
<para>cURL is a command-line tool that you can use to interact
|
||||
with REST interfaces. cURL lets you to transmit and receive
|
||||
HTTP requests and responses from the command line or a shell
|
||||
script, which enables you to work with the API directly. It is
|
||||
available for Linux distributions, Mac OS X, and Windows. For
|
||||
information about cURL, see <link
|
||||
xlink:href="http://curl.haxx.se/"
|
||||
>http://curl.haxx.se/</link>.</para>
|
||||
<para>To run the cURL request examples shown in this guide, copy
|
||||
each example from the HTML version of this guide directly to
|
||||
the command line or a script.</para>
|
||||
<para>Before you can run these examples, you must set environment
|
||||
variables. See <xref linkend="env-vars"/>.</para>
|
||||
<para>This example cURL command shows account details and lists
|
||||
containers in the account.</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>
|
||||
<para>The response, in JSON format, is:</para>
|
||||
<programlisting language="json">[
|
||||
{
|
||||
"count":0,
|
||||
"bytes":0,
|
||||
"name":"janeausten"
|
||||
},
|
||||
{
|
||||
"count":1,
|
||||
"bytes":14,
|
||||
"name":"marktwain"
|
||||
}
|
||||
]</programlisting>
|
||||
<note>
|
||||
<para>The carriage returns in the cURL request examples are
|
||||
escaped with a backslash (<literal>\</literal>) character.
|
||||
The escape character allows continuation of the command
|
||||
across multiple lines. However, do not include the escape
|
||||
character in the JSON or XML request body within the cURL
|
||||
command.</para>
|
||||
</note>
|
||||
<para>The cURL examples in this guide use the following
|
||||
command-line options:</para>
|
||||
<table xml:id="curl_options" rules="all" width="75%">
|
||||
<caption>cURL command-line options</caption>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<option>-d</option>
|
||||
</td>
|
||||
<td>
|
||||
<para>Sends the specified data in a &POST; request
|
||||
to the HTTP server. Use this option to send a
|
||||
JSON or XML request body to the server.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<option>-H</option>
|
||||
</td>
|
||||
<td>
|
||||
<para>Specifies an extra HTTP header in the
|
||||
request. You can specify any number of extra
|
||||
headers. Precede each header with the
|
||||
<option>-H</option> option.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<option>-i</option>
|
||||
</td>
|
||||
<td>
|
||||
<para>Includes the HTTP response headers in the
|
||||
output.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<option>-s</option>
|
||||
</td>
|
||||
<td>
|
||||
<para>Silent or quiet mode. Does not show progress
|
||||
or error messages. Makes cURL mute.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<option>-T</option>
|
||||
</td>
|
||||
<td>
|
||||
<para>Transfers the specified local file to the
|
||||
remote URL.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<option>-X</option>
|
||||
</td>
|
||||
<td>
|
||||
<para>Specifies the request method to use when
|
||||
communicating with the HTTP server. The
|
||||
specified request is used instead of the
|
||||
default method, which is &GET;.</para>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<note xml:id="json_tool">
|
||||
<title>json.tool</title>
|
||||
<para>For commands that return a response, you can append the
|
||||
following code to the command to call the json.tool to
|
||||
pretty-print output:</para>
|
||||
<programlisting language="bash" role="gutter: false">| python -m json.tool</programlisting>
|
||||
<para>To use the <filename>json.tool</filename>, import the
|
||||
<literal>json</literal> module. For information about
|
||||
the <filename>json.tool</filename>, see <link
|
||||
xlink:href="http://docs.python.org/2/library/json.html"
|
||||
>json — JSON encoder and decoder</link>.</para>
|
||||
<para>If you run a Python version older than 2.6, import the
|
||||
<literal>simplejson</literal> module and use the
|
||||
<filename>simplejson.tool</filename>. For information
|
||||
about the <filename>simple.json</filename> tool, see <link
|
||||
xlink:href="http://simplejson.googlecode.com/svn/tags/simplejson-2.0.9/docs/index.html"
|
||||
>simplejson — JSON encoder and decoder</link>.</para>
|
||||
<para>If you do not want to pretty-print JSON output, omit
|
||||
this code.</para>
|
||||
</note>
|
||||
<section xml:id="curl_summary_xml">
|
||||
<title>Example of an XML response</title>
|
||||
<para>To request an XML response, append the
|
||||
<literal>format=xml</literal> query parameter to the
|
||||
request.</para>
|
||||
<para>This example cURL command shows account information and
|
||||
list containers in the account, and asks for the response
|
||||
in XML:</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"><?xml version="1.0" encoding="UTF-8"?>
|
||||
<account name="my_account">
|
||||
<container>
|
||||
<name>janeausten</name>
|
||||
<count>0</count>
|
||||
<bytes>0</bytes>
|
||||
</container>
|
||||
<container>
|
||||
<name>marktwain</name>
|
||||
<count>1</count>
|
||||
<bytes>14</bytes>
|
||||
</container>
|
||||
</account</programlisting>
|
||||
</section>
|
||||
</section>
|
||||
@ -0,0 +1,66 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
||||
]>
|
||||
<section 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="discoverability">
|
||||
<title>Discoverability</title>
|
||||
<para>Your Object Storage system might not enable all features
|
||||
that this document describes. These features are:</para>
|
||||
<itemizedlist role="compact">
|
||||
<listitem>
|
||||
<para><xref linkend="large-object-creation"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="expire-objects"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="archive-auto-extract"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="bulk-delete"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="container-sync"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="container-quotas"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="tempurl"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="form-post"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="static-website"/></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>To discover which features are enabled in your Object
|
||||
Storage system, use the <literal>/info</literal> request.
|
||||
However, your service provider might have disabled the
|
||||
<literal>/info</literal> request, or you might be using an
|
||||
older version that does not support the
|
||||
<literal>/info</literal> request.</para>
|
||||
<para>To use the <literal>/info</literal> request, send a &GET;
|
||||
request using the <literal>/info</literal> path to the Object
|
||||
Store endpoint as shown in this example:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl https://storage.clouddrive.com/info</userinput></screen>
|
||||
<para>This example shows a truncated response body:</para>
|
||||
<programlisting language="json">{
|
||||
"swift":{
|
||||
"version":"1.11.0"
|
||||
},
|
||||
"staticweb":{
|
||||
|
||||
},
|
||||
"tempurl":{
|
||||
|
||||
}
|
||||
}</programlisting>
|
||||
<para>This output shows that the Object Storage system has enabled
|
||||
the static website and temporary URL features.</para>
|
||||
</section>
|
||||
@ -29,7 +29,7 @@ format="SVG" scale="60"/>
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="doc_history">
|
||||
<title>Document Change History</title>
|
||||
<title>Document change history</title>
|
||||
<para>This version of the document replaces and obsoletes
|
||||
all previous versions. The following table describes the latest changes:</para>
|
||||
<?rax revhistory?>
|
||||
|
||||
38
openstack-object-storage-dev/section_object-api-env-vars.xml
Normal file
38
openstack-object-storage-dev/section_object-api-env-vars.xml
Normal file
@ -0,0 +1,38 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section 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="env-vars">
|
||||
<title>Environment variables required to run examples</title>
|
||||
<para>To run the cURL command examples for the Object Storage API
|
||||
requests, set these environment variables:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>publicURL</literal>. The public URL that is
|
||||
the HTTP endpoint from where you can access Object
|
||||
Storage. It includes the Object Storage API version
|
||||
number and your account name. For example,
|
||||
<code>https://23.253.72.207/v1/my_account</code>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>token</literal>. The authentication token
|
||||
for Object Storage.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>To obtain these values, run the <command>swift stat
|
||||
-v</command> command.</para>
|
||||
<para>As shown in this example, the public URL appears in the
|
||||
<literal>StorageURL</literal> field, and the token appears
|
||||
in the <literal>Auth Token</literal> field:</para>
|
||||
<programlisting>StorageURL: https://23.253.72.207/v1/my_account
|
||||
Auth Token: {token}
|
||||
Account: my_account
|
||||
Containers: 2
|
||||
Objects: 3
|
||||
Bytes: 47
|
||||
Meta Book: MobyDick
|
||||
X-Timestamp: 1389453423.35964
|
||||
X-Trans-Id: txee55498935404a2caad89-0052dd3b77
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
Accept-Ranges: bytes</programlisting>
|
||||
</section>
|
||||
@ -0,0 +1,61 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||||
]>
|
||||
<section 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="expire-objects">
|
||||
<title>Schedule objects for deletion</title>
|
||||
<para>To discover whether your Object Storage system supports this
|
||||
feature, see <xref linkend="discoverability"/>. Alternatively,
|
||||
check with your service provider.</para>
|
||||
<para>Scheduling an object for deletion is helpful for objects
|
||||
that you do not want to permanently store, such as log files,
|
||||
recurring full backups of a dataset, or documents or images
|
||||
that become outdated at a specified future time.</para>
|
||||
<para>To schedule an object for deletion, include one of these
|
||||
headers with the &PUT; or &POST; request on the object:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>X-Delete-After</literal></para>
|
||||
<para>An integer value. Specifies the number of seconds in
|
||||
the future when you want to delete the object.</para>
|
||||
<para>This header is converted to an
|
||||
<literal>X-Delete-At</literal> header that is set
|
||||
to the sum of the <literal>X-Delete-After</literal>
|
||||
value plus the current time, in seconds.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>X-Delete-At</literal></para>
|
||||
<para>A UNIX Epoch timestamp, in integer form. For
|
||||
example, <literal>1348691905</literal> represents
|
||||
<literal>Wed, 26 Sep 2012 20:38:25 GMT</literal>.
|
||||
Specifies the time when you want the object to expire,
|
||||
not be served, and be deleted completely from the
|
||||
object store.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>Use the &POST; method to assign expiration headers to
|
||||
existing objects that you want expire.</para>
|
||||
<simplesect>
|
||||
<title>Delete object at specified time request: HTTP</title>
|
||||
<para>In the example, the <code>X-Delete-At</code> header is
|
||||
assigned a UNIX Epoch timestamp in integer form for Mon,
|
||||
11 Jun 2012 15:38:25 GMT. Use <link
|
||||
xlink:href="http://www.epochconverter.com/"
|
||||
>http://www.epochconverter.com/</link> for example
|
||||
timestamps and a batch converter.</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/marktwain/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Delete-At: 1390581073" -H "Content-Length: 14" -H "Content-Type: application/octet-stream"</userinput></screen>
|
||||
</simplesect>
|
||||
<simplesect>
|
||||
<title>Delete object after specified interval request:
|
||||
HTTP</title>
|
||||
<para>This example sets the <code>X-Delete-After</code> header
|
||||
to a value in seconds that is equivalent to 10 days. After
|
||||
this time, the object expires.</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/object-delete-after-req.txt" parse="text"/></literallayout>
|
||||
</simplesect>
|
||||
</section>
|
||||
@ -13,6 +13,9 @@
|
||||
xml:id="form-post">
|
||||
<title>Form POST middleware</title>
|
||||
<?dbhtml stop-chunking?>
|
||||
<para>To discover whether your Object Storage system supports
|
||||
this feature, see <xref linkend="discoverability"
|
||||
/>. Alternatively, check with your service provider.</para>
|
||||
<para>You can upload objects directly to the Object Storage system
|
||||
from a browser by using the form &POST; middleware. This
|
||||
middleware uses account secret keys to generate a
|
||||
@ -0,0 +1,58 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
]>
|
||||
<section 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="large-lists">
|
||||
<title>Page through large lists of containers or objects</title>
|
||||
<para>If you have a large number of containers or objects, you can
|
||||
use the <parameter>marker</parameter>,
|
||||
<parameter>limit</parameter>, and
|
||||
<parameter>end_marker</parameter> parameters to control
|
||||
how many items are returned in a list and where the list
|
||||
starts or ends.</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis role="bold"><parameter>marker</parameter>
|
||||
parameter</emphasis>. When you request a list of
|
||||
containers or objects, Object Storage returns a
|
||||
maximum of 10,000 names for each request. To get
|
||||
subsequent names, you must make another request with
|
||||
the <parameter>marker</parameter> parameter. Set the
|
||||
<literal>marker</literal> parameter to the name of
|
||||
the last item returned in the previous list. You must
|
||||
URL-encode the <parameter>marker</parameter> value
|
||||
before you send the HTTP request. Object Storage
|
||||
returns a maximum of 10,000 names again.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis role="bold"><parameter>limit</parameter>
|
||||
parameter</emphasis>. To return fewer than 10,000
|
||||
names, use the <parameter>limit</parameter> parameter.
|
||||
If the number of names returned equals the specified
|
||||
<parameter>limit</parameter> (or 10,000 if you
|
||||
omit the <parameter>limit</parameter> parameter), you
|
||||
can assume there are more names to list. If the number
|
||||
of names in the list is exactly divisible by the
|
||||
<parameter>limit</parameter> value, the last
|
||||
request has no content.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis role="bold"
|
||||
><parameter>end_marker</parameter>
|
||||
parameter</emphasis>. Limits the result set to
|
||||
names that are less than the
|
||||
<parameter>end_marker</parameter> parameter value.
|
||||
You must URL-encode the
|
||||
<parameter>end_marker</parameter> value before you
|
||||
send the HTTP request.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>For examples of how to page through large lists, see <xref
|
||||
linkend="examples"/>.</para>
|
||||
</section>
|
||||
257
openstack-object-storage-dev/section_object-api-overview.xml
Normal file
257
openstack-object-storage-dev/section_object-api-overview.xml
Normal file
@ -0,0 +1,257 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY nbsp " ">
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
||||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||||
]>
|
||||
<section 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="object_storage_api_overview">
|
||||
<title>Object Storage API overview</title>
|
||||
<para>OpenStack Object Storage is an object-based storage system
|
||||
that stores content and metadata as objects. You create,
|
||||
modify, and get objects and metadata by using the Object
|
||||
Storage API, which is implemented as a set of Representational
|
||||
State Transfer (REST) web services.</para>
|
||||
<para>For an introduction to OpenStack Object Storage, see <link
|
||||
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-object-storage.html"
|
||||
>Object Storage</link> in the <citetitle>OpenStack Cloud
|
||||
Administrator Guide</citetitle>.</para>
|
||||
<para>You use the HTTPS (SSL) protocol to interact with Object
|
||||
Storage, and you use standard HTTP calls to perform API
|
||||
operations. You can also use language-specific APIs, which use
|
||||
the RESTful API, that make it easier for you to integrate into
|
||||
your applications.</para>
|
||||
<para>To assert your right to access and change data in an
|
||||
account, you identify yourself to Object Storage by using an
|
||||
authentication token. To get a token, you present your
|
||||
credentials to an authentication service. The authentication
|
||||
service returns a token and the URL for the account. Depending
|
||||
on which authentication service that you use, the URL for the
|
||||
account appears in:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">OpenStack Identity
|
||||
Service</emphasis>. The URL is defined in the
|
||||
service catalog.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">Tempauth</emphasis>. The URL
|
||||
is provided in the <literal>X-Storage-Url</literal>
|
||||
response header.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>In both cases, the URL is the full URL and includes the
|
||||
account resource. For information about authentication, see
|
||||
<xref linkend="authentication"/>.</para>
|
||||
<para>The Object Storage API supports the standard, non-serialized
|
||||
response format, which is the default, and both JSON and XML
|
||||
serialized response formats. See <xref
|
||||
linkend="serialized-response-formats"/>.</para>
|
||||
<para>The Object Storage system organizes data in a hierarchy, as
|
||||
follows:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">Account</emphasis>. Represents
|
||||
the top-level of the hierarchy.</para>
|
||||
<para>Your service provider creates your account and you
|
||||
own all resources in that account. The account defines
|
||||
a namespace for containers. A container might have the
|
||||
same name in two different accounts.</para>
|
||||
<para>In the OpenStack environment,
|
||||
<firstterm>account</firstterm> is synonymous with
|
||||
a project or tenant.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">Container</emphasis>. Defines
|
||||
a namespace for objects. An object with the same name
|
||||
in two different containers represents two different
|
||||
objects. You can create any number of containers
|
||||
within an account.</para>
|
||||
<para>In addition to containing objects, you can also use
|
||||
the container to control access to objects by using an
|
||||
access control list (ACL). You cannot store an ACL
|
||||
with individual objects.</para>
|
||||
<para>In addition, you configure and control many other
|
||||
features, such as object versioning, at the container
|
||||
level. See <xref linkend="set-object-versions"
|
||||
/>.</para>
|
||||
<para>You can bulk-delete up to 10,000 containers in a
|
||||
single request. See <xref linkend="bulk-delete"
|
||||
/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis role="bold">Object</emphasis>. Stores data
|
||||
content, such as documents, images, and so on. You can
|
||||
also store custom metadata with an object.</para>
|
||||
<para>With the Object Storage API, you can:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Store an unlimited number of objects. Each
|
||||
object can be as large as 5 GB, which is the
|
||||
default. You can configure the maximum object
|
||||
size.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Upload and store objects of any size with
|
||||
large object creation. See <xref
|
||||
linkend="large-object-creation"/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Use cross-origin resource sharing to manage
|
||||
object security. See <xref
|
||||
linkend="cors-headers"/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Compress files. See <xref
|
||||
linkend="file-compression"/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Override browser behavior for an object. See
|
||||
<xref linkend="content-disposition"
|
||||
/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Schedule objects for deletion. See <xref
|
||||
linkend="expire-objects"/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Bulk-delete up to 10,000 objects in a single
|
||||
request. See <xref linkend="bulk-delete"
|
||||
/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Auto-extract archive files. See <xref
|
||||
linkend="archive-auto-extract"/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Generate a URL that provides time-limited
|
||||
&GET; access to an object. See <xref
|
||||
linkend="tempurl"/>.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Upload objects directly to the Object
|
||||
Storage system from a browser by using form
|
||||
&POST; middleware. See <xref
|
||||
linkend="form-post"/>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The account, container, and object hierarchy affects the way
|
||||
you interact with the Object Storage API.</para>
|
||||
<para>Specifically, the resource path reflects this structure and
|
||||
has this format:</para>
|
||||
<programlisting>/v1/{account}/{container}/{object}</programlisting>
|
||||
<para>For example, for the <literal>flowers/rose.jpg</literal>
|
||||
object in the <literal>images</literal> container in the
|
||||
<literal>12345678912345</literal> account, the resource
|
||||
path is:</para>
|
||||
<programlisting>/v1/12345678912345/images/flowers/rose.jpg</programlisting>
|
||||
<para>Notice that the object name contains the
|
||||
<literal>/</literal> character. This slash does not
|
||||
indicate that Object Storage has a sub-hierarchy called
|
||||
<literal>flowers</literal> because containers do not store
|
||||
objects in actual sub-folders. However, the inclusion of
|
||||
<literal>/</literal> or a similar convention inside object
|
||||
names enables you to create pseudo-hierarchical folders and
|
||||
directories. See <xref
|
||||
linkend="pseudo-hierarchical-folders-directories"
|
||||
/>.</para>
|
||||
<para>For example, if the endpoint for Object Storage is
|
||||
<literal>objects.mycloud.com</literal>, the returned URL
|
||||
is
|
||||
<literal>https://objects.mycloud.com/v1/12345678912345</literal>.</para>
|
||||
<para>To access a container, append the container name to the
|
||||
resource path.</para>
|
||||
<para>To access an object, append the container and the object
|
||||
name to the path.</para>
|
||||
<para>If you have a large number of containers or objects, you can
|
||||
use query parameters to page through large lists of
|
||||
containers or objects. Use the <parameter>marker</parameter>,
|
||||
<parameter>limit</parameter>, and
|
||||
<parameter>end_marker</parameter> query parameters to
|
||||
control how many items are returned in a list and where the
|
||||
list starts or ends. See <xref linkend="large-lists"/>.</para>
|
||||
<para>Object Storage HTTP requests have the following default
|
||||
constraints. Your service provider might use different default
|
||||
values.</para>
|
||||
<informaltable rules="all">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Item</th>
|
||||
<th>Maximum value</th>
|
||||
<th>Notes</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Number of HTTP headers</td>
|
||||
<td>90</td>
|
||||
<td/>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Length of HTTP headers</td>
|
||||
<td>4096 bytes</td>
|
||||
<td/>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Length per HTTP request line</td>
|
||||
<td>8192 bytes</td>
|
||||
<td/>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Length of HTTP request</td>
|
||||
<td>5 GB</td>
|
||||
<td/>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Length of container names</td>
|
||||
<td>256 bytes</td>
|
||||
<td>Cannot contain the <literal>/</literal>
|
||||
character.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Length of object names</td>
|
||||
<td>1024 bytes</td>
|
||||
<td>By default, there are no character
|
||||
restrictions.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<para>You must UTF-8-encode and then URL-encode container and
|
||||
object names before you call the API binding. If you use an
|
||||
API binding that performs the URL-encoding for you, do not
|
||||
URL-encode the names before you call the API binding.
|
||||
Otherwise, you double-encode these names. Check the length
|
||||
restrictions against the URL-encoded string.</para>
|
||||
<para>These sections describe the operations that you can perform
|
||||
with the Object Storage API:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="storage_account_services"/>. Use to
|
||||
perform account-level tasks.</para>
|
||||
<para>Lists containers for a specified account. Creates,
|
||||
updates, and deletes account metadata. Shows account
|
||||
metadata.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="storage_container_services"/>. Use to
|
||||
perform container-level tasks.</para>
|
||||
<para>Lists objects in a specified container. Creates,
|
||||
shows details for, and deletes containers. Creates,
|
||||
updates, shows, and deletes container metadata.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="storage_object_services"/>. Use to
|
||||
perform object-level tasks.</para>
|
||||
<para>Creates, replaces, shows details for, and deletes
|
||||
objects. Copies objects with another object with a new
|
||||
or different name. Updates object metadata.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
@ -0,0 +1,94 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
]>
|
||||
<section 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="pseudo-hierarchical-folders-directories">
|
||||
<title>Pseudo-hierarchical folders and directories</title>
|
||||
<!-- reworked this section / as path and its elements / are not supported - dsh - 02-16-12 -->
|
||||
<para>Although you cannot nest directories in OpenStack Object
|
||||
Storage, you can simulate a hierarchical structure within a
|
||||
single container by adding forward slash characters
|
||||
(<literal>/</literal>) in the object name. To navigate the
|
||||
pseudo-directory structure, you can use the
|
||||
<code>delimiter</code> query parameter. this examples show
|
||||
you how to use pseudo-hierarchical folders and
|
||||
directories.</para>
|
||||
<note>
|
||||
<para>In this example, the objects reside in a container
|
||||
called <code>backups</code>. Within that container, the
|
||||
objects are organized in a pseudo-directory called
|
||||
<code>photos</code>. Keep in mind that the container
|
||||
name is not displayed in the example, but that it is a
|
||||
part of the object URLs. For instance, the URL of the
|
||||
picture <code>me.jpg</code> is
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg</uri>.</para>
|
||||
</note>
|
||||
<example>
|
||||
<title>List pseudo-hierarchical folders request: HTTP</title>
|
||||
<para>To display a list of all the objects in the storage
|
||||
container, use &GET; without a <code>delimiter</code> or
|
||||
<code>prefix</code>.</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups</literallayout>
|
||||
<para>The system returns status code 2xx (between 200 and 299,
|
||||
inclusive) and the requested list of the objects.</para>
|
||||
<literallayout class="monospaced">photos/animals/cats/persian.jpg
|
||||
photos/animals/cats/siamese.jpg
|
||||
photos/animals/dogs/corgi.jpg
|
||||
photos/animals/dogs/poodle.jpg
|
||||
photos/animals/dogs/terrier.jpg
|
||||
photos/me.jpg
|
||||
photos/plants/fern.jpg
|
||||
photos/plants/rose.jpg</literallayout>
|
||||
<para>
|
||||
<!-- The JIRA ticket / doc-97 subsumed / to this location - dsh - 02-03-12 -->Use
|
||||
the delimiter parameter to limit the displayed results.
|
||||
You can use any character as a delimiter. However, to use
|
||||
<code>delimiter</code> with pseudo-directories, use
|
||||
the parameter slash (<literal>/</literal>).</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups?delimiter=/</literallayout>
|
||||
<para>The system returns status code 2xx (between 200 and 299,
|
||||
inclusive) and the requested matching objects. Because you
|
||||
use the slash, only the pseudo-directory
|
||||
<code>photos/</code> displays. Keep in mind that the
|
||||
returned values from a slash <code>delimiter</code> query
|
||||
are not real objects. They have a content-type of
|
||||
<literal>application/directory</literal> and are in
|
||||
the <literal>subdir</literal> section of json and xml
|
||||
results.</para>
|
||||
<literallayout class="monospaced">photos/</literallayout>
|
||||
<para>Use the <code>prefix</code> and <code>delimiter</code>
|
||||
parameters to view the objects inside a pseudo-directory,
|
||||
including further nested pseudo-directories.</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/&delimiter=/</literallayout>
|
||||
<para>The system returns status code 2xx (between 200 and 299,
|
||||
inclusive) and the objects and pseudo-directories within
|
||||
the top level pseudo-directory.</para>
|
||||
<literallayout class="monospaced">photos/animals/
|
||||
photos/me.jpg
|
||||
photos/plants/</literallayout>
|
||||
<para>You can create an unlimited number of nested
|
||||
pseudo-directories. To navigate through them, use a longer
|
||||
<code>prefix</code> parameter coupled with the
|
||||
<code>delimiter</code> parameter. In this sample
|
||||
output, there is a pseudo-directory called
|
||||
<code>dogs</code> within the pseudo-directory
|
||||
<code>animals</code>. To navigate directly to the
|
||||
files contained within <code>dogs</code>, enter the
|
||||
following command:</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/ </literallayout>
|
||||
<para>The system returns status code <returnvalue>2<replaceable>nn</replaceable></returnvalue> (between 200 and 299,
|
||||
inclusive) and the objects and pseudo-directories within
|
||||
the nested pseudo-directory.</para>
|
||||
<literallayout class="monospaced">photos/animals/dogs/corgi.jpg
|
||||
photos/animals/dogs/poodle.jpg
|
||||
photos/animals/dogs/terrier.jpg</literallayout>
|
||||
</example>
|
||||
</section>
|
||||
@ -0,0 +1,136 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
||||
]>
|
||||
<section 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="serialized-response-formats">
|
||||
<title>Serialized response formats</title>
|
||||
<para>By default, the Object Storage API uses a
|
||||
<literal>text/plain</literal> response format. In
|
||||
addition, both JSON and XML data serialization response
|
||||
formats are supported.</para>
|
||||
<note>
|
||||
<para>To run the cURL command examples, you must export <link
|
||||
xlink:href="run_curl_commands">environment
|
||||
variables</link>.</para>
|
||||
</note>
|
||||
<para>To define the response format, use one of these
|
||||
methods:</para>
|
||||
<informaltable rules="all">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Method</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><para><code>format=<replaceable>format</replaceable></code>
|
||||
query parameter</para></td>
|
||||
<td>
|
||||
<para>Append this parameter to the URL for a &GET;
|
||||
request, where
|
||||
<replaceable>format</replaceable> is
|
||||
<code>json</code> or
|
||||
<code>xml</code>.</para>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><para><literal>Accept</literal> request
|
||||
header</para></td>
|
||||
<td>
|
||||
<para>Include this header in the &GET; request.
|
||||
The valid header values are:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><code>text/plain</code>. Plain text
|
||||
response format. The default.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><code>application/json</code>. JSON
|
||||
data serialization response
|
||||
format.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><code>application/xml</code> or
|
||||
<code>text/xml</code>. XML data
|
||||
serialization response format.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<example>
|
||||
<title>JSON example with format query parameter</title>
|
||||
<para>For example, this request uses the
|
||||
<parameter>format</parameter> query parameter to ask
|
||||
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>
|
||||
<para>Object Storage lists container names with additional
|
||||
information in JSON format:</para>
|
||||
<programlisting language="json">[
|
||||
{
|
||||
"count":0,
|
||||
"bytes":0,
|
||||
"name":"janeausten"
|
||||
},
|
||||
{
|
||||
"count":1,
|
||||
"bytes":14,
|
||||
"name":"marktwain"
|
||||
}
|
||||
]</programlisting>
|
||||
</example>
|
||||
<example>
|
||||
<title>XML example with Accept header</title>
|
||||
<para>This request uses the <literal>Accept</literal> request
|
||||
header to ask for an XML response:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL -X GET -H "X-Auth-Token: $token" -H "Accept: application/xml; charset=utf-8"</userinput></screen>
|
||||
<screen><computeroutput>HTTP/1.1 200 OK
|
||||
Content-Length: 263
|
||||
X-Account-Object-Count: 3
|
||||
X-Account-Meta-Book: MobyDick
|
||||
X-Timestamp: 1389453423.35964
|
||||
X-Account-Bytes-Used: 47
|
||||
X-Account-Container-Count: 2
|
||||
Content-Type: application/xml; charset=utf-8
|
||||
Accept-Ranges: bytes
|
||||
X-Trans-Id: txf0b4c9727c3e491694019-0052e03420
|
||||
Date: Wed, 22 Jan 2014 21:12:00 GMT</computeroutput></screen>
|
||||
<para>Object Storage lists container names with additional
|
||||
information in XML format:</para>
|
||||
<programlisting language="xml"><?xml version="1.0" encoding="UTF-8"?>
|
||||
<account name="AUTH_73f0aa26640f4971864919d0eb0f0880">
|
||||
<container>
|
||||
<name>janeausten</name>
|
||||
<count>2</count>
|
||||
<bytes>33</bytes>
|
||||
</container>
|
||||
<container>
|
||||
<name>marktwain</name>
|
||||
<count>1</count>
|
||||
<bytes>14</bytes>
|
||||
</container>
|
||||
</account></programlisting>
|
||||
<para>The remainder of the examples in this guide use
|
||||
standard, non-serialized responses. However, all &GET;
|
||||
requests that perform list operations accept the
|
||||
<parameter>format</parameter> query parameter or
|
||||
<literal>Accept</literal> request header.</para>
|
||||
</example>
|
||||
</section>
|
||||
@ -1,518 +1,20 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<section 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="storage-container-services">
|
||||
<title>Storage Container Services</title>
|
||||
<para>You can perform the following operations for
|
||||
containers:</para>
|
||||
<informaltable rules="all">
|
||||
<thead>
|
||||
<tr>
|
||||
<td colspan="1">Verb</td>
|
||||
<td colspan="2">URI</td>
|
||||
<td colspan="3">Description</td>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="1">&GET;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter></td>
|
||||
<td colspan="3">Lists objects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&PUT;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter></td>
|
||||
<td colspan="3">Creates a container.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&DELETE;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter></td>
|
||||
<td colspan="3">Deletes a container.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&HEAD;</td>
|
||||
<td colspan="2"
|
||||
>/<parameter>account</parameter>/<parameter>container</parameter></td>
|
||||
<td colspan="3">Gets container metadata.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<variablelist>
|
||||
<title>Optional headers for HEAD and GET</title>
|
||||
<varlistentry>
|
||||
<term><code>X-Newest</code></term>
|
||||
<listitem>
|
||||
<para>Set the optional <code>X-newest</code> header to
|
||||
<code>True</code> in HEAD and GET requests to have
|
||||
Object Storage return the latest version of the container.
|
||||
If set to <code>True</code>, Object Storage queries all
|
||||
replicas to return the most recent one. Without this header,
|
||||
Object Storage responds faster after it finds one valid replica.
|
||||
Because setting this header to <code>True</code> is more
|
||||
expensive for the back end, use it only when it is
|
||||
absolutely needed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>All operations follow this format:</para>
|
||||
<example>
|
||||
<title>Storage Container Services HTTP Request</title>
|
||||
<literallayout class="monospaced">METHOD /v1/<account>/<container> HTTP/1.1 </literallayout>
|
||||
</example>
|
||||
<section xml:id="list-objects">
|
||||
<title>List Objects</title>
|
||||
<para>&GET; operations against a storage container name are
|
||||
performed to retrieve a list of objects stored in the
|
||||
container. Additionally, there are a number of optional
|
||||
query parameters that can be used to refine the list
|
||||
results.</para>
|
||||
<para>A request with no query parameters will return the full
|
||||
list of object names stored in the container, up to 10,000
|
||||
names. Optionally specifying the query parameters will
|
||||
filter the full list and return a subset of
|
||||
objects.</para>
|
||||
<variablelist>
|
||||
<title>Query Parameters</title>
|
||||
<varlistentry>
|
||||
<term><code>limit</code></term>
|
||||
<listitem>
|
||||
<para>For an integer value <inlineequation>
|
||||
<mathphrase><emphasis>n</emphasis></mathphrase>
|
||||
</inlineequation>, limits the number of
|
||||
results to at most <inlineequation>
|
||||
<mathphrase><emphasis>n</emphasis></mathphrase>
|
||||
</inlineequation> values.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>marker</code></term>
|
||||
<listitem>
|
||||
<para>Given a string value <inlineequation>
|
||||
<mathphrase><emphasis>x</emphasis></mathphrase>
|
||||
</inlineequation>, return object names greater
|
||||
in value than the specified marker.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>end_marker</code></term>
|
||||
<listitem>
|
||||
<para>Given a string value <inlineequation>
|
||||
<mathphrase><emphasis>x</emphasis></mathphrase>
|
||||
</inlineequation>, return object names less in
|
||||
value than the specified marker.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>prefix</code></term>
|
||||
<listitem>
|
||||
<para>For a string value <inlineequation>
|
||||
<mathphrase><emphasis>x</emphasis></mathphrase>
|
||||
</inlineequation>, causes the results to be
|
||||
limited to object names beginning with the
|
||||
substring <inlineequation>
|
||||
<mathphrase><emphasis>x</emphasis></mathphrase>
|
||||
</inlineequation>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>format</code></term>
|
||||
<listitem>
|
||||
<para>Specify either <code>json</code> or
|
||||
<code>xml</code> to return the respective
|
||||
serialized response.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>delimiter</code></term>
|
||||
<listitem>
|
||||
<para>For a character <inlineequation>
|
||||
<mathphrase><emphasis>c</emphasis></mathphrase>
|
||||
</inlineequation>, return all the object names
|
||||
nested in the container (without the need for
|
||||
the directory marker objects).</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>path</code></term>
|
||||
<listitem>
|
||||
<para>For a string value<inlineequation>
|
||||
<mathphrase><emphasis>x</emphasis></mathphrase>
|
||||
</inlineequation>, return the object names
|
||||
nested in the pseudo path. Equivalent to
|
||||
setting delimiter to '/' and prefix to the
|
||||
path with a '/' on the end.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<example>
|
||||
<title>List Objects HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/object-list-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>A list of objects is returned in the response body, one
|
||||
object name per line. The response will have a 2xx HTTP status
|
||||
code (between 200 and 299 inclusive). If the container does
|
||||
not exist, or if an incorrect account is specified, then a
|
||||
response with a 404 (Not Found) status code will be
|
||||
returned.</para>
|
||||
<example>
|
||||
<title>List Objects HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/object-list-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<section xml:id="serialized-list-output">
|
||||
<title>Serialized List Output</title>
|
||||
<para>If a <code>format=xml</code> or
|
||||
<code>format=json</code> argument is appended to
|
||||
the storage account URL, the service will serve
|
||||
extended object information serialized in the chosen
|
||||
format. Other than the <code>?format=xml|json</code>
|
||||
parameter, it will return the same status/errors
|
||||
codes. The sample responses below are formatted for
|
||||
readability.</para>
|
||||
<example>
|
||||
<title>Get Objects Details HTTP and JSON
|
||||
Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-json-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>Get Objects Details HTTP and JSON Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-json-resp.txt" parse="text"/></literallayout>
|
||||
<programlisting language="json"><xi:include href="samples/objects-get-details-resp.json" parse="text"/></programlisting>
|
||||
</example>
|
||||
<example>
|
||||
<title>Objects Details Request: XML</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-xml-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>Objects Details Request: XML</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-get-details-http-xml-resp.txt" parse="text"/></literallayout>
|
||||
<programlisting language="xml"><xi:include href="samples/objects-get-details-resp.xml" parse="text"/></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="list-large-number-of-objects">
|
||||
<title>Controlling a Large List of Objects</title>
|
||||
<para>The system returns a maximum of 10,000 object names
|
||||
per request. To retrieve subsequent object names,
|
||||
another request must be made with the 'marker'
|
||||
parameter. The marker indicates where the last list
|
||||
left off and the system returns object names greater
|
||||
than this marker, up to 10,000 again. Note that the
|
||||
‘marker’ value should be URL encoded prior to sending
|
||||
the HTTP request.</para>
|
||||
<para>If 10,000 is larger than desired, a 'limit'
|
||||
parameter may be given.</para>
|
||||
<para>If the number of object names returned equals the
|
||||
limit given (or 10,000 if no limit is given), it can
|
||||
be assumed there are more object names to be listed.
|
||||
If the container name list is exactly divisible by the
|
||||
limit, the last request has no content.</para>
|
||||
<example>
|
||||
<title>List Large Number of Objects</title>
|
||||
<para>For an example, let's use a listing of five
|
||||
object names:</para>
|
||||
<literallayout class="monospaced">gala
|
||||
grannysmith
|
||||
honeycrisp
|
||||
jonagold
|
||||
reddelicious</literallayout>
|
||||
<para>We'll use a limit of two to show how things
|
||||
work:</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-list-req.txt" parse="text"/></literallayout>
|
||||
<para>Because we received two items back, we can
|
||||
assume there are more object names to list. So, we
|
||||
make another request with a marker of the last
|
||||
item returned:</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-list-marker-req.txt" parse="text"/></literallayout>
|
||||
<para>Again we have two items returned; there might be
|
||||
more:</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-list-marker2-req.txt" parse="text"/></literallayout>
|
||||
<para>Now we received less than the limit number of
|
||||
object names, indicating that we have the complete
|
||||
list.</para>
|
||||
<para>By using <code>end_marker</code> we can limit
|
||||
the result set to object names less than the given
|
||||
value.</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/objects-list-end-marker-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="pseudo-hierarchical-folders-directories">
|
||||
<title>Pseudo-Hierarchical Folders and Directories</title>
|
||||
<!-- reworked this section / as path and its elements / are not supported - dsh - 02-16-12 -->
|
||||
<para>Although you cannot nest directories in OpenStack
|
||||
Object Storage, you can simulate a hierarchical
|
||||
structure within a single container by adding forward
|
||||
slash characters (<literal>/</literal>) in the object
|
||||
name. To navigate the pseudo-directory structure, you
|
||||
may use the <code>delimiter</code> query parameter.
|
||||
See the below examples for an illustration.</para>
|
||||
<note>
|
||||
<para>In the example below, the objects reside in a
|
||||
container called <code>backups</code>. Within that
|
||||
container, the objects are organized in a
|
||||
pseudo-directory called <code>photos</code>. Keep
|
||||
in mind that the container name is not displayed
|
||||
in the example, but that it is a part of the
|
||||
object URLs. For instance, the URL of the picture
|
||||
<code>me.jpg</code> is
|
||||
<uri>https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg</uri>.
|
||||
</para>
|
||||
</note>
|
||||
<example>
|
||||
<title>List Pseudo-Hierarchical Folders/Directories
|
||||
Request</title>
|
||||
<para>To display a list of all the objects in the
|
||||
storage container, use &GET; without a
|
||||
<code>delimiter</code> or <code>prefix</code>.</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups</literallayout>
|
||||
<para>The system returns status code 2xx (between 200
|
||||
and 299, inclusive) and the requested list of the
|
||||
objects.</para>
|
||||
<literallayout class="monospaced">photos/animals/cats/persian.jpg
|
||||
photos/animals/cats/siamese.jpg
|
||||
photos/animals/dogs/corgi.jpg
|
||||
photos/animals/dogs/poodle.jpg
|
||||
photos/animals/dogs/terrier.jpg
|
||||
photos/me.jpg
|
||||
photos/plants/fern.jpg
|
||||
photos/plants/rose.jpg</literallayout>
|
||||
<para>
|
||||
<!-- The JIRA ticket / doc-97 subsumed / to this location - dsh - 02-03-12 -->Use
|
||||
the delimiter parameter to limit the displayed
|
||||
results. Any character may be used as a delimiter.
|
||||
However, to use <code>delimiter</code> with
|
||||
pseudo-directories, use the parameter slash
|
||||
(<literal>/</literal>).</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups?delimiter=/</literallayout>
|
||||
<para>The system returns status code 2xx (between 200
|
||||
and 299, inclusive) and the requested matching
|
||||
objects. Because we use the slash, only the
|
||||
pseudo-directory <code>photos/</code> displays. Keep
|
||||
in mind that the returned values from a slash
|
||||
<code>delimiter</code> query are not real objects.
|
||||
They have a content-type of
|
||||
<literal>application/directory</literal> and are in
|
||||
the <literal>subdir</literal> section of json and xml
|
||||
results.</para>
|
||||
<literallayout class="monospaced">photos/</literallayout>
|
||||
<para>Use the <code>prefix</code> parameter with the
|
||||
<code>delimiter</code> parameter to view the
|
||||
objects inside a pseudo-directory, including
|
||||
further nested pseudo-directories.</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/&delimiter=/</literallayout>
|
||||
<para>The system returns status code 2xx (between 200
|
||||
and 299, inclusive) and the objects and
|
||||
pseudo-directories within the top level
|
||||
pseudo-directory.</para>
|
||||
<literallayout class="monospaced">photos/animals/
|
||||
photos/me.jpg
|
||||
photos/plants/ </literallayout>
|
||||
<para>You can create an unlimited number of nested
|
||||
pseudo-directories. To navigate through them, use
|
||||
a longer <code>prefix</code> parameter coupled
|
||||
with the <code>delimiter</code> parameter. In the
|
||||
sample output below, there is a pseudo-directory
|
||||
called <code>dogs</code> within the
|
||||
pseudo-directory <code>animals</code>. In order to
|
||||
navigate directly to the files contained within
|
||||
<code>dogs</code>, enter the below command.</para>
|
||||
<literallayout class="monospaced">GET /v1/AccountString/backups?prefix=photos/animals/dogs/&delimiter=/ </literallayout>
|
||||
<para>The system returns status code 2xx (between 200
|
||||
and 299, inclusive) and the objects and
|
||||
pseudo-directories within the nested pseudo-directory.
|
||||
</para>
|
||||
<literallayout class="monospaced">photos/animals/dogs/corgi.jpg
|
||||
photos/animals/dogs/poodle.jpg
|
||||
photos/animals/dogs/terrier.jpg</literallayout>
|
||||
</example>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="create-container">
|
||||
<title>Create Container</title>
|
||||
<para>&PUT; operations against a storage container are used to
|
||||
create that container.</para>
|
||||
<para>Containers are storage compartments for your data. The
|
||||
URL encoded name must be less than 256 bytes and cannot
|
||||
contain a forward slash '/' character.</para>
|
||||
<para>Containers can be assigned custom metadata by including
|
||||
additional HTTP headers on the &PUT; request. The custom
|
||||
metadata is assigned to a container via HTTP headers
|
||||
identified with the <code>X-Container-Meta-</code> prefix.</para>
|
||||
<example>
|
||||
<title>Create Container HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-create-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>No content is returned. A status code of 201 (Created)
|
||||
indicates that the container was created as requested.
|
||||
Container &PUT; requests are idempotent and a code of 202
|
||||
(Accepted) is returned when the container already existed.
|
||||
If you request a &PUT; to a container with an
|
||||
<code>X-Container-Meta-</code> prefix in the header,
|
||||
your &GET;/&HEAD; request responses carry the metadata
|
||||
prefix from the container in subsequent requests.</para>
|
||||
<example>
|
||||
<title>Create Container HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-create-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>Using custom container metadata, you can create information in the header to
|
||||
effectively tag a container with metadata. The container metadata restrictions are the
|
||||
same as object metadata: you can have 4096 bytes maximum overall metadata, 90 distinct
|
||||
metadata items at the most. Each may have a 128 character name length with a maximum of
|
||||
256 bytes in the value. Any valid UTF-8 encoded string value is allowed for metadata. In
|
||||
addition for custom metadata, we <emphasis role="italic">recommend</emphasis> that you
|
||||
URL-encode the header value. However, for non-custom metadata (such as
|
||||
X-Versions-Location), you <emphasis role="italic">must</emphasis> UTF-8 encode and then
|
||||
URL-encode values that contain a container or object name.</para>
|
||||
<example>
|
||||
<title>Container Create Container with Metadata HTTP
|
||||
Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-create-metadata-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>No content is returned. A status code of 201 (Created)
|
||||
indicates that the container was created as requested.
|
||||
Container &PUT; requests are idempotent and a code of 202
|
||||
(Accepted) is returned if the container existed prior to
|
||||
the request. If you request a &PUT; to a container with an
|
||||
<code>X-Container-Meta-</code> prefix in the header,
|
||||
your &GET;/&HEAD; request responses carry the metadata
|
||||
prefix from the container in subsequent requests.</para>
|
||||
<example>
|
||||
<title>Create Container with Metadata HTTP
|
||||
Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-create-metadata-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="delete-container">
|
||||
<title>Delete Container</title>
|
||||
<para>&DELETE; operations against a storage container
|
||||
permanently remove it. The container must be empty before
|
||||
it can be deleted.</para>
|
||||
<para>A &HEAD; request against the container can be used to
|
||||
determine if it contains any objects.</para>
|
||||
<example>
|
||||
<title>Delete Container HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-delete-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>No content is returned. A status code of 2xx (between
|
||||
200 and 299, inclusive) indicates success, 404 (Not Found) is
|
||||
returned if the requested container was not found, and a 409
|
||||
(Conflict) if the container is not empty. No response body is
|
||||
generated.</para>
|
||||
<example>
|
||||
<title>Delete Container HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-delete-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="retrieve-container-metadata">
|
||||
<title>Get Container Metadata</title>
|
||||
<para>&HEAD; operations against a storage container are used
|
||||
to determine the number of objects, and the total bytes of
|
||||
all objects stored in the container. Since the storage
|
||||
system is designed to store large amounts of data, care
|
||||
should be taken when representing the total bytes response
|
||||
as an integer; when possible, convert it to a 64-bit
|
||||
unsigned integer if your platform supports that primitive
|
||||
type.</para>
|
||||
<example>
|
||||
<title>Get Container Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-get-metadata-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>The HTTP status code will be 2xx (between 200 and 299,
|
||||
inclusive) if the container exists, and 404 (Not Found) if it
|
||||
does not. The object count and utilization are returned in the
|
||||
<code>X-Container-Object-Count</code> and
|
||||
<code>X-Container-Bytes-Used</code> headers
|
||||
respectively.</para>
|
||||
<example>
|
||||
<title>Get Container Metadata HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-get-metadata-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="Update_Container_Metadata-d1e1900">
|
||||
<title>Create or Update Container Metadata</title>
|
||||
<para>You may create any custom or arbitrary metadata headers
|
||||
as you find useful. They must, however, take the format
|
||||
<code>X-Container-Meta-</code>.</para>
|
||||
<para>To create or update the arbitrary container metadata,
|
||||
use the &POST; query. Subsequent requests of the same
|
||||
key/value pair overwrites the previous value.</para>
|
||||
<example>
|
||||
<title>Update Container Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-update-metadata-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>No response body is returned. A status code of 2xx
|
||||
(between 200 and 299, inclusive) indicates success; status 404
|
||||
(Not Found) is returned when the requested container does not
|
||||
exist.</para>
|
||||
<example>
|
||||
<title>Update Container Metadata HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-update-metadata-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>To confirm your metadata changes, perform a &HEAD;
|
||||
request on the container. Do not send the metadata in your
|
||||
&HEAD; request.</para>
|
||||
<example>
|
||||
<title>View Container Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-view-metadata-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>View Container Metadata HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-view-metadata-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<!-- Note: using POST with null value should delete a metadata header, but
|
||||
this method is not functional with all tools, so we are leaving it out for now.
|
||||
A future patch may come where using "-" (dash) for the value will delete it. dsh - 2012-0309 -->
|
||||
</section>
|
||||
<section xml:id="delete-container-metadata">
|
||||
<title>Delete Container Metadata</title>
|
||||
<para>To delete a metadata header send an empty value for that
|
||||
particular header, such as
|
||||
<code>X-Container-Meta-Book:</code>.</para>
|
||||
<para>If the tool you're using to communicate with Object
|
||||
Storage doesn't support sending empty headers (older
|
||||
versions of curl) send the header
|
||||
"X-Remove-Container-Meta-<replaceable>name</replaceable>:
|
||||
<replaceable>arbitrary value</replaceable>". For
|
||||
example, send a header like
|
||||
<code>X-Remove-Container-Meta-Book: x</code>. The
|
||||
<emphasis>value</emphasis> (x in this example) is
|
||||
ignored.</para>
|
||||
<example>
|
||||
<title>Delete Container Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-delete-metadata-req.txt" parse="text"/></literallayout>
|
||||
<para>No response body is returned. A status code of 2xx
|
||||
(between 200 and 299, inclusive) indicates success.</para>
|
||||
</example>
|
||||
</section>
|
||||
<title>Storage container services</title>
|
||||
<para>Lists objects, creates and delete containers, and gets,
|
||||
creates, updates, or deletes container metadata.</para>
|
||||
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
||||
<wadl:resource
|
||||
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#container">
|
||||
<wadl:method href="#listObjects"/>
|
||||
<wadl:method href="#createcontainer"/>
|
||||
<wadl:method href="#deletecontainer"/>
|
||||
<wadl:method href="#retrievecontainermeta"/>
|
||||
<wadl:method href="#updateacontainermeta"/>
|
||||
<wadl:method href="#deletecontainermeta"/>
|
||||
</wadl:resource>
|
||||
</wadl:resources>
|
||||
</section>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,325 +1,19 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
|
||||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Check_mark_23x20_02.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
|
||||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||||
<imageobject>
|
||||
<imagedata fileref="img/Arrow_east.svg"
|
||||
format="SVG" scale="60"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject>'>
|
||||
]>
|
||||
<section xml:id="storage-account-services"
|
||||
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">
|
||||
<title>Storage Account Services</title>
|
||||
<para>Perform the following operations at the account level of the
|
||||
URL:</para>
|
||||
<informaltable rules="all">
|
||||
<thead>
|
||||
<tr>
|
||||
<td colspan="1">Verb</td>
|
||||
<td colspan="2">URI</td>
|
||||
<td colspan="3">Description</td>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="1">&GET;</td>
|
||||
<td colspan="2">/<parameter>account</parameter></td>
|
||||
<td colspan="3">Lists containers.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&HEAD;</td>
|
||||
<td colspan="2">/<parameter>account</parameter></td>
|
||||
<td colspan="3">Gets account metadata.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&POST;</td>
|
||||
<td colspan="2">/<parameter>account</parameter></td>
|
||||
<td colspan="3">Creates or updates account
|
||||
metadata.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="1">&POST;</td>
|
||||
<td colspan="2">/<parameter>account</parameter></td>
|
||||
<td colspan="3">Deletes account metadata.</td>
|
||||
</tr>
|
||||
|
||||
</tbody>
|
||||
</informaltable>
|
||||
<variablelist>
|
||||
<title>Optional headers for HEAD and GET</title>
|
||||
<varlistentry>
|
||||
<term><code>X-Newest</code></term>
|
||||
<listitem>
|
||||
<para>Set the optional <code>X-newest</code> header to
|
||||
<code>True</code> in HEAD and GET requests to have
|
||||
Object Storage return the latest version of the account.
|
||||
If set to <code>True</code>, Object Storage queries all
|
||||
replicas to return the most recent one. Without this header,
|
||||
Object Storage responds faster after it finds one valid replica.
|
||||
Because setting this header to <code>True</code> is more
|
||||
expensive for the back end, use it only when it is
|
||||
absolutely needed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>For example, the URL for the requests end with the OpenStack
|
||||
Object Storage account string, as follows:</para>
|
||||
<example>
|
||||
<title>Storage Account Services HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/object-api-general-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<section xml:id="s_listcontainers">
|
||||
<title>List Containers</title>
|
||||
<para>&GET; operations against the <code>X-Storage-Url</code>
|
||||
for an account are performed to list storage containers
|
||||
sorted by name. The sort order for the name is based on a
|
||||
<link
|
||||
xlink:href="http://www.sqlite.org/datatype3.html#collation"
|
||||
>binary comparison</link>, a single built-in collating
|
||||
sequence that compares string data by using the SQLite
|
||||
memcmp() function, regardless of text encoding. The
|
||||
following list describes the optional query parameters
|
||||
that are supported with this request.</para>
|
||||
<variablelist>
|
||||
<title>Query Parameters</title>
|
||||
<varlistentry>
|
||||
<term><code>limit</code></term>
|
||||
<listitem>
|
||||
<para>For an integer value <inlineequation>
|
||||
<mathphrase><emphasis>n</emphasis></mathphrase>
|
||||
</inlineequation>, limits the number of
|
||||
results to <inlineequation>
|
||||
<mathphrase><emphasis>n</emphasis></mathphrase>
|
||||
</inlineequation> values.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>marker</code></term>
|
||||
<listitem>
|
||||
<para>Given a string value <inlineequation>
|
||||
<mathphrase><emphasis>x</emphasis></mathphrase>
|
||||
</inlineequation>, return container names
|
||||
greater in value than the specified
|
||||
marker.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>end_marker</code></term>
|
||||
<listitem>
|
||||
<para>Given a string value <inlineequation>
|
||||
<mathphrase><emphasis>x</emphasis></mathphrase>
|
||||
</inlineequation>, return container names less
|
||||
in value than the specified marker.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>format</code></term>
|
||||
<listitem>
|
||||
<para>Specify either <code>json</code> or
|
||||
<code>xml</code> to return the respective
|
||||
serialized response.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>At this time, a <code>prefix</code> query parameter is
|
||||
not supported at the account level.</para>
|
||||
<example>
|
||||
<title>List Containers HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/containers-list-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>A list of containers is returned in the response body,
|
||||
one container per line. The HTTP response's status code
|
||||
will be 2xx (between 200 and 299, inclusive).</para>
|
||||
<example>
|
||||
<title>List Containers HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/containers-list-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<section xml:id="s_serializedlistoutput">
|
||||
<title>Serialized List Output</title>
|
||||
<para>If a <code>format=xml</code> or
|
||||
<code>format=json</code> argument is appended to
|
||||
the storage account URL, the service serves extended
|
||||
container information serialized in the chosen format.
|
||||
The sample responses are formatted for readability.</para>
|
||||
<para>The following HTTP request asks for a JSON response,
|
||||
so the response returns an HTTP header and a JSON
|
||||
response.</para>
|
||||
<example>
|
||||
<title>Get Containers Details HTTP and JSON
|
||||
Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-get-details-json-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>Get Containers Details HTTP and JSON
|
||||
Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-get-details-http-json-resp.txt" parse="text"/></literallayout>
|
||||
<programlisting language="json"><xi:include href="samples/container-get-details-resp.json" parse="text"/></programlisting>
|
||||
</example>
|
||||
<para>The following HTTP request asks for an XML response,
|
||||
so the response returns an HTTP header and an XML
|
||||
response.</para>
|
||||
<example>
|
||||
<title>Containers Details HTTP and XML Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-get-details-http-xml-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>Containers Details HTTP and XML
|
||||
Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/container-get-details-http-xml-resp.txt" parse="text"/></literallayout>
|
||||
<programlisting language="xml"><xi:include href="samples/container-get-details-resp.xml" parse="text"/></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="s_list-large-number-containers">
|
||||
<title>Controlling a Large List of Containers</title>
|
||||
<para>The system returns a maximum of 10,000 container
|
||||
names per request. To retrieve subsequent container
|
||||
names, another request must be made with the 'marker'
|
||||
parameter. The marker indicates where the last list
|
||||
left off; the system returns container names greater
|
||||
than this marker, up to 10,000 again. Note that the
|
||||
‘marker’ value should be URL-encoded prior to sending
|
||||
the HTTP request.</para>
|
||||
<para>If 10,000 is larger than desired, use the 'limit'
|
||||
parameter.</para>
|
||||
<para>If the number of container names returned equals the
|
||||
limit given (or 10,000 if no limit is given), you may
|
||||
assume there are more container names.</para>
|
||||
<example>
|
||||
<title>List Large Number of Containers</title>
|
||||
<para>For example, let's use a listing of five
|
||||
container names:</para>
|
||||
<literallayout class="monospaced">apples
|
||||
bananas
|
||||
kiwis
|
||||
oranges
|
||||
pears</literallayout>
|
||||
<para>We'll use a limit of two to show how things
|
||||
work:</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/large-container-list-req.txt" parse="text"/></literallayout>
|
||||
<literallayout class="monospaced">apples
|
||||
bananas</literallayout>
|
||||
<para>Because we received two items back, we can
|
||||
assume there are more container names to list, so
|
||||
we make another request with a marker of the last
|
||||
item returned:</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/large-container-list-filter-req.txt" parse="text"/></literallayout>
|
||||
<literallayout class="monospaced">kiwis
|
||||
oranges</literallayout>
|
||||
<para>Again, two items are returned; there might be
|
||||
more:</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/large-container-list-filter2-req.txt" parse="text"/></literallayout>
|
||||
<literallayout class="monospaced">pears</literallayout>
|
||||
<para>With this one-item response we received less
|
||||
than the limit number of container names,
|
||||
indicating that this is the end of the
|
||||
list.</para>
|
||||
<para>By using <code>end_marker</code> we can limit
|
||||
the result set to container names less than the
|
||||
given value.</para>
|
||||
<literallayout class="monospaced"><xi:include href="samples/large-container-list-filter-end-marker-req.txt" parse="text"/></literallayout>
|
||||
<literallayout class="monospaced">apples
|
||||
bananas
|
||||
kiwis</literallayout>
|
||||
</example>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="retrieve-account-metadata">
|
||||
<title>Get Account Metadata</title>
|
||||
<para>&HEAD; operations against an account are performed to
|
||||
retrieve the number of containers and the total bytes
|
||||
stored in OpenStack Object Storage for the account. This
|
||||
information is returned in two custom headers,
|
||||
<code>X-Account-Container-Count</code> and
|
||||
<code>X-Account-Bytes-Used</code>. Since the storage
|
||||
system is designed to store large amounts of data, care
|
||||
should be taken when representing the total bytes response
|
||||
as an integer; when possible, convert it to a 64-bit
|
||||
unsigned integer if your platform supports that primitive
|
||||
type.</para>
|
||||
<example>
|
||||
<title>Get Account Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/account-get-metadata-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>The HTTP return code will be 2xx (between 200 and 299,
|
||||
inclusive) if the request succeeds. A 401 (Unauthorized)
|
||||
will be returned for an invalid account or access
|
||||
key.</para>
|
||||
<example>
|
||||
<title>Get Account Metadata HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/account-get-metadata-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="create-update-account-metadata">
|
||||
<title>Create or Update Account Metadata</title>
|
||||
<para>You can associate custom metadata headers with the
|
||||
account level URI. These headers must take the format
|
||||
<code>X-Account-Meta-*</code>.</para>
|
||||
<para>To create or update an account metadata header use the
|
||||
&POST; query. Subsequent requests for the same key/value
|
||||
pair overwrite the previous value.</para>
|
||||
<example>
|
||||
<title>Update Account Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/account-update-metadata-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>No response body is returned. A status code of 2xx
|
||||
(between 200 and 299, inclusive) indicates success.</para>
|
||||
<example>
|
||||
<title>Update Account Metadata HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/account-update-metadata-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<para>To confirm your metadata changes, perform a &HEAD;
|
||||
request on the account. Do not send the metadata in your
|
||||
&HEAD; request.</para>
|
||||
<example>
|
||||
<title>View Account Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/account-view-metadata-req.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
<example>
|
||||
<title>View Account Metadata HTTP Response</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/account-view-metadata-resp.txt" parse="text"/></literallayout>
|
||||
</example>
|
||||
</section>
|
||||
<section xml:id="delete-account-metadata">
|
||||
<title>Delete Account Metadata</title>
|
||||
<para>To delete a metadata header, send an empty value for
|
||||
that particular header, such as for the
|
||||
<code>X-Account-Meta-Book</code> header.</para>
|
||||
<para>If the tool you use to communicate with Object Storage,
|
||||
such as older versions of cURL, does not support empty
|
||||
headers, send the
|
||||
<literal>X-Remove-Account-Meta-</literal><replaceable>name</replaceable><literal>:</literal>
|
||||
<replaceable>arbitrary value</replaceable> header. For
|
||||
example, <code>X-Remove-Account-Meta-Book: x</code>. The
|
||||
<replaceable>arbitrary value</replaceable> is
|
||||
ignored.</para>
|
||||
<example>
|
||||
<title>Delete Account Metadata HTTP Request</title>
|
||||
<literallayout class="monospaced"><xi:include href="samples/account-delete-metadata-req.txt" parse="text"/></literallayout>
|
||||
<para>No response body is returned. A status code from 200
|
||||
to 299 indicates success.</para>
|
||||
</example>
|
||||
</section>
|
||||
<title>Storage account services</title>
|
||||
<para>Lists containers and gets, creates, updates, or deletes
|
||||
account metadata. You can perform these actions at the account
|
||||
level of the storage system.</para>
|
||||
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
||||
<wadl:resource
|
||||
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl#account">
|
||||
<wadl:method href="#listContainers"/>
|
||||
<wadl:method href="#retrieveaccountmeta"/>
|
||||
<wadl:method href="#updateaccountmeta"/>
|
||||
<wadl:method href="#deleteaccountmeta"/>
|
||||
</wadl:resource>
|
||||
</wadl:resources>
|
||||
</section>
|
||||
|
||||
@ -14,10 +14,12 @@
|
||||
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
||||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||||
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
|
||||
xml:id="object-storage-tempurl">
|
||||
xml:id="tempurl">
|
||||
<?dbhtml stop-chunking?>
|
||||
<title>Temporary URL middleware</title>
|
||||
<para>A temporary URL gives users temporary access to objects. For
|
||||
<para>To discover whether your Object Storage system supports
|
||||
this feature, see <xref linkend="discoverability"
|
||||
/>. Alternatively, check with your service provider.</para><para>A temporary URL gives users temporary access to objects. For
|
||||
example, a website might want to provide a link to download a
|
||||
large object in Object Storage, but the Object Storage account
|
||||
has no public access. The website can generate a URL that
|
||||
184
openstack-object-storage-dev/section_object-api-versioning.xml
Normal file
184
openstack-object-storage-dev/section_object-api-versioning.xml
Normal file
@ -0,0 +1,184 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE section [
|
||||
<!-- Some useful entities borrowed from HTML -->
|
||||
<!ENTITY ndash "–">
|
||||
<!ENTITY mdash "—">
|
||||
<!ENTITY hellip "…">
|
||||
|
||||
<!-- Useful for describing APIs -->
|
||||
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
|
||||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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>'>
|
||||
]>
|
||||
<section 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="set-object-versions">
|
||||
<title>Object versioning</title>
|
||||
<para>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.</para>
|
||||
<note>
|
||||
<para>You cannot version a large-object manifest file, but the
|
||||
large-object manifest file can point to versioned
|
||||
segments.</para>
|
||||
</note>
|
||||
<para>It is strongly recommended that you put non-current objects
|
||||
in a different container than the container where current
|
||||
object versions reside.</para>
|
||||
<procedure>
|
||||
<title>To enable and use object versioning</title>
|
||||
<step>
|
||||
<para>To enable object versioning, ask your cloud provider
|
||||
to set the <option>allow_versions</option> option to
|
||||
<literal>TRUE</literal> in the container
|
||||
configuration file.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>Create an <literal>archive</literal> container to
|
||||
store older versions of objects.</para>
|
||||
<para>Create the <literal>archive</literal>
|
||||
container:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive -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: tx46f8c29050834d88b8d7e-0052e1859d
|
||||
Date: Thu, 23 Jan 2014 21:11:57 GMT</computeroutput></screen>
|
||||
</step>
|
||||
<step>
|
||||
<para>Create a <literal>current</literal> container to
|
||||
store current versions of objects.</para>
|
||||
<para>Include the <literal>X-Versions-Location</literal>
|
||||
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
|
||||
<code>X-Versions-Location</code> header. This
|
||||
header enables object versioning for all objects in
|
||||
the <literal>current</literal> container. Changes to
|
||||
objects in the <literal>current</literal> container
|
||||
automatically create non-current versions in the
|
||||
<literal>archive</literal> container.</para>
|
||||
<para>Create the <literal>current</literal>
|
||||
container:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive"</userinput></screen>
|
||||
<screen><computeroutput>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</computeroutput></screen>
|
||||
</step>
|
||||
<step>
|
||||
<para>Create the first version of an object in the
|
||||
<literal>current</literal> container:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
|
||||
<screen><computeroutput>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</computeroutput></screen>
|
||||
<para>Nothing is written to the non-current version
|
||||
container when you initially &PUT; an object in the
|
||||
<literal>current</literal> container. However,
|
||||
subsequent &PUT; requests that edit an object trigger
|
||||
the creation of a version of that object in the
|
||||
<literal>archive</literal> container.</para>
|
||||
<para>These non-current versions are named as
|
||||
follows:</para>
|
||||
<programlisting><length><object_name><timestamp></programlisting>
|
||||
<para>Where <literal>length</literal> is the 3-character, zero-padded
|
||||
hexadecimal character length of the object,
|
||||
<literal><object_name></literal> is the object name, and
|
||||
<literal><timestamp></literal> is the time when the object was
|
||||
initially created as a current version.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>Create a second version of the object in the
|
||||
<literal>current</literal> container:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
|
||||
<screen><computeroutput>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</computeroutput></screen>
|
||||
</step>
|
||||
<step>
|
||||
<para>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.</para>
|
||||
<para>List older versions of the object in the
|
||||
<literal>archive</literal> container:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
|
||||
<screen><computeroutput>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</computeroutput></screen>
|
||||
<note>
|
||||
<para>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.</para>
|
||||
</note>
|
||||
</step>
|
||||
<step>
|
||||
<para>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.</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token"</userinput></screen>
|
||||
<screen><computeroutput>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</computeroutput></screen>
|
||||
<para>List objects in the <literal>archive</literal>
|
||||
container to show that the archived object was moved
|
||||
back to the <literal>current</literal>
|
||||
container:</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
|
||||
<screen><computeroutput>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</computeroutput></screen>
|
||||
<para>This next-most current version carries with it any
|
||||
metadata last set on it. If want to completely remove
|
||||
an object and you have five versions of it, you must
|
||||
&DELETE; it five times.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>To disable object versioning for the
|
||||
<literal>current</literal> container, remove its
|
||||
<literal>X-Versions-Location</literal> metadata
|
||||
header by sending an empty key value.</para>
|
||||
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: "</userinput></screen>
|
||||
<screen><computeroutput>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></computeroutput></screen>
|
||||
</step>
|
||||
</procedure>
|
||||
</section>
|
||||
Loading…
Reference in New Issue
Block a user