e12c65a369
The queue in Zaqar will support to encrypt messages before storing them into storage backends, also could support to decrypt messages when those are claimed by consumer. This feature will enhance the security of messaging service. Implements: blueprint encrypted-messages-in-queue Signed-off-by: wanghao <sxmatch1986@gmail.com> Change-Id: Icecfb9a232cfeefc2f9603934696bb2dcd56bc9c
424 lines
8.5 KiB
HTML
424 lines
8.5 KiB
HTML
===============
|
|
Queues (queues)
|
|
===============
|
|
Queue is a logical entity that groups messages. Ideally a queue is created per
|
|
work type. For example, if you want to compress files, you would create a queue
|
|
dedicated for this job. Any application that reads from this queue would only
|
|
compress files.
|
|
|
|
Nowadays, queue in Zaqar is most like a topic, it's created lazily. User can
|
|
post messages to a queue before creating the queue. Zaqar will create the
|
|
queue/topic automatically.
|
|
|
|
List queues
|
|
===========
|
|
|
|
.. rest_method:: GET /v2/queues
|
|
|
|
Lists queues.
|
|
|
|
A request to list queues when you have no queues in your account returns 204,
|
|
instead of 200, because there was no information to send back.
|
|
|
|
This operation lists queues for the project. The queues are sorted
|
|
alphabetically by name.
|
|
|
|
When queue listing , we can add filter in query string parameter
|
|
to filter queue, like name and metadata. If metadata or name of queue is
|
|
consistent with the filter,the queue will be listed to the user,
|
|
otherwise the queue will be filtered.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 503
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- limit: limit
|
|
- marker: marker
|
|
- detailed: detailed
|
|
- name: name
|
|
- with_count: with_count
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queues: queues
|
|
- links: links
|
|
- count: count
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/queues-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
Create queue
|
|
============
|
|
|
|
.. rest_method:: PUT /v2/queues/{queue_name}
|
|
|
|
Creates a queue.
|
|
|
|
This operation creates a new queue.
|
|
|
|
The body of the request is empty.
|
|
|
|
``queue_name`` is the name that you give to the queue. The name must not
|
|
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
|
underscores, and hyphens.
|
|
|
|
When create queue, user can specify metadata for the queue. Currently, Zaqar
|
|
supports below metadata: _flavor, _max_claim_count, _dead_letter_queue,
|
|
_dead_letter_queue_messages_ttl and _enable_encrypt_messages.
|
|
|
|
In order to support the delayed queues, now add a metadata
|
|
``_default_message_delay``.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 201
|
|
- 204
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 503
|
|
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queue_name: queue_name
|
|
- _dead_letter_queue: _dead_letter_queue
|
|
- _dead_letter_queue_messages_ttl: _dead_letter_queue_messages_ttl
|
|
- _default_message_delay: _default_message_delay
|
|
- _default_message_ttl: _default_message_ttl
|
|
- _flavor: _flavor
|
|
- _max_claim_count: _max_claim_count
|
|
- _max_messages_post_size: _max_messages_post_size
|
|
- _enable_encrypt_messages: _enable_encrypt_messages
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/queue-create-request.json
|
|
:language: javascript
|
|
|
|
|
|
This operation does not return a response body.
|
|
|
|
|
|
Update queue
|
|
============
|
|
|
|
.. rest_method:: PATCH /v2/queues/{queue_name}
|
|
|
|
Updates a queue.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 404
|
|
- 409
|
|
- 503
|
|
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queue_name: queue_name
|
|
|
|
When setting the request body of updating queue, the body must be a list which
|
|
contains a series of json object which follows
|
|
https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10.
|
|
|
|
.. note::
|
|
|
|
- The "Content-Type" header should be
|
|
"application/openstack-messaging-v2.0-json-patch"
|
|
|
|
- The ''path'' must start with /metadata, for example, if the key is
|
|
''ttl'', then the path should be /metadata/ttl
|
|
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/queue-update-request.json
|
|
:language: javascript
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/queue-update-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show queue details
|
|
==================
|
|
|
|
.. rest_method:: GET /v2/queues/{queue_name}
|
|
|
|
Shows details for a queue.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 503
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queue_name: queue_name
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- _max_messages_post_size: _max_messages_post_size
|
|
- _default_message_delay: _default_message_delay_response
|
|
- _default_message_ttl: _default_message_ttl
|
|
- _max_claim_count: _max_claim_count_response
|
|
- _dead_letter_queue: _dead_letter_queue_response
|
|
- _dead_letter_queue_messages_ttl: _dead_letter_queue_messages_ttl_response
|
|
- _enable_encrypt_messages: _enable_encrypt_messages
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/queue-show-response.json
|
|
:language: javascript
|
|
|
|
|
|
Delete queue
|
|
===============
|
|
|
|
.. rest_method:: DELETE /v2/queues/{queue_name}
|
|
|
|
Deletes the specified queue.
|
|
|
|
This operation immediately deletes a queue and all of its existing messages.
|
|
|
|
``queue_name`` is the name that you give to the queue. The name must not
|
|
exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
|
|
underscores, and hyphens.
|
|
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 204
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 503
|
|
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queue_name: queue_name
|
|
|
|
This operation does not accept a request body and does not return a response
|
|
body.
|
|
|
|
|
|
Get queue stats
|
|
===============
|
|
|
|
.. rest_method:: GET /v2/queues/{queue_name}/stats
|
|
|
|
Returns statistics for the specified queue.
|
|
|
|
This operation returns queue statistics, including how many messages are in
|
|
the queue, categorized by status.
|
|
|
|
If the value of the ``total`` attribute is 0, then ``oldest`` and ``newest``
|
|
message statistics are not included in the response.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 503
|
|
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queue_name: queue_name
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/queue-stats-response.json
|
|
:language: javascript
|
|
|
|
|
|
Pre-signed queue
|
|
================
|
|
|
|
.. rest_method:: POST /v2/queues/{queue_name}/share
|
|
|
|
Create a pre-signed URL for a given queue.
|
|
|
|
.. note::
|
|
|
|
In the case of pre-signed URLs, the queue cannot be created lazily. This
|
|
is to prevent cases where queues are deleted and users still have a valid
|
|
URL. This is not a big issues in cases where there's just 1 pool. However,
|
|
if there's a deployment using more than 1 type of pool, the lazily created
|
|
queue may end up in an undesired pool and it'd be possible for an attacker
|
|
to try a DoS on that pool. Therefore, whenever a pre-signed URL is created,
|
|
if a pool doesn't exist, it needs to be created.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 404
|
|
- 503
|
|
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queue_name: queue_name
|
|
- paths: pre_signed_queue_paths
|
|
- methods: pre_signed_queue_methods
|
|
- expires: pre_signed_queue_expires
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/queue-pre-signed-request.json
|
|
:language: javascript
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project: project_id
|
|
- paths: pre_signed_queue_paths
|
|
- methods: pre_signed_queue_methods
|
|
- expires: pre_signed_queue_expires
|
|
- signature: pre_signed_queue_signature
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/queue-pre-signed-response.json
|
|
:language: javascript
|
|
|
|
|
|
Purge queue
|
|
===========
|
|
|
|
.. rest_method:: POST /v2/queues/{queue_name}/purge
|
|
|
|
Purge particular resource of the queue.
|
|
|
|
.. note::
|
|
|
|
Now Zaqar supports to purge "messages" and "subscriptions" resource from
|
|
a queue.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 204
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 503
|
|
|
|
|
|
Request Parameters
|
|
------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- queue_name: queue_name
|
|
- resource_types: resource_types
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/purge-queue-request.json
|
|
:language: javascript
|