326 lines
16 KiB
XML
326 lines
16 KiB
XML
<?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>
|
||
</section>
|