0c02c60282
This change adds information to the getting started user guide about the partial attribute deprecation/removal. Change-Id: I97684ffa7766885990e433304c9b8118b41c3af5 Closes-Bug: #1350437
1154 lines
58 KiB
XML
1154 lines
58 KiB
XML
<?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 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>'>
|
|
<!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
|
|
<!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>'>
|
|
]>
|
|
<book 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"
|
|
version="5.0" xml:id="mq-gettingstarted">
|
|
<title>Message Queuing API v1 Getting Started Guide</title>
|
|
<titleabbrev>Message Queuing Getting Started Guide</titleabbrev>
|
|
<info>
|
|
<author>
|
|
<personname>
|
|
<firstname/>
|
|
<surname/>
|
|
</personname>
|
|
<!-- <affiliation>
|
|
<orgname>OpenStack Foundation</orgname>
|
|
</affiliation> -->
|
|
</author>
|
|
<!-- <copyright>
|
|
<year>2013</year>
|
|
<year>2014</year>
|
|
<holder>OpenStack Foundation</holder>
|
|
</copyright> -->
|
|
<releaseinfo>API v1</releaseinfo>
|
|
<productname>Message Queuing</productname>
|
|
<pubdate>2014-02-20</pubdate>
|
|
<!--If you leave the <pubdate> element empty, the build system inserts today's date automatically. -->
|
|
<legalnotice role="rs-api">
|
|
<annotation>
|
|
<remark>Copyright details are filled in by the build
|
|
system.</remark>
|
|
</annotation>
|
|
</legalnotice>
|
|
<abstract>
|
|
<para>This document is intended for software developers interested in developing
|
|
applications using the Message Queuing Application Programming Interface
|
|
(<abbrev>API</abbrev>).</para>
|
|
</abstract>
|
|
<revhistory>
|
|
<revision>
|
|
<date>2014-02-20</date>
|
|
<revdescription>
|
|
<para>Initial document for OpenStack incubation
|
|
incubation.</para>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2014-08-30</date>
|
|
<revdescription>
|
|
<para>The <parameter>partial</parameter> attribute is no longer supported.</para>
|
|
</revdescription>
|
|
</revision>
|
|
</revhistory>
|
|
</info>
|
|
<chapter xml:id="doc-change-history">
|
|
<title>Document Change History</title>
|
|
<para>This version of the document replaces and obsoletes all
|
|
earlier versions. The most recent changes are described in
|
|
the following table:</para>
|
|
<?rax revhistory?>
|
|
</chapter>
|
|
<chapter xml:id="DB_Overview"
|
|
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">
|
|
<title>Overview</title>
|
|
<para>Message Queuing is a RESTful API-based messaging service that supports distributed web
|
|
applications. A message service such as Message Queuing is a vital component of large,
|
|
distributed web applications. You can use Message Queuing for public, private, and
|
|
hybrid cloud environments.</para>
|
|
<para>As you develop distributed web applications, you often have multiple agents set up to
|
|
complete sets of tasks for those applications. These tasks can be anything from creating
|
|
users to deleting blocks of storage. Message Queuing provides a simple interface to
|
|
create these tasks as queues, messages, and claims and to post, claim, read, and delete
|
|
them as the tasks are needed and performed.</para>
|
|
<para>Message Queuing handles the distribution of tasks, but it does not necessarily manage
|
|
the order of the tasks. Applications handle the workflow at a higher level.</para>
|
|
<para>Message Queuing is based on the OpenStack Zaqar project.</para>
|
|
<para>This guide explains how to access and start using the API so that you can begin to use
|
|
Message Queuing for your applications. Instructions are given for how to properly enter
|
|
the necessary URLs, using cURL, to set up and use a basic set of Message Queuing
|
|
operations.</para>
|
|
<section xml:id="core_concepts">
|
|
<title>Prerequisites for Running Examples</title>
|
|
<para xmlns:wadl="http://wadl.dev.java.net/2009/02">In
|
|
order to run the examples in this guide, you must have
|
|
the following prerequisites:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>A Cloud account</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A username and password, as
|
|
specified during registration</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Prior knowledge of HTTP/1.1
|
|
conventions</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Basic familiarity with Cloud and RESTful
|
|
APIs</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="how_mq_works">
|
|
<title>How Message Queuing Works</title>
|
|
<para>Following is an overview of how Message Queuing works. For definitions of Message
|
|
Queuing terms, see the <xref linkend="glossary-d1e018"/>.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>You create a queue to which producers or
|
|
publishers post messages.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Workers (consumers or subscribers) claim or
|
|
get a message from the queue, complete the
|
|
work in that message, and delete the
|
|
message.</para>
|
|
<para>If a worker will be off-line before it
|
|
completes the work in a message, the worker
|
|
can retire the claim's time to live (TTL),
|
|
putting the message back into the queue for
|
|
another worker to claim.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Subscribers monitor the claims from these
|
|
queues to track activity and help troubleshoot
|
|
errors.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>For the majority of use cases, Message Queuing is not responsible for the ordering
|
|
of messages. However, if there is only a single producer, Message Queuing ensures
|
|
that messages are handled in a First In, First Out (FIFO) order.</para>
|
|
<section xml:id="operating_modes">
|
|
<title>Messaging Patterns</title>
|
|
<para>The Message Queuing API supports a variety of
|
|
messaging patterns including the following:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Task distribution</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Event broadcasting</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Point-to-point messaging</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="task_distribution">
|
|
<title>Task distribution</title>
|
|
<para>The task distribution pattern has the following
|
|
characteristics:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A producer is programmed to send messages to a
|
|
queue.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Multiple workers (or consumers) are programmed to
|
|
monitor a queue.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Only one worker can claim a message so that
|
|
no other worker can claim the message and
|
|
duplicate the work.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The worker must delete the message when work
|
|
is done.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>TTL restores a message to an unclaimed state
|
|
if the worker never finishes.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>This pattern is ideal for dispatching jobs to multiple
|
|
processors.</para>
|
|
</section>
|
|
<section xml:id="event_broadcasting">
|
|
<title>Event Broadcasting</title>
|
|
<para>Characteristics of the event broadcasting pattern
|
|
are:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The publisher sends messages to a
|
|
queue.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Multiple observers (or subscribers) get the
|
|
messages in the queue.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Multiple observers take action on each
|
|
message.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Observers send a marker to skip messages
|
|
already seen.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>TTL eventually deletes messages.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>This pattern is ideal for notification of events to
|
|
multiple observers at once.</para>
|
|
</section>
|
|
<section xml:id="point_to_point">
|
|
<title>Point-to-point messaging</title>
|
|
<para>Characteristics of the point-to-point messaging
|
|
pattern are:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The publisher sends messages to a queue.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The consumer gets the messages in the queue.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The consumer can reply with the result of
|
|
processing a message by sending another message
|
|
to the same queue (queues are duplex by
|
|
default).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The publisher gets replies from the queue.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The consumer sends a marker to skip messages
|
|
already seen.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>TTL eventually deletes messages.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>This pattern is ideal for communicating with a
|
|
specific client, especially when a reply is desired
|
|
from that client.</para>
|
|
</section>
|
|
<section xml:id="cloud-queuing-actions">
|
|
<title>Message Queuing Operations</title>
|
|
<para>This section lists all of the operations that are available in the Message
|
|
Queuing API. This document uses some of the most common operations in <xref
|
|
linkend="stepping_through_the_api"/>.</para>
|
|
<para>For details about all of the operations, see the <citetitle>Message Queuing
|
|
API v1 Reference</citetitle>.</para>
|
|
<section xml:id="homeDocument">
|
|
<title>Home Document</title>
|
|
<para>The following operation is available for the
|
|
home document:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Get Home Document</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="queue-actions">
|
|
<title>Queues</title>
|
|
<para>The following operations are available for
|
|
queues:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Create Queue</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>List Queues</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Check Queue Existence</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Set Queue Metadata</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Get Queue Metadata</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Get Queue Stats</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Delete Queue</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="message-actions">
|
|
<title>Messages</title>
|
|
<para>The following operations are available for
|
|
messages:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Post Message</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Get Messages</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Get a Specific Message</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Get a Set of Messages by ID</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Delete Message</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Delete a Set of Messages by
|
|
ID</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="claim-actions">
|
|
<title>Claims</title>
|
|
<para>The following operations are available for
|
|
claims:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Claim Messages</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Query Claim</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Update Claim</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Release Claim</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
<section xml:id="use_cases">
|
|
<title>Use Cases</title>
|
|
<para>Queuing systems are used to coordinate tasks
|
|
within an application. Here are some
|
|
examples:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Backup</emphasis>:
|
|
A backup application might use a queuing
|
|
system to connect the actions that users
|
|
do in the a control panel to the
|
|
customer's backup agent on a server. When
|
|
a customer wants to start a backup, they
|
|
simply choose "start backup" on a panel.
|
|
Doing so causes the producer to put a
|
|
"startBackup" message into the queue.
|
|
Every few minutes, the agent on the
|
|
customers server (the worker) checks the
|
|
queue to see if it has any new messages to
|
|
act on. The agent claims the "startBackup"
|
|
message and kicks off the backup on the
|
|
customer's server.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold"
|
|
>Storage</emphasis>: Gathering statistics
|
|
for a large, distributed storage system
|
|
can be a long process. The storage system
|
|
can use a queuing system to ensure that
|
|
jobs complete, even if one initially
|
|
fails. Since messages are not deleted
|
|
until after the worker has completed the
|
|
job, the storage system can make sure that
|
|
no job goes undone. If the worker fails to
|
|
complete the job, the message stays in the
|
|
queue to be completed by another server.
|
|
In this case, a worker claims a message to
|
|
perform a statistics job, but the claim's
|
|
TTL expired and the message is put back
|
|
into the queue when the job took too long
|
|
to complete (meaning that it most likely
|
|
failed). By giving the claim a TTL,
|
|
applications can protect themselves from
|
|
workers going off-line while processing a
|
|
message. After a claim's TTL expires, the
|
|
message is put back into the queue for
|
|
another worker to claim.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Email</emphasis>:
|
|
The team for an email application is
|
|
constantly migrating customer email from
|
|
old versions to newer ones, so they
|
|
develop a tool to let customers do it
|
|
themselves. The migrations take a long
|
|
time, so they cannot be done with single
|
|
API calls, or by a single server. When a
|
|
user starts a migration job from their
|
|
portal, the migration tool sends messages
|
|
to the queue with details of how to run
|
|
the migration. A set of migration engines,
|
|
the consumers in this case, periodically
|
|
check the queues for new migration tasks,
|
|
claim the messages, perform the migration,
|
|
and update a database with the migration
|
|
details. This process allows a set of
|
|
servers to work together to accomplish
|
|
large migrations in a timely manner.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Following are some generic use cases for Message Queuing:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Distribute tasks among multiple workers (transactional
|
|
job queues)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Forward events to data collectors (transactional event
|
|
queues)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Publish events to any number of subscribers
|
|
(event broadcasting)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Send commands to one or more agents
|
|
(point-to-point messaging or event broadcasting)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Request an action or get information from a Remote
|
|
Procedure Call (RPC) agent (point-to-point
|
|
messaging)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="prerequisites">
|
|
<title>Send Requests to the API</title>
|
|
<para>You have several options for sending requests through an
|
|
API:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Developers and testers may prefer to use cURL,
|
|
the command-line tool from <link
|
|
xlink:href="http://curl.haxx.se/"
|
|
>http://curl.haxx.se/</link>.</para>
|
|
<para>With cURL you can send HTTP requests and receive
|
|
responses back from the command line.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you like to use a more graphical interface,
|
|
the REST client for Firefox also works well for
|
|
testing and trying out commands, see <link
|
|
xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/"
|
|
>https://addons.mozilla.org/en-US/firefox/addon/restclient/</link>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can also download and install rest-client, a
|
|
Java application to test RESTful web services,
|
|
from <link
|
|
xlink:href="http://code.google.com/p/rest-client/"
|
|
>http://code.google.com/p/rest-client/</link>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<section xml:id="using_curl">
|
|
<title>Sending API Requests Using cURL</title>
|
|
<para>cURL is a command-line tool that is available in
|
|
UNIX® system-based environments and Apple Mac OS X®
|
|
systems, and can be downloaded for Microsoft Windows®
|
|
to interact with the REST interfaces. For more
|
|
information about cURL, visit <link
|
|
xlink:href="http://curl.haxx.se/"
|
|
>http://curl.haxx.se/</link>.</para>
|
|
<para>cURL enables you to transmit and receive HTTP
|
|
requests and responses from the command line or from
|
|
within a shell script. As a result, you can work with
|
|
the REST API directly without using one of the client
|
|
APIs.</para>
|
|
<para>The following cURL command-line options are used in
|
|
this guide to run the examples.</para>
|
|
<table rules="all">
|
|
<caption>cURL Command-Line Options</caption>
|
|
<col width="30%"/>
|
|
<col width="70%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>-d</code></td>
|
|
<td>Sends the specified data in a
|
|
<code>POST</code> request to the HTTP
|
|
server.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>-i</code></td>
|
|
<td>Includes the HTTP header in the
|
|
output.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>-H HEADER</code></td>
|
|
<td>Specifies an HTTP header in the
|
|
request.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>-X</code></td>
|
|
<td>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. For example,
|
|
<code>-X PUT</code> specifies to use
|
|
the <code>PUT</code> request method.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<note>
|
|
<para>If you have the tools, you can run the cURL JSON
|
|
request examples with the following options to
|
|
format the output from cURL: <command><curl
|
|
JSON request example> | python
|
|
-mjson.tool</command>.</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="Copying-and_Pasting-cURL-d1e003">
|
|
<title>Copying and Pasting cURL Request Examples into a
|
|
Terminal Window</title>
|
|
<para>To run the cURL request examples shown in this guide
|
|
(<xref linkend="stepping_through_the_api"/>) on
|
|
Linux or Mac systems, perform the following
|
|
actions:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Copy and paste each example from the HTML
|
|
version of this guide into an ASCII text
|
|
editor (for example, vi or TextEdit). You can
|
|
click on the small document icon to the right
|
|
of each request example to select it.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Modify each example with your required
|
|
account information and so forth, as detailed
|
|
in this guide.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>After you are finished modifying the text
|
|
for the cURL request example with your
|
|
information (for example,<emphasis role="bold"
|
|
><literal>your_username</literal></emphasis>
|
|
and <emphasis role="bold"
|
|
><literal>your_api_key</literal></emphasis>),
|
|
paste it into your terminal window.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Press <guilabel>Enter</guilabel> to run the
|
|
cURL command.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<note>
|
|
<para>The carriage returns in the cURL request
|
|
examples that are part of the cURL syntax are
|
|
escaped with a backslash (\) in order to avoid
|
|
prematurely terminating the command. However, you
|
|
should not escape carriage returns inside the JSON
|
|
message within the command.</para>
|
|
</note>
|
|
<tip>
|
|
<para>If you have trouble copying and pasting the
|
|
examples as described, try typing the entire
|
|
example on one long line, removing all the
|
|
backslash line continuation characters.</para>
|
|
</tip>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="Generating_Auth_Token">
|
|
<title>Generate an Authentication Token</title>
|
|
<para>You can use <link xlink:href="http://curl.haxx.se/">cURL</link> to try the
|
|
authentication process in two steps: get a token, and send the token to a service.<orderedlist>
|
|
<listitem>
|
|
<para>Get an authentication token by providing your user name and either your
|
|
API key or your password. Here are examples of both approaches:</para>
|
|
<para>You can request a token by providing your user name and your
|
|
password.</para>
|
|
<programlisting>$ curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</programlisting>
|
|
<para>Successful authentication returns a token which you can use as evidence
|
|
that your identity has already been authenticated. To use the token, pass it
|
|
to other services as an <code>X-Auth-Token</code> header.</para>
|
|
<para>Authentication also returns a service catalog, listing the endpoints you
|
|
can use for Cloud services.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Use the authentication token to send a <command>GET</command> to a service
|
|
you would like to use.</para>
|
|
</listitem>
|
|
</orderedlist></para>
|
|
<para>Authentication tokens are typically valid for 24 hours. Applications should be
|
|
designed to re-authenticate after receiving a 401 (Unauthorized) response from a service
|
|
endpoint.</para>
|
|
<note>
|
|
<para>If you programmatically parse an authentication response, be aware that service
|
|
names are stable for the life of the particular service and can be used as keys. You
|
|
should also be aware that a user's service catalog can include multiple
|
|
uniquely-named services that perform similar functions.</para>
|
|
</note>
|
|
</chapter>
|
|
<chapter xml:id="commonHeaders">
|
|
<title>Common Headers</title>
|
|
<para>Each request to the Message Queuing API must include certain standard and extended
|
|
HTTP headers (as shown in the following table). These headers provide host, agent,
|
|
authentication, and other pertinent information to the server. The following table
|
|
provides the common headers used by the API.</para>
|
|
<table rules="all">
|
|
<caption>Common Headers</caption>
|
|
<col width="30%"/>
|
|
<col width="70%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Header</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>Host</td>
|
|
<td>Host name of the API</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Date</td>
|
|
<td>Current date and time</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Accept</td>
|
|
<td>Media type to use. Initially, only
|
|
<code>application/json</code> is
|
|
supported. <emphasis role="bold">Note: The
|
|
<code>Accept</code> header is
|
|
required.</emphasis></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Accept-Encoding</td>
|
|
<td>Specifies that the agent accepts gzip-encoded
|
|
response bodies</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Content-Type</td>
|
|
<td><code>application/json</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Content-Length</td>
|
|
<td>For <command>POST</command> or
|
|
<command>PUT</command> requests, the
|
|
length in bytes of the message document being
|
|
submitted</td>
|
|
</tr>
|
|
<tr>
|
|
<td>X-Auth-Token</td>
|
|
<td>Authorization token</td>
|
|
</tr>
|
|
<tr>
|
|
<td>X-Project-Id</td>
|
|
<td>An ID for a project to which the value of
|
|
X-Auth-Token grants access. Queues are created
|
|
under this project. The project ID is the same
|
|
as the account ID (also sometimes called
|
|
tenant ID).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Client-ID</td>
|
|
<td>A UUID for each client instance. The UUID must
|
|
be submitted in its canonical form (for
|
|
example,
|
|
3381af92-2b9e-11e3-b191-71861300734c). The
|
|
client generates the Client-ID once. Client-ID
|
|
persists between restarts of the client so the
|
|
client should reuse that same Client-ID.
|
|
<emphasis role="bold">Note: All
|
|
message-related operations require the use
|
|
of <code>Client-ID</code> in the headers
|
|
to ensure that messages are not echoed
|
|
back to the client that posted them,
|
|
unless the client explicitly requests
|
|
this.</emphasis></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</chapter>
|
|
<chapter xml:id="stepping_through_the_api">
|
|
<title>Working with the Message Queuing API</title>
|
|
<para>This chapter contains a simple exercise with some basic Message Queuing requests that
|
|
you will commonly use. Example requests are provided in cURL, followed by the
|
|
response.</para>
|
|
<para>For a complete list of operations available for Message Queuing, see <xref
|
|
linkend="cloud-queuing-actions"/>. Each operation is fully described in the
|
|
<emphasis role="italic">Message Queuing API v1 Reference</emphasis>.</para>
|
|
<section xml:id="create_queue">
|
|
<title>Create Queue</title>
|
|
<para>The Create Queue operation creates a queue in the
|
|
region of your choice.</para>
|
|
<para>The body of the PUT request is empty.</para>
|
|
<para>The template is as follows:</para>
|
|
<para>
|
|
<programlisting language="json">PUT {endpoint}/queues/{queue_name}</programlisting>
|
|
</para>
|
|
<para>The <parameter>queue_name</parameter> parameter
|
|
specifies the name to give the queue. The name
|
|
<emphasis role="italic">must not</emphasis> exceed
|
|
64 bytes in length and is limited to US-ASCII letters,
|
|
digits, underscores, and hyphens.</para>
|
|
<para>Following are examples of a Create Queue request and
|
|
response:</para>
|
|
<example>
|
|
<title>cURL Create Queue Request</title>
|
|
<programlisting language="bash">curl -i -X PUT https://queues.api.openstack.org/v1/queues/samplequeue \
|
|
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
|
|
-H "Accept: application/json" \
|
|
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Create Queue Response</title>
|
|
<programlisting language="json">HTTP/1.1 201 Created
|
|
Content-Length: 0
|
|
Location: /v1/queues/samplequeue</programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="insert_messages">
|
|
<title>Post Message</title>
|
|
<para>The Post Message operation inserts one or more
|
|
messages in a queue.</para>
|
|
<para>You can submit up to 10 messages in a single
|
|
request, but you must encapsulate them in a collection
|
|
container (an array in JSON, even for a single message
|
|
- without the JSON array, you receive an "Invalid body
|
|
request" error message). You can use the resulting
|
|
value of the location header or response body to
|
|
retrieve the created messages for further processing
|
|
if needed.</para>
|
|
<para>The template is as
|
|
follows:<programlisting language="json">POST {endpoint}/queues/{queue_name}/messages</programlisting></para>
|
|
<para>The client specifies only the <tag class="attribute"
|
|
>body</tag> and <tag class="attribute">ttl</tag>
|
|
attributes for the message. Metadata, such as <tag
|
|
class="attribute">id</tag> and <tag
|
|
class="attribute">age</tag>, is added.</para>
|
|
<para>The response body contains a list of resource paths
|
|
that correspond to each message submitted in the
|
|
request, in the same order as they were submitted.</para>
|
|
<para>If a server-side error occurs during the processing
|
|
of the submitted messages, a partial list is returned.
|
|
The <parameter>partial</parameter> attribute is set to
|
|
<parameter>true</parameter>, and the client tries
|
|
to post the remaining messages again.
|
|
</para>
|
|
<important>
|
|
<para>The <parameter>partial</parameter> attribute has been deprecated in the v1.0 API
|
|
and is not available in the v1.1 API.
|
|
Drivers are now required to operate in a transactional manner.
|
|
In other words, either all messages must be posted, or none of them.
|
|
</para>
|
|
</important>
|
|
<para>
|
|
The <parameter>body</parameter> attribute specifies an
|
|
arbitrary document that constitutes the body of the
|
|
message being sent.</para>
|
|
<para>The following rules apply for the maximum size:<itemizedlist>
|
|
<listitem>
|
|
<para>The size is limited to 256 KB for the
|
|
entire request body (as-is), including
|
|
whitespace.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The maximum size of posted messages is
|
|
the maximum size of the entire request
|
|
document (rather than the sum of the
|
|
individual message <code>body</code> field
|
|
values as it was earlier releases). On
|
|
error, the client is notified of by how
|
|
much the request exceeded the
|
|
limit.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
<!-- 2014-01-17 cyr: Per email from Kurt today, the following information is now outdated and is replaced with the information above.
|
|
<para>
|
|
excluding whitespace. If multiple messages are
|
|
included in the request, this limit also applies to
|
|
the sum of the message bodies. For example, you can
|
|
have one message body of 256 KB, or up to 10 messages
|
|
for which the sum of the message bodies is 256 KB. An
|
|
HTTP<code>400 Bad Request</code> response code is
|
|
triggered if a single message body or the sum of
|
|
multiple message bodies exceeds 256 KB in a single
|
|
request.</para>
|
|
-->
|
|
<para>The document <emphasis role="italic">must</emphasis> be valid JSON. (The Message
|
|
Queuing service validates it.)</para>
|
|
<para>The <parameter>ttl</parameter> attribute specifies
|
|
the lifetime of the message. When the lifetime
|
|
expires, the server deletes the message and removes it
|
|
from the queue. Valid values are 60 through 1209600
|
|
seconds (14 days).</para>
|
|
<note>
|
|
<para>The server might not actually delete the
|
|
message until its age reaches <tag
|
|
class="attribute">(ttl + 60)</tag> seconds. So
|
|
there might be a delay of 60 seconds after the
|
|
message expires before it is deleted.</para>
|
|
</note>
|
|
<para>The following are examples of a Post Message request
|
|
and response:</para>
|
|
<example>
|
|
<title>cURL Post Message Request</title>
|
|
<programlisting language="bash">curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/messages -d \
|
|
'[{"ttl": 300,"body": {"event": "BackupStarted"}},{"ttl": 60,"body": {"play": "hockey"}}]' \
|
|
-H "Content-type: application/json" \
|
|
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
|
|
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
|
|
-H "Accept: application/json" \
|
|
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Post Message Response</title>
|
|
<programlisting language="json">HTTP/1.1 201 Created
|
|
Content-Length: 153
|
|
Content-Type: application/json; charset=utf-8
|
|
Location: /v1/queues/samplequeue/messages?ids=51ca00a0c508f154c912b85c,51ca00a0c508f154c912b85d
|
|
|
|
{"partial": false, "resources": ["/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c", "/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85d"]}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Claim_messages">
|
|
<title>Claim Messages</title>
|
|
<para>The Claim Messages operation claims a set of messages (up to the value of the
|
|
<parameter>limit</parameter> parameter) from oldest to newest and skips any
|
|
messages that are already claimed. If there are no messages available to claim, the
|
|
Message Queuing service returns an HTTP <code>204 No Content</code> response
|
|
code.</para>
|
|
<para>The template is as follows:</para>
|
|
<programlisting language="json">POST {endpoint}/queues/{queue_name}/claims{?limit}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"ttl": {claim_ttl},
|
|
"grace": {message_grace}
|
|
}</programlisting>
|
|
<para>The client (worker) needs to delete the message when it has finished processing
|
|
it. The client deletes the message before the claim expires to ensure that the
|
|
message is processed only once. If a client needs more time, the Cloud Service
|
|
provides the Update Claim operation to make changes. See the <citetitle>Message
|
|
Queuing API v1 Reference</citetitle> for a description of this operation. As
|
|
part of the delete operation, workers specify the claim ID (which is best done by
|
|
simply using the provided href). If workers perform these actions, then if a claim
|
|
simply expires, the server can return an error and notify the worker of a possible
|
|
race condition. This action gives the worker a chance to roll back its own
|
|
processing of the given message because another worker can claim the message and
|
|
process it.</para>
|
|
<para>The age given for a claim is relative to the
|
|
server's clock. The claim's age is useful for
|
|
determining how quickly messages are getting processed
|
|
and whether a given message's claim is about to
|
|
expire.</para>
|
|
<para>When a claim expires, it is released back to the
|
|
queue for other workers to claim. (If the original
|
|
worker failed to process the message, another client
|
|
worker can then claim the message.)</para>
|
|
<para>The <parameter>limit</parameter> parameter specifies
|
|
the number of messages to claim. The <parameter>limit</parameter> parameter is configurable.
|
|
The default is 20. Messages
|
|
are claimed based on the number of messages available.
|
|
The server might claim and return less than the
|
|
requested number of messages.</para>
|
|
<para>The <parameter>ttl</parameter> attribute specifies
|
|
the lifetime of the claim. While messages are claimed,
|
|
they are not available to other workers. The value
|
|
must be between 60 and 43200 seconds (12
|
|
hours).</para>
|
|
<para>The <parameter>grace</parameter> attribute specifies
|
|
the message grace period in seconds. Valid values are
|
|
between 60 and 43200 seconds (12 hours). To deal with
|
|
workers that have stopped responding (for up to
|
|
1209600 seconds or 14 days, including claim lifetime),
|
|
the server extends the lifetime of claimed messages to
|
|
be at least as long as the lifetime of the claim
|
|
itself, plus the specified grace period. If a claimed
|
|
message normally lives longer than the grace period,
|
|
its expiration is not adjusted. it</para>
|
|
<para>Following are examples of a Claim Messages request
|
|
and response:</para>
|
|
<example>
|
|
<title>cURL Claim Messages Request</title>
|
|
<programlisting language="bash">curl -i -X POST https://queues.api.openstack.org/v1/queues/samplequeue/claims -d \
|
|
'{"ttl": 300,"grace":300}' \
|
|
-H "Content-type: application/json" \
|
|
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
|
|
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
|
|
-H "Accept: application/json" \
|
|
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Claim Messages Response</title>
|
|
<programlisting language="json">HTTP/1.1 201 OK
|
|
Content-Length: 164
|
|
Content-Type: application/json; charset=utf-8
|
|
Location: /v1/queues/samplequeue/claims/51ca011c821e7250f344efd6
|
|
X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>
|
|
|
|
[
|
|
{
|
|
"body": {
|
|
"event": "BackupStarted"
|
|
},
|
|
"age": 124,
|
|
"href": "\/v1\/queues\/samplequeue\/messages\/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6",
|
|
"ttl": 300
|
|
}
|
|
]</programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Delete_messages">
|
|
<title>Delete Message with Claim ID</title>
|
|
<para>The Delete Message operations deletes
|
|
messages.</para>
|
|
<para>The template is as
|
|
follows:<programlisting language="json">DELETE {endpoint}/queues/{queue_name}/messages/{message_id}{?claim_id}
|
|
</programlisting></para>
|
|
<para>The <parameter>message_id</parameter> parameter
|
|
specifies the message to delete.</para>
|
|
<para>The <parameter>claim_id</parameter> parameter
|
|
specifies that the message is deleted only if it has
|
|
the specified claim ID and that claim has not expired.
|
|
This specification is useful for ensuring that only
|
|
one worker processes any given message. When a
|
|
worker's claim expires before it deletes a message
|
|
that it has processed, the worker must roll back any
|
|
actions it took based on that message because another
|
|
worker can now claim and process the same
|
|
message.</para>
|
|
<para>Following are examples of a Delete Message request
|
|
and response:</para>
|
|
<example>
|
|
<title>cURL Delete Message Request</title>
|
|
<programlisting language="bash">curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/messages/51ca00a0c508f154c912b85c?claim_id=51ca011c821e7250f344efd6 \
|
|
-H "Content-type: application/json" \
|
|
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
|
|
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
|
|
-H "Accept: application/json" \
|
|
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Delete Message Response</title>
|
|
<programlisting language="json">HTTP/1.1 204 No Content</programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Delete_claim">
|
|
<title>Release Claim</title>
|
|
<para>The Release Claim operation immediately releases a
|
|
claim, making any remaining, undeleted) messages
|
|
associated with the claim available to other
|
|
workers.</para>
|
|
<para>The template is as follows:</para>
|
|
<programlisting language="json">DELETE {endpoint}/queues/{queue_name}/claims/{claim_id}</programlisting>
|
|
<para>This operation is useful when a worker is performing
|
|
a graceful shutdown, fails to process one or more
|
|
messages, or is taking longer than expected to process
|
|
messages and wants to make the remainder of the
|
|
messages available to other workers.</para>
|
|
<para>Following are examples of a Release Claim request
|
|
and response:</para>
|
|
<example>
|
|
<title>cURL Release Claim Request</title>
|
|
<programlisting language="bash">curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue/claims/51ca011c821e7250f344efd6 \
|
|
-H "Content-type: application/json" \
|
|
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
|
|
-H "Client-ID: e58668fc-26eb-11e3-8270-5b3128d43830" \
|
|
-H "Accept: application/json" \
|
|
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Release Claim Response</title>
|
|
<programlisting language="json">HTTP/1.1 204 No Content</programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Delete_queue">
|
|
<title>Delete Queue</title>
|
|
<para>The Delete Queue operation immediately deletes a
|
|
queue and all of its existing messages.</para>
|
|
<para>The template is as
|
|
follows:<programlisting language="json">DELETE {endpoint}/queues/{queue_name}</programlisting></para>
|
|
<para>Following are examples of a Delete Queue request and
|
|
response:</para>
|
|
<example>
|
|
<title>cURL Delete Queue Request</title>
|
|
<programlisting language="bash">curl -i -X DELETE https://queues.api.openstack.org/v1/queues/samplequeue \
|
|
-H "Content-type: application/json" \
|
|
-H "X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>" \
|
|
-H "Accept: application/json" \
|
|
-H "X-Project-Id: <emphasis role="bold">your_project_ID</emphasis>"</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Delete Queue Response</title>
|
|
<programlisting language="json">HTTP/1.1 204 No Content
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="additional-resources">
|
|
<title>Additional Resources</title>
|
|
<para>For more information about using the API, see the <citetitle>Message Queuing API v1
|
|
Reference</citetitle>. All you need to get started with Message Queuing is the
|
|
getting started guide, the reference, and your Cloud account.</para>
|
|
<para>For information about the OpenStack Zaqar API, see
|
|
<link
|
|
xlink:href="https://wiki.openstack.org/wiki/Zaqar/specs/api/v1"
|
|
>wiki.openstack.org/wiki/Zaqar/specs/api/v1</link>.</para>
|
|
<para>This API uses standard HTTP 1.1 response codes as
|
|
documented at <link
|
|
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
|
|
>www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>.
|
|
</para>
|
|
</chapter>
|
|
<glossary xml:id="glossary-d1e018">
|
|
<title>Glossary</title>
|
|
<glossentry xml:id="claim-d1e017">
|
|
<glossterm>Claim</glossterm>
|
|
<glossdef>
|
|
<para>The process of a worker checking out a message
|
|
to perform a task. Claiming a message prevents
|
|
other workers from attempting to process the same
|
|
messages.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>Claim TTL</glossterm>
|
|
<glossdef>
|
|
<para>Defines how long a message will be in claimed
|
|
state. A message can be claimed by one worker at a
|
|
time.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>Consumer</glossterm>
|
|
<glossdef>
|
|
<para>A server that claims messages from the
|
|
queue.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry xml:id="message-d1e016">
|
|
<glossterm>Message</glossterm>
|
|
<glossdef>
|
|
<para>A task, a notification, or any meaningful data
|
|
that a producer or publisher sends to the queue. A
|
|
message exists until it is deleted by a recipient
|
|
or automatically by the system based on a TTL
|
|
(time-to-live) value.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>Message TTL</glossterm>
|
|
<glossdef>
|
|
<para>Defines how long a message will be accessible.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>Producer </glossterm>
|
|
<glossdef>
|
|
<para>A server or application that sends messages to
|
|
the queue.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>Producer - Consumer</glossterm>
|
|
<glossdef>
|
|
<para>A pattern where each worker application that
|
|
reads the queue has to claim the message in order
|
|
to prevent duplicate processing. Later, when work
|
|
is done, the worker is responsible for deleting
|
|
the message. If message is not deleted in a
|
|
predefined time, it can be claimed by other
|
|
workers.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>Publisher</glossterm>
|
|
<glossdef>
|
|
<para>A server or application that posts messages to
|
|
the queue with the intent to distribute
|
|
information or updates to multiple
|
|
subscribers.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>Publisher - Subscriber</glossterm>
|
|
<glossdef>
|
|
<para>A pattern where all worker applications have
|
|
access to all messages in the queue. Workers
|
|
cannot delete or update messages.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry xml:id="queue-d1e019">
|
|
<glossterm>Queue</glossterm>
|
|
<glossdef>
|
|
<para>The entity that holds messages. Ideally, a queue
|
|
is created per work type. For example, if you want
|
|
to compress files, you would create a queue
|
|
dedicated to this job. Any application that reads
|
|
from this queue would only compress files.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry xml:id="subscriber-d1e018">
|
|
<glossterm>Subscriber</glossterm>
|
|
<glossdef>
|
|
<para>An observer that watches messages like an RSS
|
|
feed but does not claim any messages.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry>
|
|
<glossterm>TTL</glossterm>
|
|
<glossdef>
|
|
<para>Time-to-live value.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry xml:id="worker-d1e018">
|
|
<glossterm>Worker</glossterm>
|
|
<glossdef>
|
|
<para>A client that claims messages from the queue and
|
|
performs actions based on those messages.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
</glossary>
|
|
</book>
|