AMQP 1.0 in Azure Service Bus: request-response-based operations

  • Article

This article defines the list of 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.

Concepts

ServiceBusReceivedMessage / ServiceBusMessage

Represents a message in Service Bus, which is mapped to an AMQP message. The mapping is defined in the Service Bus AMQP protocol guide.

Attach to entity management node

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>" }
)

Transfer a request message

Transfers a request message.
A transaction-state can be added optionally for operations that support transactions.

requestLink.sendTransfer(
        Message(
                properties: {
                        message-id: <request id>,
                        reply-to: "<my response link unique address>"
                },
                application-properties: {
                        "operation" -> "<operation>",
                }
        ),
        [Optional] State = transactional-state: {
                txn-id: <txn-id>
        }
)

Receive a response message

Receives the response message from the response link.

responseMessage = responseLink.receiveTransfer()

The response message is in the following form:

Message(
properties: {
		correlation-id: <request id>
	},
	application-properties: {
			"statusCode" -> <status code>,
			"statusDescription" -> <status description>,
           },
)

Service Bus entity address

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"

Message operations

Message Renew Lock

Extends the lock of a message by the lock duration set on the queue or subscription.

Request

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.

Note

Lock token here refers to the delivery-tag property on the received AMQP message. If you received a deferred message and want to renew its lock, then use the property lock-token on the message instead of the delivery-tag.

Response

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.

Peek Message

Peeks messages without locking.

Request

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.

Response

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

204: 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.

Schedule Message

Schedules messages. This operation supports transaction.

Request

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 No amqpMessage.Properties.GroupId as string
partition-key string No amqpMessage.MessageAnnotations."x-opt-partition-key"
via-partition-key string No amqpMessage.MessageAnnotations."x-opt-via-partition-key"
message array of byte Yes AMQP 1.0 wire-encoded message.

Response

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.

Cancel Scheduled Message

Cancels scheduled messages.

Request

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.

Response

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.

Session Operations

Session Renew Lock

Extends the lock of a message by the lock duration set on the queue or subscription.

Request

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.

Response

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

204: 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.

Peek Session Message

Peeks session messages without locking.

Request

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.

Response

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

204: 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.

Set Session State

Sets the state of a session.

Request

The request message must include the following application properties:

Key Value Type Required Value Contents
operation string Yes com.microsoft:set-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.
session-state array of bytes Yes Opaque binary data.

Response

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.

Get Session State

Gets the state of a session.

Request

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.

Response

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.

Enumerate Sessions

Enumerates sessions on a messaging entity.

Request

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.

Note

When you set LastUpdatedTime to DateTime.MaxValue (in .NET), the Enumerate Sessions method returns all sessions whether they have state or not. DateTime.MaxValue in .NET may not exist in other programming languages. In such cases, use a time stamp that is equal to 253402300800000 milliseconds from the Epoch (January 1, 1970, 00:00:00 GMT), which is equivalent to DateTime.MaxValue in .NET.

Response

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

204: 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.

Rule operations

Add Rule

Request

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 ServiceBusMessage.Properties

The sql-rule-action map must include the following entries:

Key Value Type Required Value Contents
expression string Yes Sql action expression.

Response

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.

Remove Rule

Request

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.

Response

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.

Get Rules

Request

The request message must include the following application properties:

Key Value Type Required Value Contents
operation string Yes com.microsoft:enumerate-rules
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
top int Yes The number of rules to fetch in the page.
skip int Yes The number of rules to skip. Defines the starting index (+1) on the list of rules.

Response

The response message includes the following properties:

Key Value Type Required Value Contents
statusCode int Yes HTTP response code [RFC2616]

200: OK - success, otherwise failed
rules list of maps Yes List of rules. Each rule is represented by a map.

Each map entry in the list includes the following properties:

Key Value Type Required Value Contents
rule-description described object Yes com.microsoft:rule-description with AMQP described code 0x0000013700000004

com.microsoft.rule-description itself is a described list. It has the following properties:

Index Value Type Required Value Contents
0 described list Yes filter as specified in the next table.
1 described list Yes ruleAction as specified later in this section.
2 string Yes name of the rule.
3 timestamp Yes time stamp.

filter can be of either of the following types:

Descriptor Name Descriptor code Value
com.microsoft:sql-filter:list 0x000001370000006 SQL filter
com.microsoft:correlation-filter:list 0x000001370000009 Correlation filter
com.microsoft:true-filter:list 0x000001370000007 True filter representing 1=1
com.microsoft:false-filter:list 0x000001370000008 False filter representing 1=0

com.microsoft:sql-filter:list is a described list, which includes:

Index Value Type Required Value Contents
0 string Yes Sql Filter expression
1 int Yes always 20. This integer is the compatibility level of the sql filter. It indicates the syntax version of the sql filter.

com.microsoft:correlation-filter:list is a described list, which includes:

Index (if exists) Value Type Value Contents
0 string Correlation ID
1 string Message ID
2 string To
3 string Reply To
4 string Label
5 string Session ID
6 string Reply To Session ID
7 string Content Type
8 Map Map of application defined properties

ruleAction can be either of the following types:

Descriptor Name Descriptor code Value
com.microsoft:empty-rule-action:list 0x0000013700000005 Empty Rule Action - No rule action present
com.microsoft:sql-rule-action:list 0x0000013700000006 SQL Rule Action

com.microsoft:sql-rule-action:list is a described list that has two elements.

Index Value Type Required Value Contents
0 string Yes SQL rule action's expression
1 int Yes always 20. This integer is the compatibility level of the sql filter. It indicates the syntax version of the sql filter.

Deferred message operations

Receive by sequence number

Receives deferred messages by sequence number.

Request

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.

Response

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.

Update disposition status

Updates the disposition status of deferred messages. This operation supports transactions.

Request

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 It's set if disposition status is set to suspended.
deadletter-description string No It's set if disposition status is set to suspended.
properties-to-modify map No List of Service Bus brokered message properties to modify.

Response

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.

Next steps

To learn more about AMQP and Service Bus, visit the following links: