AMQP 1.0 in Service Bus: request/response-based operations
This topic defines the list of Microsoft Azure Service Bus request/response-based operations. This information is based on the AMQP Management Version 1.0 working draft.
For a detailed wire-level AMQP 1.0 protocol guide, which explains how Service Bus implements and builds on the OASIS AMQP technical specification, see the AMQP 1.0 in Azure Service Bus and Event Hubs protocol guide.
An entity description refers to either a Service Bus QueueDescription Class, TopicDescription Class, or SubscriptionDescription Class object.
Represents a message in Service Bus which is mapped to an AMQP message. The mapping is defined in the Service Bus AMQP protocol guide article.
All the operations described in this document follow a request/response pattern, are scoped to an entity, and require attaching to an entity management node.
Creates a link to the management node for sending requests.
requestLink = session.attach(
role: SENDER,
target: { address: "<entity address>/$management" },
source: { address: ""<my request link unique address>" }
)
Creates a link for receiving responses from the management node.
responseLink = session.attach(
role: RECEIVER,
source: { address: "<entity address>/$management" }
target: { address: "<my response link unique address>" }
)
Transfers a request message.
requestLink.sendTransfer(
Message(
properties: {
message-id: <request id>,
reply-to: "<my response link unique address>"
},
application-properties: {
"operation" -> "<operation>",
},
)
Receives the response message from the response link.
responseMessage = responseLink.receiveTransfer()
The response message will be of the following form.
Message(
properties: {
correlation-id: <request id>
},
application-properties: {
"statusCode" -> <status code>,
"statusDescription" -> <status description>,
},
)
Service Bus entities must be addressed as follows:
Entity type | Address | Example |
|---|---|---|
queue | <queue_name> | “myQueue” “site1/myQueue” |
topic | <topic_name> | “myTopic” “site2/page1/myQueue” |
subscription | <topic_name>/Subscriptions/<subscription_name> | “myTopic/Subscriptions/MySub” |
Extends the lock of a message by the time specified in the entity description.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:renew-lock |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
lock-tokens | array of uuid | Yes | Message lock tokens to renew. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed. |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
expirations | array of timestamp | Yes | Message lock token new expiration corresponding to the request lock tokens. |
Peeks messages without locking.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:peek-message |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
from-sequence-number | long | Yes | Sequence number from which to start peek. |
message-count | int | Yes | Maximum number of messages to peek. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – has more messages 0xcc: No content – no more messages |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
messages | list of maps | Yes | List of messages in which every map represents a message. |
The map representing a message must contain the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
message | array of byte | Yes | AMQP 1.0 wire-encoded message. |
Schedules messages.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:schedule-message |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
messages | list of maps | Yes | List of messages in which every map represents a message. |
The map representing a message must contain the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
message-id | string | Yes | amqpMessage.Properties.MessageId as string |
session-id | string | Yes | amqpMessage.Properties.GroupId as string |
partition-key | string | Yes | amqpMessage.MessageAnnotations.”x-opt-partition-key" |
message | array of byte | Yes | AMQP 1.0 wire-encoded message. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed. |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
sequence-numbers | array of long | Yes | Sequence number of scheduled messages. Sequence number is used to cancel. |
Cancels scheduled messages.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:cancel-scheduled-message |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
sequence-numbers | array of long | Yes | Sequence numbers of scheduled messages to cancel. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed. |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
sequence-numbers | array of long | Yes | Sequence number of scheduled messages. Sequence number is used to cancel. |
Extends the lock of a message by the time specified in the entity description.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:renew-session-lock |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
session-id | string | Yes | Session ID. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – has more messages 0xcc: No content – no more messages |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
expiration | timestamp | Yes | New expiration. |
Peeks session messages without locking.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:peek-message |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
from-sequence-number | long | Yes | Sequence number from which to start peek. |
message-count | int | Yes | Maximum number of messages to peek. |
session-id | string | Yes | Session ID. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – has more messages 0xcc: No content – no more messages |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
messages | list of maps | Yes | List of messages in which every map represents a message. |
The map representing a message must contain the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
message | array of byte | Yes | AMQP 1.0 wire-encoded message. |
Sets the state of a session.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:peek-message |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
session-id | string | Yes | Session ID. |
session-state | array of bytes | Yes | Opaque binary data. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed |
statusDescription | string | No | Description of the status. |
Gets the state of a session.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:get-session-state |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
session-id | string | Yes | Session ID. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
session-state | array of bytes | Yes | Opaque binary data. |
Enumerates sessions on a messaging entity.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:get-message-sessions |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
last-updated-time | timestamp | Yes | Filter to include only sessions updated after a given time. |
skip | int | Yes | Skip a number of sessions. |
top | int | Yes | Maximum number of sessions. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – has more messages 0xcc: No content – no more messages |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
skip | int | Yes | Number of skipped sessions if status code is 200. |
sessions-ids | array of strings | Yes | Array of session IDs if status code is 200. |
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:add-rule |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
rule-name | string | Yes | Rule name, not including subscription and topic names. |
rule-description | map | Yes | Rule description as specified in next section. |
The rule-description map must include the following entries, where sql-filter and correlation-filter are mutually exclusive.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
sql-filter | map | Yes | sql-filter, as specified in the next section. |
correlation-filter | map | Yes | correlation-filter, as specified in the next section. |
sql-rule-action | map | Yes | sql-rule-action, as specified in the next section. |
The sql-filter map must include the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
expression | string | Yes | Sql filter expression. |
The correlation-filter map must include at least one of the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
correlation-id | string | No | |
message-id | string | No | |
to | string | No | |
reply-to | string | No | |
label | string | No | |
session-id | string | No | |
reply-to-session-id | string | No | |
content-type | string | No | |
properties | map | No | Maps to Service Bus BrokeredMessage.Properties. |
The sql-rule-action map must include the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
expression | string | Yes | Sql action expression. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed |
statusDescription | string | No | Description of the status. |
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:remove-rule |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
rule-name | string | Yes | Rule name, not including subscription and topic names. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed |
statusDescription | string | No | Description of the status. |
Receives deferred messages by sequence number.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:receive-by-sequence-number |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
sequence-numbers | array of long | Yes | Sequence numbers. |
receiver-settle-mode | ubyte | Yes | Receiver settle mode as specified in AMQP core v1.0. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed |
statusDescription | string | No | Description of the status. |
The response message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
messages | list of maps | Yes | List of messages where every map represents a message. |
The map representing a message must contain the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
lock-token | uuid | Yes | Lock token if receiver-settle-mode is 1. |
message | array of byte | Yes | AMQP 1.0 wire-encoded message. |
Updates the disposition status of deferred messages.
The request message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
operation | string | Yes | com.microsoft:update-disposition |
com.microsoft:server-timeout | uint | No | Operation server timeout in milliseconds. |
The request message body must consist of an amqp-value section containing a map with the following entries.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
disposition-status | string | Yes | completed abandoned suspended |
lock-tokens | array of uuid | Yes | Message lock tokens to update disposition status. |
deadletter-reason | string | No | May be set if disposition status is set to suspended. |
deadletter-description | string | No | May be set if disposition status is set to suspended. |
properties-to-modify | map | No | List of Service Bus brokered message properties to modify. |
The response message must include the following application properties.
Key | Value Type | Required | Value Contents |
|---|---|---|---|
statusCode | int | Yes | HTTP response code [RFC2616] 200: OK – success, otherwise failed |
statusDescription | string | No | Description of the status. |