Support `messages` API ref
Co-Authored-By: Kevin_Zheng <zhengzhenyu@huawei.com> Co-Authored-By: Fei Long Wang <flwang@catalyst.net.nz> Change-Id: If3fcb6594bc81736474875d5e1db0b465c6d750e
This commit is contained in:
Fei Long Wang
parent
28cc17109b
commit
930a075f96
|
|
@ -19,6 +19,7 @@ Messaging Service API v2 (CURRENT)
|
|||
|
||||
.. include:: versions.inc
|
||||
.. include:: queues.inc
|
||||
.. include:: messages.inc
|
||||
.. include:: claims.inc
|
||||
.. include:: subscription.inc
|
||||
.. include:: health.inc
|
||||
|
|
|
|||
|
|
@ -0,0 +1,328 @@
|
|||
===================
|
||||
Messages (messages)
|
||||
===================
|
||||
|
||||
Post Message
|
||||
============
|
||||
|
||||
.. rest_method:: POST /v2/queues/{queue_name}/messages
|
||||
|
||||
Posts the message or messages for the specified queue.
|
||||
|
||||
This operation posts the specified message or messages.
|
||||
|
||||
You can submit up to 10 messages in a single request, but you must always
|
||||
encapsulate the messages in a collection container (an array in JSON, even
|
||||
for a single message - without the JSON array, you receive the "Invalid request
|
||||
body" message). The resulting value of the Location header or response body
|
||||
might be used to retrieve the created messages for further processing.
|
||||
|
||||
The client specifies only the body and TTL for the message. The server inserts
|
||||
metadata, such as ID and age.
|
||||
|
||||
The response body contains a list of resource paths that correspond to each
|
||||
message submitted in the request, in the order of the messages. If a
|
||||
server-side error occurs during the processing of the submitted messages, a
|
||||
partial list is returned, the partial attribute is set to true, and the client
|
||||
tries to post the remaining messages again. If the server cannot enqueue any
|
||||
messages, the server returns a ``503 Service Unavailable`` error message.
|
||||
|
||||
The ``body`` attribute specifies an arbitrary document that constitutes the
|
||||
body of the message being sent.
|
||||
|
||||
.The following rules apply for the maximum size:
|
||||
|
||||
The maximum size of posted messages is the maximum size of the entire request
|
||||
document (rather than the sum of the individual message body field values as
|
||||
it was in earlier releases). On error, the client will now be notified of how
|
||||
much it exceeded the limit.
|
||||
|
||||
The size is limited to 256 KB, including whitespace.
|
||||
|
||||
The document must be valid JSON. (The Message Queuing service validates it.)
|
||||
|
||||
The ``ttl`` attribute specifies how long the server waits before marking the
|
||||
message as expired and removing it from the queue. The value of ``ttl`` must
|
||||
be between 60 and 1209600 seconds (14 days). Note that the server might not
|
||||
actually delete the message until its age has reached up to (ttl + 60) seconds,
|
||||
to allow for flexibility in storage implementations.
|
||||
|
||||
|
||||
Normal response codes: 201
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
|
||||
Request Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/message-post-request.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- resources: messages_resources
|
||||
|
||||
Response Example
|
||||
---------------
|
||||
|
||||
.. literalinclude:: samples/message-post-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
List Messages
|
||||
=============
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/messages
|
||||
|
||||
List the messages in the specified queue.
|
||||
|
||||
A request to list messages when the queue is not found or when messages are
|
||||
not found returns 204, instead of 200, because there was no information to
|
||||
send back. Messages with malformed IDs or messages that are not found by ID
|
||||
are ignored.
|
||||
|
||||
This operation gets the message or messages in the specified queue.
|
||||
|
||||
Message IDs and markers are opaque strings. Clients should make no assumptions
|
||||
about their format or length. Furthermore, clients should assume that there is
|
||||
no relationship between markers and message IDs (that is, one cannot be derived
|
||||
from the other). This allows for a wide variety of storage driver
|
||||
implementations.
|
||||
|
||||
Results are ordered by age, oldest message first.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- marker: marker
|
||||
- limit: limit
|
||||
- echo: echo
|
||||
- include_claimed: include_claimed
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- messages: messages
|
||||
- links: links
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/messages-list-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Get A Set Of Messages By Id
|
||||
===========================
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/messages?ids={ids}
|
||||
|
||||
Gets a specified set of messages from the specified queue.
|
||||
|
||||
This operation provides a more efficient way to query multiple messages
|
||||
compared to using a series of individual ``GET`` s. Note that the list of IDs
|
||||
cannot exceed 20. If a malformed ID or a nonexistent message ID is provided,
|
||||
it is ignored, and the remaining messages are returned.
|
||||
|
||||
Unlike the Get Messages operation, a client's own messages are always returned
|
||||
in this operation. If you use the ids parameter, the echo parameter is not used
|
||||
and is ignored if it is specified.
|
||||
|
||||
The message attributes are defined as follows: ``href`` is an opaque relative
|
||||
URI that the client can use to uniquely identify a message resource and
|
||||
interact with it. ``ttl`` is the TTL that was set on the message when it was
|
||||
posted. The message expires after (ttl - age) seconds. ``age`` is the number
|
||||
of seconds relative to the server's clock. ``body`` is the arbitrary document
|
||||
that was submitted with the original request to post the message.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- ids: ids
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- messages: messages
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/messages-get-byids-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete A Set Of Messages By Id
|
||||
==============================
|
||||
|
||||
.. rest_method:: DELETE /v2/queues/{queue_name}/messages?ids={ids}
|
||||
|
||||
Provides a bulk delete for messages.
|
||||
|
||||
This operation immediately deletes the specified messages. If any of the
|
||||
message IDs are malformed or non-existent, they are ignored. The remaining
|
||||
valid messages IDs are deleted.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- ids: ids
|
||||
- pop: pop
|
||||
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
|
||||
|
||||
Get A Specific Message
|
||||
======================
|
||||
|
||||
.. rest_method:: GET /v2/queues/{queue_name}/messages/{messageId}
|
||||
|
||||
Gets the specified message from the specified queue.
|
||||
|
||||
This operation gets the specified message from the specified queue.
|
||||
|
||||
If either the message ID is malformed or nonexistent, no message is returned.
|
||||
|
||||
Message fields are defined as follows: ``href`` is an opaque relative URI that
|
||||
the client can use to uniquely identify a message resource and interact with
|
||||
it. ``ttl`` is the TTL that was set on the message when it was posted. The
|
||||
message expires after (ttl - age) seconds. ``age`` is the number of seconds
|
||||
relative to the server's clock. ``body`` is the arbitrary document that was
|
||||
submitted with the original request to post the message.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
|
||||
Request Parameters
|
||||
------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- message_id: message_id
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/messages-get-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Delete A Specific Message
|
||||
=========================
|
||||
|
||||
.. rest_method:: DELETE /v2/queues/{queue_name}/messages/{messageId}
|
||||
|
||||
Deletes the specified message from the specified queue.
|
||||
|
||||
This operation immediately deletes the specified message.
|
||||
|
||||
The ``claim_id`` 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 only one worker processes any given message. When a
|
||||
worker's claim expires before it can delete 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.
|
||||
|
||||
If you do not specify ``claim_id``, but the message is claimed, the operation
|
||||
fails. You can only delete claimed messages by providing an appropriate
|
||||
``claim_id``.
|
||||
|
||||
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error response codes:
|
||||
|
||||
- BadRequest (400)
|
||||
- Unauthorized (401)
|
||||
- Not Found (404)
|
||||
- ServiceUnavailable (503)
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- queue_name: queue_name
|
||||
- messageId: messageId
|
||||
|
||||
This operation does not accept a request body and does not return a response
|
||||
body.
|
||||
|
||||
|
|
@ -4,7 +4,13 @@ client_id:
|
|||
type: UUID
|
||||
in: header
|
||||
description: |
|
||||
A unique ID for indicating where the request come from.
|
||||
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. Note: All
|
||||
message-related operations require the use of ``Client-ID`` in the headers
|
||||
to ensure that messages are not echoed back to the client that posted
|
||||
them, unless the client explicitly requests this.
|
||||
|
||||
#### variables in path #######################################################
|
||||
|
||||
|
|
@ -67,6 +73,42 @@ claim_limit:
|
|||
meaning the server may claim and return less than the requested number of
|
||||
messages.
|
||||
|
||||
echo:
|
||||
type: boolean
|
||||
in: query
|
||||
required: false
|
||||
description:
|
||||
Indicate if the messages can be echoed back to the client that posted
|
||||
them.
|
||||
|
||||
include_claimed:
|
||||
type: boolean
|
||||
in: query
|
||||
required: false
|
||||
description:
|
||||
Indicate if the messages list should include the claimed messages.
|
||||
|
||||
ids:
|
||||
type: list
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
A list of the messages ids. ``pop`` & ``ids`` parameters are mutually
|
||||
exclusive. Using them together in a request will result in HTTP 400.
|
||||
|
||||
NOTE: Actually, it's not a real list, it's string combined with many
|
||||
message ids separated with comma, for example:
|
||||
/messages?ids=578f0055508f153f256f717e,578f0055508f153f256f717f
|
||||
|
||||
pop:
|
||||
type: integer
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
The ``pop`` specifies how many messages will be popped up from the queue.
|
||||
``pop`` & ``ids`` parameters are mutually exclusive. Using them together
|
||||
in a request will result in HTTP 400.
|
||||
|
||||
#### variables in request ####################################################
|
||||
|
||||
claim_ttl:
|
||||
|
|
@ -209,6 +251,19 @@ _default_message_ttl:
|
|||
one of the ``reserved attributes`` of Zaqar queues. The value will be
|
||||
reverted to the default value after deleting it explicitly.
|
||||
|
||||
messages:
|
||||
type: list
|
||||
in: body
|
||||
required: True
|
||||
description: |
|
||||
A list of the messages.
|
||||
|
||||
messages_resources:
|
||||
type: list
|
||||
in: body
|
||||
description: |
|
||||
A list of the URL to messages.
|
||||
|
||||
subscriptions:
|
||||
type: list
|
||||
in: body
|
||||
|
|
|
|||
|
|
@ -0,0 +1,15 @@
|
|||
{
|
||||
"messages": [
|
||||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 443,
|
||||
"href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
|
||||
"id": "578f0055508f153f256f717f",
|
||||
"ttl": 3600
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 1110,
|
||||
"href": "/v2/queues/beijing/messages/578f0055508f153f256f717f",
|
||||
"id": "578f0055508f153f256f717f",
|
||||
"ttl": 3600
|
||||
}
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
{
|
||||
"messages": [
|
||||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 482,
|
||||
"href": "/v2/queues/beijing/messages/578edfe6508f153f256f717b",
|
||||
"id": "578edfe6508f153f256f717b",
|
||||
"ttl": 3600
|
||||
},
|
||||
{
|
||||
"body": {
|
||||
"current_bytes": "0",
|
||||
"event": "BackupProgress",
|
||||
"total_bytes": "99614720"
|
||||
},
|
||||
"age": 456,
|
||||
"href": "/v2/queues/beijing/messages/578ee000508f153f256f717d",
|
||||
"id": "578ee000508f153f256f717d",
|
||||
"ttl": 3600
|
||||
}
|
||||
],
|
||||
"links": [
|
||||
{
|
||||
"href": "/v2/queues/beijing/messages?marker=17&echo=true",
|
||||
"rel": "next"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
{
|
||||
"messages": [
|
||||
{
|
||||
"ttl": 300,
|
||||
"body": {
|
||||
"event": "BackupStarted",
|
||||
"backup_id": "c378813c-3f0b-11e2-ad92-7823d2b0f3ce"
|
||||
}
|
||||
},
|
||||
{
|
||||
"body": {
|
||||
"event": "BackupProgress",
|
||||
"current_bytes": "0",
|
||||
"total_bytes": "99614720"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
{
|
||||
"resources": [
|
||||
"/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357",
|
||||
"/v2/queues/demoqueue/messages/51db6f78c508f17ddc924358"
|
||||
]
|
||||
}
|
||||
Loading…
Reference in New Issue