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:: versions.inc
|
||||||
.. include:: queues.inc
|
.. include:: queues.inc
|
||||||
|
.. include:: messages.inc
|
||||||
.. include:: claims.inc
|
.. include:: claims.inc
|
||||||
.. include:: subscription.inc
|
.. include:: subscription.inc
|
||||||
.. include:: health.inc
|
.. include:: health.inc
|
||||||
|
|||||||
328
api-ref/source/messages.inc
Normal file
328
api-ref/source/messages.inc
Normal file
@ -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
|
type: UUID
|
||||||
in: header
|
in: header
|
||||||
description: |
|
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 #######################################################
|
#### variables in path #######################################################
|
||||||
|
|
||||||
@ -67,6 +73,42 @@ claim_limit:
|
|||||||
meaning the server may claim and return less than the requested number of
|
meaning the server may claim and return less than the requested number of
|
||||||
messages.
|
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 ####################################################
|
#### variables in request ####################################################
|
||||||
|
|
||||||
claim_ttl:
|
claim_ttl:
|
||||||
@ -209,6 +251,19 @@ _default_message_ttl:
|
|||||||
one of the ``reserved attributes`` of Zaqar queues. The value will be
|
one of the ``reserved attributes`` of Zaqar queues. The value will be
|
||||||
reverted to the default value after deleting it explicitly.
|
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:
|
subscriptions:
|
||||||
type: list
|
type: list
|
||||||
in: body
|
in: body
|
||||||
|
|||||||
15
api-ref/source/samples/messages-get-byids-response.json
Normal file
15
api-ref/source/samples/messages-get-byids-response.json
Normal file
@ -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
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
11
api-ref/source/samples/messages-get-response.json
Normal file
11
api-ref/source/samples/messages-get-response.json
Normal file
@ -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
|
||||||
|
}
|
||||||
32
api-ref/source/samples/messages-list-response.json
Normal file
32
api-ref/source/samples/messages-list-response.json
Normal file
@ -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"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
18
api-ref/source/samples/messages-post-request.json
Normal file
18
api-ref/source/samples/messages-post-request.json
Normal file
@ -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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
6
api-ref/source/samples/messages-post-response.json
Normal file
6
api-ref/source/samples/messages-post-response.json
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
{
|
||||||
|
"resources": [
|
||||||
|
"/v2/queues/demoqueue/messages/51db6f78c508f17ddc924357",
|
||||||
|
"/v2/queues/demoqueue/messages/51db6f78c508f17ddc924358"
|
||||||
|
]
|
||||||
|
}
|
||||||
Loading…
x
Reference in New Issue
Block a user