zaqarclient(1)

PYTHON-ZAQARCLIENT(1)

python-zaqarclient

PYTHON-ZAQARCLIENT(1)

NAME

python-zaqarclient - python-zaqarclient 2.5.1

Zaqar is a multi-tenant cloud messaging and notification service for web and mobile developers.

The service features a ReST API, which developers can use to send messages between various components of their SaaS and mobile applications, by using a variety of communication patterns. Underlying this API is an efficient messaging engine designed with scalability and security in mind.

Other OpenStack components can integrate with Zaqar to surface events to end users and to communicate with guest agents that run in the "over-cloud" layer.

NOTE:

This documentation is generated by the Sphinx toolkit and lives in the Zaqar project source tree. Additional draft and project documentation regarding Zaqar and other components of OpenStack can be found on the OpenStack Wiki, as well as in the user guides found on docs.openstack.org.

Client

A Client is a high-level abstraction on top of Zaqar features. It exposes the server features with an object-oriented interface, which encourages dot notation and automatic, but lazy, resources allocation. A Client allows you to control everything, from public interfaces to admin endpoints.

To create a Client instance, you supply an url pointing to the server and a version number:

from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/', version=2)

which will load the appropriate client based on the specified version. Optionally, you can also supply a config dictionary:

from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/',


                    version=2, conf={})

The arguments passed to this function will be passed to the client instances as well.

It's recommended to use Client instances instead of accessing the lower level API as it has been designed to ease the interaction with the server and it gives enough control for the most common cases.

A simple example for accessing an existing queue through a client instance - based on the API v2 - would look like:

from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/', version=2)
queue = cli.queue('my_queue')

Through the queue instance will be then possible to access all the features associated with the queue itself like posting messages, getting message and deleting messages.

As mentioned previously in this documentation, a client instance allows you to also access admin endpoints, for example:

from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/', version=2)
flavor = cli.flavor('tasty',


                    pool='my-pool-group',


                    auto_create=True)
flavor.delete()

Client uses the lower-level API to access the server, which means anything you can do with this client instance can be done by accessing the underlying API, although not recommended.

Client Object Reference

This is the reference documentation for all API version.

API v1 and v1.1:

class Client(url=None, version=1, conf=None, session=None): Client base class

Parameters

url (six.text_type) -- Zaqar's instance base url.
version (int) -- API Version pointing to.
conf (oslo_config.cfg.CONF) -- CONF object.
session -- keystone session. But it's just place holder, we wont' support it in v1.

flavor(ref, **kwargs): Returns a flavor instance

Parameters: ref (six.text_type) -- Flavor's reference name.
Returns: A flavor instance
Return type: flavor.Flavor

flavors(**params): Gets a list of flavors from the server

Parameters: params (dict.) -- Filters to use for getting flavors
Returns: A list of flavors
Return type: list

follow(ref): Follows ref.
This method instanciates a new request instance and requests ref. It is intended to be used to follow a reference href gotten from links sections in responses like queues' lists.

Params ref: The reference path.

health(): Gets the health status of Zaqar server.

pool(ref, **kwargs): Returns a pool instance

Parameters: ref (six.text_type) -- Pool's reference name.
Returns: A pool instance
Return type: pool.Pool

pools(**params): Gets a list of pools from the server

Parameters: params (dict.) -- Filters to use for getting pools
Returns: A list of pools
Return type: list

queue(ref, **kwargs): Returns a queue instance

Parameters: ref (six.text_type) -- Queue's reference id.
Returns: A queue instance
Return type: queues.Queue

queues(**params): Gets a list of queues from the server

Returns: A list of queues
Return type: list

transport(): Gets a transport based the api url and version.

Return type: zaqarclient.transport.base.Transport

API v2.0:

class Client(url=None, version=2, conf=None, session=None): Client base class

Parameters

url (six.text_type) -- Zaqar's instance base url.
version (int) -- API Version pointing to.
conf (oslo_config.cfg.CONF) -- CONF object.

health(): Gets the detailed health status of Zaqar server.

homedoc(): Get the detailed resource doc of Zaqar server

ping(): Gets the health status of Zaqar server.

queue(ref, **kwargs): Returns a queue instance

Parameters: ref (six.text_type) -- Queue's reference id.
Returns: A queue instance
Return type: queues.Queue

queues(**params): Gets a list of queues from the server

Returns: A list of queues
Return type: list

subscription(queue_name, **kwargs): Returns a subscription instance

Parameters: queue_name (six.text_type) -- Name of the queue to subscribe to.
Returns: A subscription instance
Return type: subscription.Subscription

subscriptions(queue_name, **params): Gets a list of subscriptions from the server

Parameters: params (dict.) -- Filters to use for getting subscriptions
Returns: A list of subscriptions
Return type: list

Command-line

This chapter documents the usage of Zaqar Client Command Line with API v2.0.

Zaqar client now support some kinds of resources or actions: queue, message, claim, subscription, pool, flavor, ping, health.

Click the Link below for the details.

Queue

For help on a specific openstack messaging queue command, enter:

$ openstack messaging queue COMMAND -h/--help

The fourteen commands:

messaging queue create
messaging queue delete
messaging queue get metadata
messaging queue list
messaging queue set metadata
messaging queue signed url
messaging queue stats

openstack messaging queue create

usage: openstack messaging queue create [-h] [-f {json,shell,table,value,yaml}]


                                        [-c COLUMN] [--max-width <integer>] [--noindent]


                                        [--prefix PREFIX]


                                        <queue_name>

Create a queue.

Positional arguments:

<queue_name>: Name of the queue.

openstack messaging queue delete

usage: openstack messaging queue delete [-h] <queue_name>

Delete a queue.

Positional arguments:

<queue_name>: Name of the queue.

openstack messaging queue get metadata

usage: openstack messaging queue get metadata [-h] [-f {json,shell,table,value,yaml}]


                                              [-c COLUMN] [--max-width <integer>]


                                              [--noindent] [--prefix PREFIX]


                                              <queue_name>

Get queue metadata.

Positional arguments:

<queue_name>: Name of the queue.

openstack messaging queue list

usage: openstack messaging queue list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]


                                      [--max-width <integer>] [--noindent]


                                      [--quote {all,minimal,none,nonnumeric}]


                                      [--marker <queue_id>] [--limit <limit>]


                                      [--detailed]

List available queues.

Optional arguments:

--marker <queue_id>: Queue's paging marker.
--limit <limit>: Page size limit.
--detailed: If show detailed information of queue.

openstack messaging queue set metadata

usage: openstack messaging queue set metadata [-h] <queue_name> <queue_metadata>

Set queue metadata.All the metadata of the queue will be replaced by queue_metadata.

Positional arguments:

<queue_name>: Name of the queue.
<queue_metadata>: Queue metadata. It should be json like. For example: '{"age": 18}'

openstack messaging queue signed url

usage: openstack messaging queue signed url [-h] [-f {json,shell,table,value,yaml}]


                                            [-c COLUMN] [--max-width <integer>]


                                            [--noindent] [--prefix PREFIX]


                                            [--paths <paths>]


                                            [--ttl-seconds <ttl_seconds>]


                                            [--methods <methods>]


                                            <queue_name>

Create a pre-signed url for the queue.

Positional arguments:

<queue_name>: Name of the queue.

Optional arguments:

--paths <paths>: Allowed paths in a comma-separated list. Options: messages, subscriptions, claims.
--ttl-seconds <ttl_seconds>: Length of time (in seconds) until the signature expires.
--methods <methods>: HTTP methods to allow as a comma-separated list. Options: GET, HEAD, OPTIONS, POST, PUT, DELETE.

openstack messaging queue stats

usage: openstack messaging queue stats [-h] [-f {json,shell,table,value,yaml}]


                                       [-c COLUMN] [--max-width <integer>] [--noindent]


                                       [--prefix PREFIX]


                                       <queue_name>

Get queue stats.

Positional arguments:

<queue_name>: Name of the queue.

openstack messaging queue purge

usage: openstack messaging queue purge [-h] [--resource_types <resource_types>]


                                       <queue_name>

Purge a queue. All the metadata of the queue will be kept. Use --resource_types to specify which resource should be pured. If --resource_types is not specified, all the messages and subscriptions in the queue will be purged by default.

Positional arguments:

<queue_name>: Name of the queue.

Optional arguments:

--resource_types <resource_types>: Resource types want to be purged. Support messages and subscriptions.

Health

For help on a specific openstack messaging message command, enter:

$ openstack messaging message COMMAND -h/--help

The one command:

messaging message list
messaging message post

openstack messaging message list

usage: openstack messaging message list [-h] [-f {csv,json,table,value,yaml}]


                                     [-c COLUMN]


                                     [--quote {all,minimal,none,nonnumeric}]


                                     [--noindent] [--max-width <integer>]


                                     [--fit-width] [--print-empty]


                                     [--sort-column SORT_COLUMN]


                                     [--message-ids <message_ids>]


                                     [--limit <limit>] [--echo]


                                     [--include-claimed]


                                     [--include-delayed]


                                     [--client-id <client_id>]


                                     <queue_name>

List all of the messages in a queue.

Positional arguments:

<queue_name>: Name of the queue.

openstack messaging message post

usage: openstack messaging message post [-h] [--client-id <client_id>]


                                     <queue_name> <messages>

Post the messages to a queue.

Positional arguments:

<queue_name>: Name of the queue.
<messages>: messages. It should be json like. For example: '[{"body": "msg", "ttl": 60}]'

Claim

For help on a specific openstack messaging claim command, enter:

$ openstack messaging claim COMMAND -h/--help

The eight commands:

messaging claim create
messaging claim query
messaging claim release
messaging claim renew

openstack messaging claim create

usage: openstack messaging claim create [-h] [-f {csv,json,table,value,yaml}]


                                        [-c COLUMN] [--max-width <integer>] [--noindent]


                                        [--quote {all,minimal,none,nonnumeric}]


                                        [--ttl <ttl>] [--grace <grace>]


                                        [--limit <limit>]


                                        <queue_name>

Create claim and return a list of claimed messages.

Positional arguments:

<queue_name>: Name of the queue to be claim.

Optional arguments:

--ttl <ttl>: Time to live in seconds for claim.
--grace <grace>: The message grace period in seconds.
--limit <limit>: Claims a set of messages, up to limit.

openstack messaging claim query

usage: openstack messaging claim query [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]


                                       [--max-width <integer>] [--noindent]


                                       [--quote {all,minimal,none,nonnumeric}]


                                       <queue_name> <claim_id>

Display claim details.

Positional arguments:

<queue_name>: Name of the claimed queue.
<claim_id>: ID of the claim.

openstack messaging claim release

usage: openstack messaging claim release [-h] <queue_name> <claim_id>

Delete a claim.

Positional arguments:

<queue_name>: Name of the claimed queue.
<claim_id>: Claim ID to delete.

openstack messaging claim renew

usage: openstack messaging claim renew [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]


                                       [--max-width <integer>] [--noindent]


                                       [--quote {all,minimal,none,nonnumeric}]


                                       [--ttl <ttl>] [--grace <grace>]


                                       <queue_name> <claim_id>

Renew a claim.

Positional arguments:

<queue_name>: Name of the claimed queue.
<claim_id>: Claim ID.

Optional arguments:

--ttl <ttl>: Time to live in seconds for claim.
--grace <grace>: The message grace period in seconds.

Pool

For help on a specific openstack messaging pool command, enter:

$ openstack messaging pool COMMAND -h/--help

The ten commands:

messaging pool create
messaging pool delete
messaging pool list
messaging pool show
messaging pool update

openstack messaging pool create

usage: openstack messaging pool create [-h] [-f {json,shell,table,value,yaml}]


                                       [-c COLUMN] [--max-width <integer>] [--noindent]


                                       [--prefix PREFIX] [--pool_group <pool_group>]


                                       [--pool_options <pool_options>]


                                       <pool_name> <pool_uri> <pool_weight>

Create a pool.

Positional arguments:

<pool_name>: Name of the pool.
<pool_uri>: Storage engine URI.
<pool_weight>: weight of the pool.

Optional arguments:

--pool_group <pool_group>: Group of the pool.
--pool_options <pool_options>: An optional request component related to storage-specific options.

openstack messaging pool delete

usage: openstack messaging pool delete [-h] <pool_name>

Delete a pool.

Positional arguments:

<pool_name>: Name of the pool.

openstack messaging pool list

usage: openstack messaging pool list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]


                                     [--max-width <integer>] [--noindent]


                                     [--quote {all,minimal,none,nonnumeric}]


                                     [--marker <pool_name>] [--limit <limit>]


                                     [--detailed <detailed>]

List available Pools.

Optional arguments:

--marker <pool_name>: Pool's paging marker.
--limit <limit>: Page size limit.
--detailed <detailed>: Detailed output.

openstack messaging pool show

usage: openstack messaging pool show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]


                                     [--max-width <integer>] [--noindent]


                                     [--prefix PREFIX]


                                     <pool_name>

Display pool details.

Positional arguments:

<pool_name>: Pool to display (name).

openstack messaging pool update

usage: openstack messaging pool update [-h] [-f {json,shell,table,value,yaml}]


                                       [-c COLUMN] [--max-width <integer>] [--noindent]


                                       [--prefix PREFIX] [--pool_uri <pool_uri>]


                                       [--pool_weight <pool_weight>]


                                       [--pool_group <pool_group>]


                                       [--pool_options <pool_options>]


                                       <pool_name>

Update a pool attribute.

Positional arguments:

<pool_name>: Name of the pool.

Optional arguments:

--pool_uri <pool_uri>: Storage engine URI.
--pool_weight <pool_weight>: Weight of the pool.
--pool_group <pool_group>: Group of the pool.
--pool_options <pool_options>: An optional request component related to storage-specific options.

Flavor

For help on a specific openstack messaging flavor command, enter:

$ openstack messaging flavor COMMAND -h/--help

The five commands:

messaging flavor create
messaging flavor delete
messaging flavor list
messaging flavor show
messaging flavor update

openstack messaging flavor create

usage: openstack messaging flavor create [-h]


                                         [-f {json,shell,table,value,yaml}]


                                         [-c COLUMN] [--max-width <integer>]


                                         [--noindent] [--prefix PREFIX]


                                         [--capabilities <capabilities>]


                                         <flavor_name> <pool_group>

Create a pool flavor.

Positional arguments:

<flavor_name>: Name of the flavor.
<pool_group>: Pool group for flavor.

Optional arguments:

--capabilities <capabilities>: Describes flavor-specific capabilities, This option is only available in client api version < 2.

openstack messaging flavor delete

usage: openstack messaging flavor delete [-h] <flavor_name>

Delete a pool flavor.

Positional arguments:

<flavor_name>: Name of the flavor.

openstack messaging flavor list

usage: openstack messaging flavor list [-h] [-f {csv,json,table,value,yaml}]


                                       [-c COLUMN] [--max-width <integer>]


                                       [--noindent]


                                       [--quote {all,minimal,none,nonnumeric}]


                                       [--marker <flavor_name>]


                                       [--limit <limit>]


                                       [--detailed <detailed>]

List available pool flavors.

Optional arguments:

--marker <flavor_name>: Flavor's paging marker.
--limit <limit>: Page size limit.
--detailed <detailed>: If show detailed capabilities of flavor.

openstack messaging flavor show

usage: openstack messaging flavor show [-h] [-f {json,shell,table,value,yaml}]


                                       [-c COLUMN] [--max-width <integer>]


                                       [--noindent] [--prefix PREFIX]


                                       <flavor_name>

Display flavor details.

Positional arguments:

<flavor_name>: Flavor to display (name).

openstack messaging flavor update

usage: openstack messaging flavor update [-h]


                                         [-f {json,shell,table,value,yaml}]


                                         [-c COLUMN] [--max-width <integer>]


                                         [--noindent] [--prefix PREFIX]


                                         [--pool_group <pool_group>]


                                         [--capabilities <capabilities>]


                                         <flavor_name>

Update a pool flavor's attributes.

Positional arguments:

<flavor_name>: Name of the flavor.

Optional arguments:

--pool_group <pool_group>: Pool group the flavor sits on.
--capabilities <capabilities>: Describes flavor-specific capabilities.

Ping

For help on a specific openstack messaging ping command, enter:

$ openstack messaging ping COMMAND -h/--help

The one command:

messaging ping

openstack messaging ping

usage: openstack messaging ping [-h] [-f {json,shell,table,value,yaml}]


                                [-c COLUMN] [--max-width <integer>]


                                [--noindent] [--prefix PREFIX]

Check if Zaqar server is alive or not.

Health

For help on a specific openstack messaging health command, enter:

$ openstack messaging health COMMAND -h/--help

The one command:

messaging health

openstack messaging health

usage: openstack messaging health [-h]

Display detailed health status of Zaqar server.

Subscription

For help on a specific openstack messaging subscription command, enter:

$ openstack messaging subscription COMMAND -h/--help

The ten commands:

messaging subscription create
messaging subscription delete
messaging subscription list
messaging subscription show
messaging subscription update

openstack messaging subscription create

usage: openstack messaging subscription create [-h] [-f {json,shell,table,value,yaml}]


                                               [-c COLUMN] [--max-width <integer>]


                                               [--noindent] [--prefix PREFIX]


                                               [--options <options>]


                                               <queue_name> <subscriber> <ttl>

Create a subscription.

Positional arguments:

<queue_name>: Name of the queue.
<subscriber>: Subscriber which will be notified.
<ttl>: Time to live of the subscription in seconds.

openstack messaging subscription delete

usage: openstack messaging subscription delete [-h] <queue_name> <subscription_id>

Delete a subscription.

Positional arguments:

<queue_name>: Name of the queue.
<subscription_id>: ID of the subscription.

openstack messaging subscription list

usage: openstack messaging subscription list [-h] [-f {csv,json,table,value,yaml}]


                                             [-c COLUMN] [--max-width <integer>]


                                             [--noindent]


                                             [--quote {all,minimal,none,nonnumeric}]


                                             [--marker <subscription_id>]


                                             [--limit <limit>]


                                             <queue_name>

Get list of subscriptions.

Positional arguments:

<queue_name>: Name of the queue.

openstack messaging subscription show

usage: openstack messaging subscription show [-h] [-f {json,shell,table,value,yaml}]


                                             [-c COLUMN] [--max-width <integer>]


                                             [--noindent] [--prefix PREFIX]


                                             <queue_name> <subscription_id>

Query a subscription details.

Positional arguments:

<queue_name>: Name of the queue.
<subscription_id>: ID of the subscription.

openstack messaging subscription update

usage: openstack messaging subscription update [-h] [-f {json,shell,table,value,yaml}]


                                               [-c COLUMN] [--max-width <integer>]


                                               [--noindent] [--prefix PREFIX]


                                               [--subscriber <subscriber>] [--ttl <ttl>]


                                               [--options <options>]


                                               <queue_name> <subscription_id>

Update a subscription.

Positional arguments:

<queue_name>: Name of the queue.
<subscription_id>: ID of the subscription

Optional arguments:

--subscriber <subscriber>: Subscriber which will be notified.
--ttl <ttl>: Time to live of the subscription in seconds.
--options <options>: Metadata of the subscription in JSON format.

RELEASE NOTES

New Release Note

We use reno to publish the release note now. Please see Release Page for more detail.

0.2.0

1934a98 Updated from global requirements
863371b Allow for authentication in functional tests
b35689d Don't pass options to pool creation
8104ff4 Don't reuse request and transport instances
bf841b5 Pass group in pool's functional tests
2490ed4 Send claims limit as a query param
baf6fa7 v1.1 and v2 claims return document not list
0d80728 Make sure the API version is passed down
407925c Make v1.1 the default CLI version
895aad2 Updated from global requirements
8a81c44 Updated from global requirements
705ee75 Implement CLI support for flavor
32a847e Implements CLI for pool
964443d Raises an error if the queue name is empty
e9a8d01 Added support to pools and flavors
f46979b Removed deprecated 'shard' methods
1a85f83 Update README to work with release tools

0.1.1

Fix handling of 1.1 API
Gets 'flavor' data if the resource exists
Gets 'pool' data if the resource exists
Handling exception on 504 Error
Added i18n support
Makes health return True or False
Add reference docs for latest recommended client
Add docs for Client instances
Add a read-only property for Queues

Indices and tables

Index
Module Index
Search Page

AUTHOR

unknown

COPYRIGHT

2010-present, OpenStack Foundation

October 20, 2023

2.5.1

zaqarclient(1)

NAME

CONTENTS

Client

Client Object Reference

Command-line

Queue

openstack messaging queue create

openstack messaging queue delete

openstack messaging queue get metadata

openstack messaging queue list

openstack messaging queue set metadata

openstack messaging queue signed url

openstack messaging queue stats

openstack messaging queue purge

Health

openstack messaging message list

openstack messaging message post

Claim

openstack messaging claim create

openstack messaging claim query

openstack messaging claim release

openstack messaging claim renew

Pool

openstack messaging pool create

openstack messaging pool delete

openstack messaging pool list

openstack messaging pool show

openstack messaging pool update

Flavor

openstack messaging flavor create

openstack messaging flavor delete

openstack messaging flavor list

openstack messaging flavor show

openstack messaging flavor update

Ping

openstack messaging ping

Health

openstack messaging health

Subscription

openstack messaging subscription create

openstack messaging subscription delete

openstack messaging subscription list

openstack messaging subscription show

openstack messaging subscription update

RELEASE NOTES

New Release Note

0.2.0

0.1.1

Indices and tables

AUTHOR

COPYRIGHT