Adds serialized response formats to End User Guide
With the moving of the Object Storage API content from a long-form dev guide to a specification, some topics needed to be added to the End User Guide. Also included linked environment variables topic. Change-Id: I6b8cee64e0bb7ea8ba7291aea31b4b7853f214a3 Partial-bug: 1392382
This commit is contained in:
Erik Wilson
parent
f3047b31ce
commit
1b49fe3f2c
@ -1,25 +1,24 @@
|
||||
<?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"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="managing-openstack-object-storage-with-swift-cli">
|
||||
<title>Manage objects and containers</title>
|
||||
<?dbhtml stop-chunking?>
|
||||
<para>The OpenStack Object Storage service provides the
|
||||
<command>swift</command> client, which is a command-line interface (CLI).
|
||||
Use this client to list objects and containers, upload objects to
|
||||
containers, and download or delete objects from containers. You can also
|
||||
gather statistics and update metadata for accounts, containers, and
|
||||
objects.</para>
|
||||
<para>This client is based on the native swift client library,
|
||||
<literal>client.py</literal>, which seamlessly
|
||||
re-authenticates if the current token expires during
|
||||
processing, retries operations multiple times, and provides a
|
||||
processing concurrency of 10.</para>
|
||||
<section xml:id="cli_create_containers">
|
||||
<title>Create and manage containers</title>
|
||||
<itemizedlist>
|
||||
<title>Manage objects and containers</title>
|
||||
<?dbhtml stop-chunking?>
|
||||
<para>The OpenStack Object Storage service provides the
|
||||
<command>swift</command> client, which is a command-line
|
||||
interface (CLI). Use this client to list objects and containers,
|
||||
upload objects to containers, and download or delete objects from
|
||||
containers. You can also gather statistics and update metadata for
|
||||
accounts, containers, and objects.</para>
|
||||
<para>This client is based on the native swift client library,
|
||||
<literal>client.py</literal>, which seamlessly re-authenticates
|
||||
if the current token expires during processing, retries operations
|
||||
multiple times, and provides a processing concurrency of
|
||||
10.</para>
|
||||
<section xml:id="cli_create_containers">
|
||||
<title>Create and manage containers</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>To create a container, run the following command and replace
|
||||
<replaceable>CONTAINER</replaceable> with the name of your
|
||||
@ -33,18 +32,19 @@
|
||||
<para>To check the status of containers, run the following
|
||||
command:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift stat</userinput></screen>
|
||||
<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
|
||||
<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
|
||||
Containers: 2
|
||||
Objects: 3
|
||||
Bytes: 268826
|
||||
Accept-Ranges: bytes
|
||||
X-Timestamp: 1392683866.17952
|
||||
Content-Type: text/plain; charset=utf-8</computeroutput></screen>
|
||||
<para>You can also use the <command>swift stat</command> command with the
|
||||
<replaceable>ACCOUNT</replaceable> or <replaceable>CONTAINER</replaceable>
|
||||
names as parameters.</para>
|
||||
<para>You can also use the <command>swift stat</command>
|
||||
command with the <replaceable>ACCOUNT</replaceable> or
|
||||
<replaceable>CONTAINER</replaceable> names as
|
||||
parameters.</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable></userinput></screen>
|
||||
<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
|
||||
<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
|
||||
Container: storage1
|
||||
Objects: 2
|
||||
Bytes: 240221
|
||||
@ -56,51 +56,56 @@ Accept-Ranges: bytes
|
||||
X-Timestamp: 1392683866.20180
|
||||
Content-Type: text/plain; charset=utf-8</computeroutput></screen>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="cli_manage_access_swift">
|
||||
<title>Manage access</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Users have roles on accounts. For example, a user with the admin
|
||||
role has full access to all containers and objects in an account. You
|
||||
can set access control lists (ACLs) at the container level and support
|
||||
lists for read and write access, which you set with the
|
||||
<para>Users have roles on accounts. For example, a user with
|
||||
the admin role has full access to all containers and objects
|
||||
in an account. You can set access control lists (ACLs) at
|
||||
the container level and support lists for read and write
|
||||
access, which you set with the
|
||||
<literal>X-Container-Read</literal> and
|
||||
<literal>X-Container-Write</literal> headers.</para>
|
||||
<para>To give a user read access, use the <command>swift post</command>
|
||||
command with the <parameter>-r</parameter> parameter. To give a user
|
||||
write access, use the <parameter>-w</parameter> parameter.</para>
|
||||
<para>The following example enables the <literal>testuser</literal> user
|
||||
to read objects in the container:</para>
|
||||
<para>To give a user read access, use the <command>swift
|
||||
post</command> command with the <parameter>-r</parameter>
|
||||
parameter. To give a user write access, use the
|
||||
<parameter>-w</parameter> parameter.</para>
|
||||
<para>The following example enables the
|
||||
<literal>testuser</literal> user to read objects in the
|
||||
container:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift post -r 'testuser'</userinput></screen>
|
||||
<para>You can also use this command with a list of users.</para>
|
||||
<para>You can also use this command with a list of
|
||||
users.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>If you use StaticWeb middleware to enable Object Storage to serve
|
||||
public web content, use <literal>.r:</literal>, followed by a list of
|
||||
allowed referrers.</para>
|
||||
<para>The following command gives object access to all referring
|
||||
domains:</para>
|
||||
<para>If you use StaticWeb middleware to enable Object Storage
|
||||
to serve public web content, use <literal>.r:</literal>,
|
||||
followed by a list of allowed referrers.</para>
|
||||
<para>The following command gives object access to all
|
||||
referring domains:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift post -r '.r:*'</userinput></screen>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="cli_manage_objects">
|
||||
<title>Manage objects</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<section xml:id="cli_manage_objects">
|
||||
<title>Manage objects</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>To upload an object to a container, run the following
|
||||
command:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift upload <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
|
||||
<para>To upload in chunks, for large files, run the following command:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift upload -S <replaceable>CHUNK_SIZE</replaceable> <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
|
||||
<screen><prompt>$</prompt> <userinput>swift upload <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
|
||||
<para>To upload in chunks, for large files, run the following
|
||||
command:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift upload -S <replaceable>CHUNK_SIZE</replaceable> <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>To check the status of the object, run the following
|
||||
command:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
|
||||
<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
|
||||
<screen><prompt>$</prompt> <userinput>swift stat <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
|
||||
<screen><computeroutput>Account: AUTH_7b5970fbe7724bf9b74c245e77c03bcg
|
||||
Container: storage1
|
||||
Object: images
|
||||
Content Type: application/octet-stream
|
||||
@ -110,11 +115,12 @@ ETag: 82169623d55158f70a0d720f238ec3ef
|
||||
Meta Orig-Filename: images.jpg
|
||||
Accept-Ranges: bytes
|
||||
X-Timestamp: 1392684036.33306</computeroutput></screen>
|
||||
</listitem>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>To list the objects in a container, run the following command:</para>
|
||||
<para>To list the objects in a container, run the following
|
||||
command:</para>
|
||||
<screen><prompt>$</prompt> <userinput>swift list <replaceable>CONTAINER</replaceable></userinput></screen>
|
||||
</listitem>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>To download an object from a container, run the
|
||||
following command:</para>
|
||||
@ -122,6 +128,8 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<xi:include href="section_object-api-versioning.xml"/>
|
||||
<xi:include href="section_object-api-env-vars.xml"/>
|
||||
<xi:include href="section_object-api-response-formats.xml"/>
|
||||
<xi:include href="section_object-api-create-large-objects.xml"/>
|
||||
<xi:include href="section_object-api-versioning.xml"/>
|
||||
</section>
|
||||
|
||||
44
doc/user-guide/section_object-api-env-vars.xml
Normal file
44
doc/user-guide/section_object-api-env-vars.xml
Normal file
@ -0,0 +1,44 @@
|
||||
<?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>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>publicURL</literal></term>
|
||||
<listitem>
|
||||
<para>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>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><literal>token</literal></term>
|
||||
<listitem>
|
||||
<para>The authentication token for Object
|
||||
Storage.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<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>
|
||||
144
doc/user-guide/section_object-api-response-formats.xml
Normal file
144
doc/user-guide/section_object-api-response-formats.xml
Normal file
@ -0,0 +1,144 @@
|
||||
<?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
|
||||
linkend="env-vars">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>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><code>text/plain</code></term>
|
||||
<listitem>
|
||||
<para>Plain text response format. The
|
||||
default.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>application/jsontext</code></term>
|
||||
<listitem>
|
||||
<para>JSON data serialization response
|
||||
format.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>application/xml</code>or
|
||||
<code>text/xml</code></term>
|
||||
<listitem>
|
||||
<para>XML data serialization response
|
||||
format.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</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>
|
||||
Loading…
Reference in New Issue
Block a user