Azure 服务总线中的 AMQP 1.0：基于请求/响应的操作

项目
03/18/2024

本文定义 Azure 服务总线基于请求/响应的操作的列表。此信息基于 AMQP 管理版本 1.0 工作草案。

有关详细的线级 AMQP 1.0 协议指南（其中介绍了如何基于 OASIS AMQP 技术规范实现和建立服务总线），请参阅 Azure 服务总线和事件中心的 AMQP 1.0 协议指南。

概念

ServiceBusReceivedMessage / ServiceBusMessage

表示映射到 AMQP 消息的服务总线中的消息。服务总线 AMQP 协议指南中定义了映射。

附加到实体管理节点

本文档中所述的全部操作都遵循请求/响应模式，这些操作的范围限制到实体，并需要附加到实体管理节点。

创建用于发送请求的链接

创建用于发送请求的管理节点链接。

requestLink = session.attach(
role: SENDER,
   	target: { address: "<entity address>/$management" },
   	source: { address: ""<my request link unique address>" }
)

创建用于接收响应的链接

创建用于从管理节点接收响应的链接。

responseLink = session.attach(
role: RECEIVER,
	source: { address: "<entity address>/$management" }
   	target: { address: "<my response link unique address>" }
)

传输请求消息

传输请求消息。
对于支持事务的操作，可以选择添加事务状态。

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

接收响应消息

从响应链接接收响应消息。

responseMessage = responseLink.receiveTransfer()

响应消息采用以下形式：

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

服务总线实体地址

必须如下所示处理服务总线实体：

实体类型	地址	示例
queue	`<queue_name>`	`"myQueue"` `"site1/myQueue"`
主题	`<topic_name>`	`"myTopic"` `"site2/page1/myQueue"`
订阅	`<topic_name>/Subscriptions/<subscription_name>`	`"myTopic/Subscriptions/MySub"`

消息操作

消息续订锁

根据在队列或订阅上设置的锁定持续时间延长消息的锁定时间。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:renew-lock`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
`lock-tokens`	uuid 的数组	是	要续订的消息锁令牌。

注意

此处的锁定令牌指收到的 AMQP 消息中的 delivery-tag 属性。如果收到延迟消息且想要更新消息锁定，请使用消息上的 lock-token 属性而不是 delivery-tag。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败。
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
expirations	时间戳的数组	是	对应于请求锁令牌的消息锁令牌新到期日。

速览消息

在不锁定的情况下速览消息。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:peek-message`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
`from-sequence-number`	long	是	从其开始速览的序列号。
`message-count`	int	是	要速览的消息数量的上限。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 有更多消息 204：无内容 - 没有更多消息
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
messages	映射列表	是	消息列表，其中每个映射表示一条消息。

代表消息的映射必须包含以下条目：

键	值类型	必须	值内容
message	字节的数组	是	AMQP 1.0 连线编码消息。

计划消息

计划消息。此操作支持事务。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:schedule-message`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
messages	映射列表	是	消息列表，其中每个映射表示一条消息。

代表消息的映射必须包含以下条目：

键	值类型	必须	值内容
message-id	string	是	`amqpMessage.Properties.MessageId` 为字符串
session-id	string	否	`amqpMessage.Properties.GroupId as string`
partition-key	string	否	`amqpMessage.MessageAnnotations."x-opt-partition-key"`
via-partition-key	string	否	`amqpMessage.MessageAnnotations."x-opt-via-partition-key"`
message	字节的数组	是	AMQP 1.0 连线编码消息。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败。
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
sequence-numbers	长整数的数组	是	计划消息的序列号。序列号用于取消。

取消计划消息

取消计划消息。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:cancel-scheduled-message`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
sequence-numbers	长整数的数组	是	要取消的计划消息的序列号。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败。
statusDescription	string	否	状态的说明。

会话操作

会话续订锁

根据在队列或订阅上设置的锁定持续时间延长消息的锁定时间。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:renew-session-lock`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
session-id	string	是	会话 ID。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 有更多消息 204：无内容 - 没有更多消息
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
expiration	timestamp	是	新到期日。

速览会话消息

在不锁定的情况下速览会话消息。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:peek-message`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
from-sequence-number	long	是	从其开始速览的序列号。
message-count	int	是	要速览的消息数量的上限。
session-id	string	是	会话 ID。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 有更多消息 204：无内容 - 没有更多消息
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
messages	映射列表	是	消息列表，其中每个映射表示一条消息。

代表消息的映射必须包含以下条目：

键	值类型	必须	值内容
message	字节的数组	是	AMQP 1.0 连线编码消息。

设置会话状态

设置会话的状态。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:set-session-state`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
session-id	string	是	会话 ID。
session-state	字节的数组	是	不透明的二进制数据。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败
statusDescription	string	否	状态的说明。

获取会话状态

获取会话的状态。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:get-session-state`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
session-id	string	是	会话 ID。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
session-state	字节的数组	是	不透明的二进制数据。

枚举会话

消息传送实体上的枚举会话。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:get-message-sessions`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
last-updated-time	timestamp	是	筛选，以便仅包含在给定时间后更新的会话。
skip	int	是	跳过会话数量。
top	int	是	会话数量的上限。

注意

将 LastUpdatedTime 设置为 DateTime.MaxValue 时（在 .NET 中），枚举会话方法返回所有会话（无论其是否有状态）。 .NET 中的 DateTime.MaxValue 在其他编程语言中可能不存在。在这种情况下，请使用等于距纪元（1970 年 1 月 1 日 00:00:00 GMT）253402300800000 毫秒的时间戳，这相当于 .NET 中的 DateTime.MaxValue。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 有更多消息 204：无内容 - 没有更多消息
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
skip	int	是	状态代码为 200 时的已跳过会话的数量。
sessions-ids	字符串的数组	是	状态代码为 200 时的会话 ID 的数组。

规则操作

添加规则

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:add-rule`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
rule-name	string	是	规则名称，不包括订阅和主题名称。
rule-description	map	是	如下一部分中指定的规则描述。

rule-description 映射必须包含以下条目，其中 sql-filter 和 correlation-filter 互斥：

键	值类型	必须	值内容
sql-filter	map	是	`sql-filter`，如下一部分中所指定。
correlation-filter	map	是	`correlation-filter`，如下一部分中所指定。
sql-rule-action	map	是	`sql-rule-action`，如下一部分中所指定。

sql-filter 映射必须包含以下条目：

键	值类型	必须	值内容
expression	string	是	Sql 筛选器表达式。

correlation-filter 映射至少必须包含以下条目之一：

键	值类型	必须	值内容
correlation-id	string	否
message-id	string	否
to	string	否
reply-to	string	否
label	string	否
session-id	string	否
reply-to-session-id	string	否
content-type	string	否
properties	map	否	映射到服务总线 ServiceBusMessage.Properties

sql-rule-action 映射必须包含以下条目：

键	值类型	必须	值内容
expression	string	是	Sql 操作表达式。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败
statusDescription	string	否	状态的说明。

删除规则

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:remove-rule`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
rule-name	string	是	规则名称，不包括订阅和主题名称。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败
statusDescription	string	否	状态的说明。

获取规则

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:enumerate-rules`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
top	int	是	要在页面中提取的规则数量。
skip	int	是	要跳过的规则数量。定义规则列表中的起始索引 (+1)。

响应

响应消息包含以下属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败
规则	映射列表	是	规则列表。每个规则均由一个映射表示。

列表中的每个映射项都包含以下属性：

键	值类型	必须	值内容
rule-description	描述对象	是	带有 AMQP 的 `com.microsoft:rule-description` 描述了代码 0x0000013700000004

com.microsoft.rule-description 本身是描述列表。它具有以下属性：

索引	值类型	必须	值内容
0	描述列表	是	`filter` 的详细信息请参阅下一表格。
1	描述列表	是	本部分后面将介绍 `ruleAction` 的详细信息。
2	string	是	规则名称。
3	timestamp	是	时间戳。

filter 可以是以下任一类型：

描述符名称	描述符代码	Value
`com.microsoft:sql-filter:list`	0x000001370000006	SQL 筛选器
`com.microsoft:correlation-filter:list`	0x000001370000009	关联筛选器
`com.microsoft:true-filter:list`	0x000001370000007	True 筛选器表示 1=1
`com.microsoft:false-filter:list`	0x000001370000008	False 筛选器表示 1=0

com.microsoft:sql-filter:list 是描述列表，它包括：

索引	值类型	必须	值内容
0	string	是	SQL 筛选表达式
1	int	是	始终为 20。此整数是 SQL 筛选器的兼容级别。它表示 SQL 筛选器的语法版本。

com.microsoft:correlation-filter:list 是描述列表，它包括：

索引（如果存在）	值类型	值内容
0	string	相关性 ID
1	string	消息 ID
2	string	如果
3	string	回复
4	string	Label
5	string	会话 ID
6	string	会话 ID 回复
7	string	内容类型
8	映射	定义属性的应用程序的映射

ruleAction 可以是以下任一类型：

描述符名称	描述符代码	Value
`com.microsoft:empty-rule-action:list`	0x0000013700000005	空规则操作 - 不存在任何规则操作
`com.microsoft:sql-rule-action:list`	0x0000013700000006	SQL 规则操作

com.microsoft:sql-rule-action:list 是包含两个元素的描述列表。

索引	值类型	必须	值内容
0	string	是	SQL 规则操作的表达式
1	int	是	始终为 20。此整数是 SQL 筛选器的兼容级别。它表示 SQL 筛选器的语法版本。

延迟的消息操作

按序列号接收

按序列号接收延迟的消息。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:receive-by-sequence-number`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
sequence-numbers	长整数的数组	是	序列号。
receiver-settle-mode	ubyte	是	AMQP 核心 v1.0 中指定的“接收方结算” 模式。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败
statusDescription	string	否	状态的说明。

响应消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
messages	映射列表	是	消息列表，其中每个映射表示一条消息。

代表消息的映射必须包含以下条目：

键	值类型	必须	值内容
lock-token	uuid	是	`receiver-settle-mode` 为 1 时的锁令牌。
message	字节的数组	是	AMQP 1.0 连线编码消息。

更新处置状态

更新延迟消息的处置状态。该操作支持事务。

请求

请求消息必须包含以下应用程序属性：

键	值类型	必须	值内容
operation	字符串	是	`com.microsoft:update-disposition`
`com.microsoft:server-timeout`	uint	否	操作服务器超时以毫秒为单位。

请求消息正文必须包含 amqp-value 部分，其中所含映射必须包括以下条目：

键	值类型	必须	值内容
disposition-status	string	是	已完成已放弃已挂起
lock-tokens	uuid 的数组	是	用于更新处置状态的消息锁令牌。
deadletter-reason	string	否	如果处置状态设置为“已暂停”，则会对其进行设置。
deadletter-description	string	否	如果处置状态设置为“已暂停”，则会对其进行设置。
properties-to-modify	map	否	要修改的服务总线中转消息属性的列表。

响应

响应消息必须包含以下应用程序属性：

键	值类型	必须	值内容
statusCode	int	是	HTTP 响应代码 [RFC2616] 200：正常 - 成功，其他表示失败
statusDescription	string	否	状态的说明。

后续步骤

若要详细了解 AMQP 和服务总线，请单击以下链接：

Azure 服务总线中的 AMQP 1.0：基于请求/响应的操作

概念

ServiceBusReceivedMessage / ServiceBusMessage

附加到实体管理节点

创建用于发送请求的链接

创建用于接收响应的链接

传输请求消息

接收响应消息

服务总线实体地址

消息操作

消息续订锁

请求

响应

速览消息

请求

响应

计划消息

请求

响应

取消计划消息

请求

响应

会话操作

会话续订锁

请求

响应

速览会话消息

请求

响应

设置会话状态

请求

响应

获取会话状态

请求

响应

枚举会话

请求

响应

规则操作

添加规则

请求

响应

删除规则

请求

响应

获取规则

请求

响应

延迟的消息操作

按序列号接收

请求

响应

更新处置状态

请求

响应

后续步骤

其他资源