本页包含 RabbitMQ 对 AMQP 规范版本 0-9-1 的实现的完整参考。 原始规范 由 AMQP 工作组 于 2008 年发布,并根据 AMQP 许可证 提供。
您可以在本网站的其他地方阅读有关 RabbitMQ 与规范的符合性 的详细信息。RabbitMQ 在核心规范上实现了 若干扩展,这些扩展在本指南中有所记录。原始规范和扩展规范的下载可以在 协议页面 上找到。
您可能还对我们的 协议和 API 快速参考 感兴趣。
- 主版本-次版本
- 0-9
- 修订版
- 1
- 端口
- 5672
- 描述
- AMQ 协议版本 0-9-1
规范中定义了以下类及其关联方法
连接
处理套接字连接。
连接类为客户端提供方法来建立与服务器的网络连接,并为两个对等体提供方法来操作此连接。
类语法
connection = open-connection *use-connection close-connection open-connection = C:protocol-header S:START C:START-OK *challenge S:TUNE C:TUNE-OK C:OPEN S:OPEN-OK challenge = S:SECURE C:SECURE-OK use-connection = *channel close-connection = C:CLOSE S:CLOSE-OK / S:CLOSE C:CLOSE-OK
方法
start(
启动连接协商。
此方法通过告诉客户端服务器建议的协议版本以及客户端可用于身份验证的安全机制列表来启动连接协商过程。
如果服务器无法支持协议头中指定的协议,则它 MUST 使用有效的协议头进行响应,然后关闭套接字连接。
服务器 MUST 提供的协议版本低于或等于客户端在协议头中请求的版本。
如果客户端无法处理服务器建议的协议版本,则它 MUST 关闭套接字连接,而无需发送任何其他数据。
参数
octet version-major
主版本号可以取 AMQP 规范中定义的 0 到 99 之间的任何值。
octet version-minor
次版本号可以取 AMQP 规范中定义的 0 到 99 之间的任何值。
peer-properties server-properties
服务器属性。
属性 SHOULD 包含以下字段:指定服务器主机名或地址的 "host"、提供服务器产品名称的 "product"、提供服务器版本名称的 "version"、提供操作系统名称的 "platform"、如果适用则提供版权信息的 "copyright" 以及提供其他一般信息的 "information"。
longstr mechanisms
服务器支持的安全机制列表,以空格分隔。
longstr locales
服务器支持的消息区域设置列表,以空格分隔。区域设置定义了服务器将发送回复文本的语言。
服务器 MUST 至少支持 en_US 区域设置。
start-ok(
选择安全机制和区域设置。
此方法选择 SASL 安全机制。
参数
peer-properties client-properties
客户端属性。
属性 SHOULD 包含以下字段:提供客户端产品名称的 "product"、提供客户端版本名称的 "version"、提供操作系统名称的 "platform"、如果适用则提供版权信息的 "copyright" 以及提供其他一般信息的 "information"。
shortstr mechanism
客户端选择的一个安全机制,必须是服务器指定的机制之一。
客户端 SHOULD 使用它可以处理的来自服务器提供的列表中的最高级别安全配置文件进行身份验证。
如果 mechanism 字段不包含服务器在 Start 方法中提出的安全机制之一,则服务器 MUST 关闭连接,而无需发送任何其他数据。
longstr response
传递给安全机制的一块不透明数据。此数据的內容由 SASL 安全机制定义。
shortstr locale
客户端选择的一个消息区域设置,必须是服务器指定的区域设置之一。
(返回顶部)secure(
安全机制挑战。
SASL 协议通过交换挑战和响应来工作,直到两个对等体都收到足够的信息来相互验证。此方法挑战客户端提供更多信息。
参数
longstr challenge
挑战信息,传递给安全机制的一块不透明二进制数据。
(返回顶部)secure-ok(
安全机制响应。
此方法尝试进行身份验证,将一块 SASL 数据传递给服务器端的安全机制。
参数
longstr response
传递给安全机制的一块不透明数据。此数据的內容由 SASL 安全机制定义。
(返回顶部)tune(
建议连接调整参数。
此方法向客户端建议一组连接配置值。客户端可以接受和/或调整这些值。
参数
short channel-max
指定服务器允许的最高通道号。可用的通道号在 1..channel-max 范围内。零表示没有指定限制。
long frame-max
服务器建议的连接的最大帧大小,包括帧头和结束字节。客户端可以协商一个较低的值。零表示服务器不施加任何特定限制,但如果无法为它们分配资源,则可能会拒绝非常大的帧。
在协商 frame-max 之前,两个对等体 MUST 接受最大为 frame-min-size 个字节的帧,frame-max 的最小协商值也是 frame-min-size。
short heartbeat
服务器想要的连接心跳延迟(以秒为单位)。零表示服务器不需要心跳。
(返回顶部)tune-ok(
协商连接调整参数。
此方法将客户端的连接调整参数发送到服务器。某些字段是协商的,其他字段提供功能信息。
参数
short channel-max
客户端将在每个连接上使用的最大通道总数。
如果客户端指定的 channel max 高于服务器提供的 value,则服务器 MUST 关闭连接,而无需尝试协商关闭。服务器可能会以某种方式报告错误,以帮助实施者。
long frame-max
客户端和服务器将在连接上使用的最大帧大小。零表示客户端不施加任何特定限制,但如果无法为它们分配资源,则可能会拒绝非常大的帧。请注意,frame-max 限制主要适用于内容帧,其中大内容可以分成任意大小的帧。
在协商 frame-max 之前,两个对等体 MUST 接受最大为 frame-min-size 个字节的帧,frame-max 的最小协商值也是 frame-min-size。
如果客户端指定的 frame max 高于服务器提供的 value,则服务器 MUST 关闭连接,而无需尝试协商关闭。服务器可能会以某种方式报告错误,以帮助实施者。
short heartbeat
客户端想要的连接心跳延迟(以秒为单位)。零表示客户端不需要心跳。
(返回顶部)open(
打开与虚拟主机的连接。
此方法打开与虚拟主机的连接,虚拟主机是资源的集合,用于在服务器中隔离多个应用程序域。服务器可能会对每个虚拟主机应用任意限制,例如每连接和/或总共可使用的每种类型实体的数量。
参数
path virtual-host
要使用的虚拟主机的名称。
如果服务器支持多个虚拟主机,则它 MUST 强制对每个虚拟主机的交换、队列和所有关联实体进行完全隔离。连接到特定虚拟主机的应用程序 MUST NOT 能够访问其他虚拟主机的资源。
服务器 SHOULD 验证客户端是否有权访问指定的虚拟主机。
shortstr reserved-1
bit reserved-2
(返回顶部)open-ok(
表示连接已准备好。
此方法向客户端表示连接已准备好使用。
参数
shortstr reserved-1
(返回顶部)close(
请求关闭连接。
此方法表示发送方想要关闭连接。这可能是由于内部条件(例如强制关闭)或由于处理特定方法的错误(即异常)造成的。当关闭是由于异常引起的,发送方会提供导致异常的方法的类和方法 ID。
发送此方法后,除 Close 和 Close-OK 之外的任何接收方法都必须丢弃。接收 Close 后发送 Close 的响应必须是发送 Close-Ok。
参数
回复代码 回复代码
回复文本 回复文本
类 ID 类 ID
当关闭是由方法异常引起的,这是该方法的类。
方法 ID 方法 ID
当关闭是由方法异常引起的,这是该方法的 ID。
(返回顶部)关闭确认()
确认连接关闭。
此方法确认 Connection.Close 方法,并告诉接收方可以安全地释放连接资源并关闭套接字。
在未收到 Close-Ok 握手方法的情况下检测到套接字关闭的对等方应该记录错误。
阻塞(
指示连接已阻塞。
此方法表示连接已被阻塞,不接受新的发布。
参数
短字符串 原因
连接被阻塞的原因。
(返回顶部)解除阻塞()
指示连接已解除阻塞。
此方法表示连接已被解除阻塞,现在接受发布。
(返回顶部)更新密钥(
更新密钥。
此方法更新用于验证此连接的密钥。当密钥具有过期日期并且需要更新时,例如 OAuth 2 令牌,将使用它。
参数
长字符串 新密钥
新的密钥。
短字符串 原因
更新密钥的原因。
(返回顶部)更新密钥确认()
更新密钥响应。
此方法确认更新后的密钥有效。
(返回顶部)通道
处理通道。
通道类提供方法,供客户端建立到服务器的通道,以及供两个对等方在之后操作通道。
类语法
channel = open-channel *use-channel close-channel open-channel = C:OPEN S:OPEN-OK use-channel = C:FLOW S:FLOW-OK / S:FLOW C:FLOW-OK / functional-class close-channel = C:CLOSE S:CLOSE-OK / S:CLOSE C:CLOSE-OK
方法
open(
打开通道以供使用。
此方法打开到服务器的通道。
客户端不得在已打开的通道上使用此方法。
错误代码:通道错误
参数
shortstr reserved-1
(返回顶部)open-ok(
发出通道已准备好的信号。
此方法向客户端发出信号,指示通道已准备好使用。
参数
长字符串 保留 1
(返回顶部)流(
启用/禁用来自对等方的流。
此方法要求对等方暂停或重启由消费者发送的内容数据的流。这是一种简单的流量控制机制,对等方可以使用它来避免溢出其队列,或以其他方式发现自己接收到的消息超过其处理能力。请注意,此方法并非用于窗口控制。它不会影响 Basic.Get-Ok 方法返回的内容。
当打开新通道时,它处于活动状态(流处于活动状态)。一些应用程序假设通道在启动之前处于非活动状态。要模拟这种行为,客户端可以在打开通道后暂停它。
在发送内容帧时,对等方应该监视通道上的传入方法,并尽快响应 Channel.Flow。
对等方可以使用 Channel.Flow 方法出于内部原因限制传入的内容数据,例如,在通过较慢的连接交换数据时。
请求 Channel.Flow 方法的对等方可以断开连接和/或禁止不尊重请求的对等方。这样做是为了防止行为不端的客户端压垮服务器。
参数
比特 活动
如果为 1,则对等方开始发送内容帧。如果为 0,则对等方停止发送内容帧。
(返回顶部)流确认(
确认流方法。
向对等方确认已收到并处理了流命令。
参数
比特 活动
确认已处理流方法的设置:1 表示对等方将开始发送或继续发送内容帧;0 表示它将不发送内容帧。
(返回顶部)close(
请求关闭通道。
此方法表示发送方想要关闭通道。这可能是由于内部条件(例如强制关闭)或由于处理特定方法的错误(即异常)造成的。当关闭是由于异常引起的,发送方会提供导致异常的方法的类和方法 ID。
发送此方法后,除 Close 和 Close-OK 之外的任何接收方法都必须丢弃。接收 Close 后发送 Close 的响应必须是发送 Close-Ok。
参数
回复代码 回复代码
回复文本 回复文本
类 ID 类 ID
当关闭是由方法异常引起的,这是该方法的类。
方法 ID 方法 ID
当关闭是由方法异常引起的,这是该方法的 ID。
(返回顶部)关闭确认()
确认通道关闭。
此方法确认 Channel.Close 方法,并告诉接收方可以安全地释放通道资源。
在未收到 Channel.Close-Ok 握手方法的情况下检测到套接字关闭的对等方应该记录错误。
交换
处理交换。
交换匹配并将消息分发到多个队列。交换可以在服务器中配置,也可以在运行时声明。
类语法
exchange = C:DECLARE S:DECLARE-OK / C:DELETE S:DELETE-OK / C:BIND S:BIND-OK / C:UNBIND S:UNBIND-OK
服务器必须实现以下标准交换类型:fanout、direct。
服务器应该实现以下标准交换类型:topic、headers。
服务器必须在每个虚拟主机中预声明每个其所实现的标准交换类型的交换实例,其中交换实例的名称(如果已定义)为“amq.”后跟交换类型名称。服务器必须在每个虚拟主机中至少预声明两个 direct 交换实例:一个名为“amq.direct”,另一个没有公共名称,作为 Publish 方法的默认交换。
服务器必须预声明一个没有公共名称的 direct 交换,作为内容 Publish 方法和默认队列绑定的默认交换。
服务器不得允许客户端访问默认交换,除非在 Queue.Bind 和内容 Publish 方法中指定空交换名称。
服务器可以根据需要实现其他交换类型。
方法
声明(
验证交换是否存在,如果不存在则创建。
此方法创建交换(如果尚不存在),如果交换存在,则验证它是否属于正确的预期类。
服务器应该支持每个虚拟主机至少 16 个交换,理想情况下,除了由可用资源定义的限制外,不应施加任何限制。
参数
短整型 保留 1
交换名称 交换
以“amq.”开头的交换名称保留用于预声明的标准化交换。如果设置了被动选项或交换已存在,则客户端可以声明以“amq.”开头的交换。
错误代码:拒绝访问交换名称由以下字符组成的非空序列构成:字母、数字、连字符、下划线、句点或冒号。
错误代码:先决条件失败
短字符串 类型
每个交换都属于服务器所实现的一组交换类型。交换类型定义交换的功能,即消息如何通过它路由。尝试更改现有交换的类型无效且没有意义。
交换不能用不同的类型重新声明。客户端不得尝试用与原始 Exchange.Declare 方法中使用的类型不同的类型重新声明现有交换。
错误代码:不允许客户端不得尝试声明服务器不支持的类型。
错误代码:命令无效
比特 被动
如果设置,如果交换已存在且名称相同,则服务器将回复 Declare-Ok,否则会引发错误。客户端可以使用它来检查交换是否存在,而无需修改服务器状态。当设置时,除名称和不等待之外的所有其他方法字段都将被忽略。同时使用被动和不等待的声明不会有任何影响。参数将针对语义等效性进行比较。
如果设置,并且交换不存在,则服务器必须引发通道异常,回复代码为 404(未找到)。
如果未设置,并且交换存在,则服务器必须检查现有交换的类型、持久性和参数字段的值是否相同。如果请求的交换与这些字段匹配,则服务器必须回复 Declare-Ok,否则必须引发通道异常。
比特 持久
如果在创建新交换时设置,则该交换将被标记为持久。持久交换在服务器重启时保持活动状态。非持久交换(瞬时交换)将在服务器重启时被清除。
服务器必须支持持久和瞬时交换。
比特 自动删除
如果设置,则在所有队列完成使用该交换后将其删除。
服务器应该允许在确定交换未被使用(或不再使用)的时间点和删除交换的时间点之间存在合理的延迟。至少它必须允许客户端创建交换,然后将队列绑定到该交换,并在这两个操作之间存在很短但非零的延迟。
如果交换已存在,则服务器必须忽略自动删除字段。
比特 内部
如果设置,交换器不能被发布者直接使用,但只有在绑定到其他交换器时才能使用。内部交换器用于构建应用程序不可见的布线。
no-wait no-wait
table arguments
声明的一组参数。这些参数的语法和语义取决于服务器实现。
(返回顶部)declare-ok()
确认交换器声明。
此方法确认 Declare 方法并确认交换器的名称,这对自动命名的交换器至关重要。
(返回顶部)delete(
删除交换器。
此方法删除交换器。当交换器被删除时,交换器上的所有队列绑定都会被取消。
参数
短整型 保留 1
交换名称 交换
客户端 MUST NOT 尝试删除不存在的交换器。
错误代码: not-found
bit if-unused
如果设置,服务器将仅在交换器没有队列绑定时才删除它。如果交换器有队列绑定,服务器不会删除它,而是会引发一个通道异常。
如果 if-unused 字段为真,服务器 MUST NOT 删除有绑定的交换器。
错误代码:先决条件失败
no-wait no-wait
(返回顶部)delete-ok()
确认交换器删除。
此方法确认交换器的删除。
(返回顶部)bind(
将交换器绑定到交换器。
此方法将交换器绑定到交换器。
服务器 MUST 允许并忽略重复绑定 - 也就是说,两个或多个针对特定交换器的 bind 方法,具有相同的参数 - 而不将其视为错误。
服务器 MUST 允许创建交换器绑定的循环,包括允许交换器绑定到自身。
服务器 MUST 不向目标交换器传递相同的消息多次,即使交换器和绑定的拓扑结构导致多条(甚至无限条)路由到该交换器。
参数
短整型 保留 1
exchange-name destination
指定要绑定的目标交换器的名称。
客户端 MUST NOT 允许绑定不存在的目标交换器。
错误代码: not-found服务器 MUST 接受空白的交换器名称表示默认交换器。
exchange-name source
指定要绑定的源交换器的名称。
客户端 MUST NOT 允许绑定不存在的源交换器。
错误代码: not-found服务器 MUST 接受空白的交换器名称表示默认交换器。
shortstr routing-key
指定绑定的路由键。路由键用于根据交换器配置路由消息。并非所有交换器都使用路由键 - 请参考特定交换器文档。
no-wait no-wait
table arguments
绑定的一组参数。这些参数的语法和语义取决于交换器类。
(返回顶部)bind-ok()
确认绑定成功。
此方法确认绑定成功。
(返回顶部)unbind(
将交换器从交换器中解绑。
此方法将交换器从交换器中解绑。
如果解绑失败,服务器 MUST 引发连接异常。
参数
短整型 保留 1
exchange-name destination
指定要解绑的目标交换器的名称。
客户端 MUST NOT 尝试从交换器中解绑不存在的交换器。
错误代码: not-found服务器 MUST 接受空白的交换器名称表示默认交换器。
exchange-name source
指定要解绑的源交换器的名称。
客户端 MUST NOT 尝试从不存在的交换器中解绑交换器。
错误代码: not-found服务器 MUST 接受空白的交换器名称表示默认交换器。
shortstr routing-key
指定要解绑的绑定的路由键。
no-wait no-wait
table arguments
指定要解绑的绑定的参数。
(返回顶部)unbind-ok()
确认解绑成功。
此方法确认解绑成功。
(返回顶部)queue
使用队列。
队列存储和转发消息。队列可以在服务器中配置或在运行时创建。队列必须至少连接到一个交换器才能从发布者接收消息。
类语法
queue = C:DECLARE S:DECLARE-OK / C:BIND S:BIND-OK / C:UNBIND S:UNBIND-OK / C:PURGE S:PURGE-OK / C:DELETE S:DELETE-OK
方法
声明(
声明队列,如果需要则创建。
此方法创建或检查队列。在创建新队列时,客户端可以指定各种属性来控制队列及其内容的持久性以及队列的共享级别。
服务器 MUST 为新声明的队列创建到默认交换器的默认绑定,该交换器是类型为“direct”的交换器,并使用队列名称作为路由键。
服务器 SHOULD 支持每个虚拟主机至少 256 个队列,理想情况下,除了由可用资源定义的限制外,不施加任何限制。
参数
短整型 保留 1
queue-name queue
队列名称 MAY 为空,在这种情况下,服务器 MUST 创建一个具有唯一生成的名称的新队列,并将其返回给客户端在 Declare-Ok 方法中。
以“amq.”开头的队列名称保留用于预先声明的和标准化的队列。如果设置了 passive 选项或队列已存在,客户端 MAY 声明以“amq.”开头的队列。
错误代码:拒绝访问队列名称可以为空,也可以是以下字符的序列:字母、数字、连字符、下划线、句点或冒号。
错误代码:先决条件失败
bit passive
如果设置,服务器将使用 Declare-Ok 回复如果队列已存在且名称相同,如果不存在则引发错误。客户端可以使用此来检查队列是否存在而不修改服务器状态。当设置时,除了 name 和 no-wait 之外的所有其他方法字段都会被忽略。具有 passive 和 no-wait 的声明没有效果。参数将被比较语义等效性。
客户端 MAY 要求服务器断言队列存在而不创建队列(如果不存在)。如果队列不存在,服务器将将其视为失败。
错误代码: not-found如果未设置且队列存在,服务器 MUST 检查现有队列的 durable、exclusive、auto-delete 和 arguments 字段的值是否相同。如果请求的队列与这些字段匹配,服务器 MUST 使用 Declare-Ok 响应,如果不匹配,则 MUST 引发通道异常。
bit durable
如果在创建新队列时设置,则该队列将被标记为持久队列。持久队列在服务器重启后仍然处于活动状态。非持久队列(瞬态队列)将在服务器重启时(如果)被清除。请注意,持久队列不一定会保存持久消息,尽管将持久消息发送到瞬态队列没有意义。
服务器 MUST 在重启后重新创建持久队列。
服务器 MUST 支持持久队列和瞬态队列。
bit exclusive
独占队列只能被当前连接访问,并在该连接关闭时被删除。其他连接不允许被动声明独占队列。
服务器 MUST 支持独占(专用)队列和非独占(共享)队列。
客户端 MAY NOT 尝试使用由其他仍处于打开状态的连接声明为独占的队列。
错误代码: resource-locked
bit auto-delete
如果设置,则在所有消费者完成使用队列后将其删除。最后一个消费者可以被显式取消,或者因为其通道被关闭而被取消。如果队列上从未有过消费者,则不会被删除。应用程序可以使用 Delete 方法按照通常的方式显式删除自动删除队列。
如果队列已存在,服务器 MUST 忽略 auto-delete 字段。
no-wait no-wait
table arguments
声明的一组参数。这些参数的语法和语义取决于服务器实现。
(返回顶部)declare-ok(
确认队列定义。
此方法确认 Declare 方法并确认队列的名称,这对自动命名的队列至关重要。
参数
queue-name queue
报告队列的名称。如果服务器生成了队列名称,则此字段包含该名称。
message-count message-count
long consumer-count
报告队列的活动消费者数量。请注意,消费者可以暂停活动(Channel.Flow),在这种情况下,它们不会出现在此计数中。
(返回顶部)bind(
将队列绑定到交换器。
此方法将队列绑定到交换器。在队列绑定之前,它不会接收任何消息。在传统的信使模型中,存储转发队列绑定到直接交换器,订阅队列绑定到主题交换器。
服务器 MUST 允许忽略重复绑定 - 也就是说,两个或多个针对特定队列的 bind 方法,具有相同的参数 - 而不将其视为错误。
服务器 MUST 不向队列传递相同的消息多次,即使队列具有多个与该消息匹配的绑定。
服务器 MUST 允许持久队列绑定到瞬态交换器。
持久队列到持久交换器的绑定自动是持久的,服务器 MUST 在服务器重启后恢复此类绑定。
服务器 SHOULD 支持每个队列至少 4 个绑定,理想情况下,除了由可用资源定义的限制外,不施加任何限制。
参数
短整型 保留 1
queue-name queue
指定要绑定的队列的名称。
exchange-name exchange
要绑定的交换器的名称。
客户端 MUST NOT 允许将队列绑定到不存在的交换器。
错误代码: not-found服务器 MUST 接受空白的交换器名称表示默认交换器。
shortstr routing-key
指定绑定使用的路由键。路由键用于根据交换机配置路由消息。并非所有交换机都使用路由键 - 请参阅特定交换机文档。如果队列名称为空,服务器将使用通道上最后声明的队列。如果路由键也为空,服务器也将使用此队列名称作为路由键。如果提供了队列名称但路由键为空,服务器将使用该空路由键进行绑定。空路由键的含义取决于交换机实现。
如果消息队列使用路由键 K 绑定到直接交换机,并且发布者向交换机发送带有路由键 R 的消息,则如果 K = R,则该消息必须传递到消息队列。
no-wait no-wait
table arguments
绑定的一组参数。这些参数的语法和语义取决于交换器类。
(返回顶部)bind-ok()
确认绑定成功。
此方法确认绑定成功。
(返回顶部)unbind(
从交换机取消绑定队列。
此方法从交换机取消绑定队列。
如果解绑失败,服务器 MUST 引发连接异常。
参数
短整型 保留 1
queue-name queue
指定要取消绑定的队列的名称。
交换名称 交换
要取消绑定的交换机的名称。
客户端不得尝试从不存在的交换机取消绑定队列。
错误代码: not-found服务器 MUST 接受空白的交换器名称表示默认交换器。
shortstr routing-key
指定要解绑的绑定的路由键。
table arguments
指定要解绑的绑定的参数。
(返回顶部)unbind-ok()
确认解绑成功。
此方法确认解绑成功。
(返回顶部)purge(
清除队列。
此方法从队列中删除所有未等待确认的消息。
服务器不得清除已发送到客户端但尚未确认的消息。
服务器可以实现一个清除队列或日志,允许系统管理员恢复意外清除的消息。服务器不应将清除的消息保存在与实时消息相同的存储空间中,因为清除消息的数量可能会非常大。
参数
短整型 保留 1
queue-name queue
指定要清除的队列的名称。
no-wait no-wait
(返回顶部)purge-ok(
确认队列清除。
此方法确认队列的清除。
参数
message-count message-count
报告清除的消息数量。
(返回顶部)delete(
删除队列。
此方法删除队列。当队列被删除时,任何待处理的消息将发送到死信队列(如果在服务器配置中定义),并且队列上的所有消费者将被取消。
服务器应该使用死信队列来保存待处理的已删除队列上的消息,并且可以为系统管理员提供将这些消息移回活动队列的功能。
参数
短整型 保留 1
queue-name queue
指定要删除的队列的名称。
bit if-unused
如果设置,服务器将仅在队列没有消费者时才删除队列。如果队列有消费者,服务器将不删除它,而是引发通道异常。
如果 if-unused 字段为真,服务器不得删除具有消费者的队列。
错误代码:先决条件失败
bit if-empty
如果设置,服务器将仅在队列没有消息时才删除队列。
如果 if-empty 字段为真,服务器不得删除包含消息的队列。
错误代码:先决条件失败
no-wait no-wait
(返回顶部)delete-ok(
确认队列删除。
此方法确认队列的删除。
参数
message-count message-count
报告删除的消息数量。
(返回顶部)basic
使用基本内容。
Basic 类提供支持行业标准消息传递模型的方法。
类语法
basic = C:QOS S:QOS-OK / C:CONSUME S:CONSUME-OK / C:CANCEL S:CANCEL-OK / C:PUBLISH content / S:RETURN content / S:DELIVER content / C:GET ( S:GET-OK content / S:GET-EMPTY ) / C:ACK / S:ACK / C:REJECT / C:NACK / S:NACK / C:RECOVER-ASYNC / C:RECOVER S:RECOVER-OK
服务器应该尊重基本消息的持久属性,并且应该尽力将持久基本消息保存在可靠的存储机制中。
服务器不得在队列溢出时丢弃持久基本消息。
服务器可以使用 Channel.Flow 方法在必要时减慢或停止基本消息发布者。
服务器可以将非持久基本消息溢出到持久存储中。
服务器可以根据优先级丢弃或死信非持久基本消息,如果队列大小超过某个配置的限制。
服务器必须至少实现 2 个基本消息优先级级别,其中优先级 0-4 和 5-9 被视为两个不同的级别。
服务器可以实现最多 10 个优先级级别。
服务器必须按顺序传递具有相同优先级的消息,而不管它们各自的持久性。
服务器必须支持未确认的基本内容交付,即 no-ack 字段设置为 TRUE 的消费者。
服务器必须支持显式确认的基本内容交付,即 no-ack 字段设置为 FALSE 的消费者。
字段
定义 | 描述 |
---|---|
shortstr content-type | MIME 内容类型。 |
shortstr content-encoding | MIME 内容编码。 |
table headers | 消息头字段表。 |
octet delivery-mode | 非持久(1)或持久(2)。 |
octet priority | 消息优先级,0 到 9。 |
shortstr correlation-id | 应用程序关联标识符。 |
shortstr reply-to | 回复地址。 |
shortstr expiration | 消息过期规范。 |
shortstr message-id | 应用程序消息标识符。 |
timestamp timestamp | 消息时间戳。 |
shortstr type | 消息类型名称。 |
shortstr user-id | 创建用户 ID。 |
shortstr app-id | 创建应用程序 ID。 |
shortstr reserved | 保留,必须为空。 |
方法
qos(
指定服务质量。
此方法请求特定的服务质量。可以为当前通道或连接上的所有通道指定 QoS。qos 方法的特定属性和语义始终取决于内容类语义。虽然 qos 方法原则上可以应用于两个对等方,但目前它仅对服务器有意义。
参数
long prefetch-size
客户端可以请求提前发送消息,以便在客户端完成消息处理后,下一条消息已经保存在本地,而不是需要通过通道发送。预取可以提高性能。此字段指定以字节为单位的预取窗口大小。如果消息的大小等于或小于可用的预取大小(并且也符合其他预取限制),服务器将提前发送消息。可以设置为零,表示“没有特定限制”,尽管其他预取限制可能仍然适用。如果设置了 no-ack 选项,则 prefetch-size 将被忽略。
当客户端没有处理任何消息时,服务器必须忽略此设置,即预取大小不限制将单个消息传输到客户端,而仅限制在客户端仍然有一条或多条未确认消息时提前发送更多消息。
short prefetch-count
以整个消息为单位指定预取窗口。此字段可以与 prefetch-size 字段结合使用;仅当两个预取窗口(以及通道和连接级别上的预取窗口)都允许时,才会提前发送消息。如果设置了 no-ack 选项,则 prefetch-count 将被忽略。
服务器可能提前发送的数据少于客户端指定的预取窗口允许的数据,但不得发送更多数据。
bit global
RabbitMQ 重新解释了此字段。原始规范说:“默认情况下,QoS 设置仅应用于当前通道。如果设置了此字段,它们将应用于整个连接。” 相反,RabbitMQ 将 global=false 解释为 QoS 设置应按消费者应用(对于通道上的新消费者;现有消费者不受影响),并将 global=true 解释为 QoS 设置应按通道应用。
(返回顶部)qos-ok()
确认请求的 QoS。
此方法告诉客户端,服务器可以处理请求的 QoS 级别。请求的 QoS 应用于所有活动消费者,直到定义新的 QoS 为止。
(返回顶部)consume(
启动队列消费者。
此方法要求服务器启动一个“消费者”,它是一个从特定队列请求消息的瞬态请求。消费者持续时间与它们声明所在的通道一样长,或者直到客户端取消它们为止。
服务器应该支持每个队列至少 16 个消费者,理想情况下,除了可用资源定义的限制之外,没有限制。
参数
短整型 保留 1
queue-name queue
指定要从中消费的队列的名称。
consumer-tag consumer-tag
指定消费者的标识符。消费者标签在通道内是本地的,因此两个客户端可以使用相同的消费者标签。如果此字段为空,服务器将生成一个唯一的标签。
no-local no-local
no-ack no-ack
bit exclusive
请求独占消费者访问,这意味着只有此消费者可以访问队列。
客户端可能无法获得对已经具有活动消费者的队列的独占访问权。
错误代码:拒绝访问
no-wait no-wait
table arguments
一组用于消费的参数。这些参数的语法和语义取决于服务器实现。
(返回顶部)consume-ok(
确认新消费者。
服务器为客户端提供一个消费者标签,客户端在稍后阶段调用消费者上的方法时使用该标签。
参数
consumer-tag consumer-tag
保存由客户端指定或由服务器提供的消费者标签。
(返回顶部)cancel(
结束队列消费者。
此方法取消消费者。这不会影响已传递的消息,但它意味着服务器不会再为该消费者发送任何消息。客户端可能会在发送取消方法和接收取消确认回复之间接收任意数量的消息。它也可能由服务器在消费者意外取消的情况下(即由于任何原因取消,而不是服务器收到来自客户端的相应基本取消)发送到客户端。这允许客户端在由于队列删除等事件导致消费者丢失时收到通知。请注意,由于客户端不必从服务器接受此方法,因此建议代理能够通过某种能力协商方式识别能够接受此方法的客户端。
如果队列不存在,只要消费者标签对该通道有效,服务器就必须忽略取消方法。
参数
consumer-tag consumer-tag
no-wait no-wait
(返回顶部)cancel-ok(
确认取消的消费者。
此方法确认已完成取消。
参数
consumer-tag consumer-tag
(返回顶部)publish(
发布消息。
此方法将消息发布到特定的交换机。消息将根据交换机配置路由到队列,并在事务(如果有)提交时分发给所有活动消费者。
参数
短整型 保留 1
交换名称 交换
指定要发布到的交换机的名称。交换机名称可以为空,表示默认交换机。如果指定了交换机名称,但该交换机不存在,服务器将引发通道异常。
客户端不得尝试将内容发布到不存在的交换机。
错误代码: not-found服务器 MUST 接受空白的交换器名称表示默认交换器。
如果交换机声明为内部交换机,服务器必须引发通道异常,并回复代码 403(访问被拒绝)。
交换机可以拒绝基本内容,在这种情况下,它必须引发通道异常,并回复代码 540(未实现)。
shortstr routing-key
指定消息的路由键。路由键用于根据交换机配置路由消息。
bit mandatory
此标志告诉服务器在消息无法路由到队列时如何反应。如果设置了此标志,服务器将返回不可路由消息,并附带一个返回方法。如果此标志为零,服务器将静默丢弃消息。
服务器应实现强制标志。
bit immediate
此标志告诉服务器在消息无法立即路由到队列消费者时如何反应。如果设置了此标志,服务器将返回不可投递消息,并附带一个返回方法。如果此标志为零,服务器将排队消息,但不能保证消息会被消费。
服务器应实现立即标志。
return(
返回失败的消息。
此方法返回不可投递消息,该消息是在设置了“立即”标志的情况下发布的,或者是在设置了“强制”标志的情况下发布的不可路由消息。回复代码和文本提供有关消息不可投递的原因的信息。
参数
回复代码 回复代码
回复文本 回复文本
交换名称 交换
指定消息最初发布到的交换机的名称。可以为空,表示默认交换机。
shortstr routing-key
指定发布消息时指定的路由键名称。
(返回顶部)deliver(
通知客户端消费者消息。
此方法通过消费者将消息传递给客户端。在异步消息传递模型中,客户端使用 Consume 方法启动消费者,然后服务器在消息到达该消费者时响应 Deliver 方法。
服务器应跟踪消息传递给客户端的次数,以及消息被重新传递一定次数(例如 5 次)后未被确认时,服务器应将消息视为不可处理(可能导致客户端应用程序中止),并将消息移动到死信队列。
参数
consumer-tag consumer-tag
delivery-tag delivery-tag
redelivered redelivered
交换名称 交换
指定消息最初发布到的交换机的名称。可以为空,表示默认交换机。
shortstr routing-key
指定发布消息时指定的路由键名称。
(返回顶部)get(
直接访问队列。
此方法提供对队列中消息的直接访问,使用同步对话,该对话专为特定类型的应用程序设计,在这些应用程序中,同步功能比性能更重要。
参数
短整型 保留 1
queue-name queue
指定要从中获取消息的队列的名称。
no-ack no-ack
(返回顶部)get-ok(
向客户端提供消息。
此方法在 get 方法之后向客户端传递消息。由“get-ok”传递的消息必须被确认,除非在 get 方法中设置了 no-ack 选项。
参数
delivery-tag delivery-tag
redelivered redelivered
交换名称 交换
指定消息最初发布到的交换机的名称。如果为空,则消息发布到默认交换机。
shortstr routing-key
指定发布消息时指定的路由键名称。
message-count message-count
(返回顶部)get-empty(
指示没有可用消息。
此方法告诉客户端队列没有可供客户端使用的消息。
参数
shortstr reserved-1
(返回顶部)ack(
确认一条或多条消息。
当由客户端发送时,此方法确认通过 Deliver 或 Get-Ok 方法传递的一条或多条消息。当由服务器发送时,此方法确认通过 Publish 方法在确认模式下的通道上发布的一条或多条消息。确认可以针对单个消息,也可以针对一组消息,直至并包括特定消息。
参数
delivery-tag delivery-tag
bit multiple
如果设置为 1,则传递标签将被视为“直至并包括”,这样就可以使用单个方法确认多条消息。如果设置为零,则传递标签是指单个消息。如果 multiple 字段为 1,且传递标签为零,则表示确认所有未决消息。
消息不得确认多次。接收方必须验证非零传递标签是否引用传递的消息,如果情况并非如此,则引发通道异常。在事务性通道上,必须立即执行此检查,不要延迟到 Tx.Commit。
错误代码:先决条件失败
reject(
拒绝传入消息。
此方法允许客户端拒绝消息。它可用于中断和取消大型传入消息,或将不可处理的消息返回到其原始队列。
服务器应能够在使用 Deliver 或 Get-Ok 方法发送消息内容时接受和处理 Reject 方法。即,服务器应在发送输出帧时读取和处理传入方法。要取消部分发送的内容,服务器发送大小为 1 的内容主体帧(即,除了帧结束八位字节外没有数据)。
服务器应将此方法解释为表示客户端目前无法处理消息。
客户端不得使用此方法作为选择要处理的消息的方式。
参数
delivery-tag delivery-tag
bit requeue
如果 requeue 为真,服务器将尝试重新排队消息。如果 requeue 为假或重新排队尝试失败,消息将被丢弃或死信处理。
服务器不得将消息传递给当前通道上下文中的同一个客户端。建议的策略是尝试将消息传递给备用消费者,如果不可行,则将消息移动到死信队列。服务器可以使用更复杂的跟踪来将消息保留在队列中并在以后阶段将其重新传递给同一个客户端。
recover-async(
重新传递未确认的消息。
此方法要求服务器重新传递指定通道上的所有未确认的消息。可能会重新传递零条或多条消息。此方法已过时,建议使用同步 Recover/Recover-Ok。
服务器必须在所有重新发送的消息上设置 redelivered 标志。
参数
bit requeue
如果此字段为零,则消息将被重新传递给原始接收方。如果此位为 1,则服务器将尝试重新排队消息,然后可能将其传递给备用订阅者。
(返回顶部)recover(
重新传递未确认的消息。
此方法要求服务器重新传递指定通道上的所有未确认的消息。可能会重新传递零条或多条消息。此方法替换异步 Recover。
服务器必须在所有重新发送的消息上设置 redelivered 标志。
参数
bit requeue
如果此字段为零,则消息将被重新传递给原始接收方。如果此位为 1,则服务器将尝试重新排队消息,然后可能将其传递给备用订阅者。
(返回顶部)recover-ok(p)
确认恢复。
此方法确认 Basic.Recover 方法。
(返回顶部)nack(
拒绝一条或多条传入消息。
此方法允许客户端拒绝一条或多条传入消息。它可用于中断和取消大型传入消息,或将不可处理的消息返回到其原始队列。此方法还由服务器用于通知确认模式下通道上的发布者未处理的消息。如果发布者收到此方法,则可能需要重新发布有问题的消息。
服务器应能够在使用 Deliver 或 Get-Ok 方法发送消息内容时接受和处理 Nack 方法。即,服务器应在发送输出帧时读取和处理传入方法。要取消部分发送的内容,服务器发送大小为 1 的内容主体帧(即,除了帧结束八位字节外没有数据)。
服务器应将此方法解释为表示客户端目前无法处理消息。
客户端不得使用此方法作为选择要处理的消息的方式。
将消息发布到确认模式下通道的客户端应能够接受并以某种方式处理 Nack 方法。
参数
delivery-tag delivery-tag
bit multiple
如果设置为 1,则传递标签将被视为“直至并包括”,这样就可以使用单个方法拒绝多条消息。如果设置为零,则传递标签是指单个消息。如果 multiple 字段为 1,且传递标签为零,则表示拒绝所有未决消息。
消息不得拒绝多次。接收方必须验证非零传递标签是否引用未确认的传递消息,如果情况并非如此,则引发通道异常。
错误代码:先决条件失败
bit requeue
如果 `requeue` 为真,服务器将尝试重新排队消息。如果 `requeue` 为假或重新排队尝试失败,消息将被丢弃或进入死信队列。接收 Nack 方法的客户端应忽略此标志。
服务器不得将消息传递给当前通道上下文中的同一个客户端。建议的策略是尝试将消息传递给备用消费者,如果不可行,则将消息移动到死信队列。服务器可以使用更复杂的跟踪来将消息保留在队列中并在以后阶段将其重新传递给同一个客户端。
tx
使用事务。
Tx 类允许将发布和确认操作批处理成原子工作单元。目的是,在事务中发出的所有发布和确认请求都将成功完成,或者一个也不成功。服务器应该至少在所有发布或确认请求影响单个队列的情况下实现原子事务。跨越多个队列的事务可能是非原子的,因为队列可以异步创建和销毁,并且此类事件不构成任何事务的一部分。此外,事务相对于 Basic.Publish 方法上的立即和强制标志的行为没有定义。
类语法
tx = C:SELECT S:SELECT-OK / C:COMMIT S:COMMIT-OK / C:ROLLBACK S:ROLLBACK-OK
应用程序不能依赖影响多个队列的事务的原子性。
应用程序不能依赖包含使用立即选项发布的消息的事务的行为。
应用程序不能依赖包含使用强制选项发布的消息的事务的行为。
方法
select() ➔ select-ok
) ➔ select-ok
选择标准事务模式。
此方法将通道设置为使用标准事务。客户端必须在使用 Commit 或 Rollback 方法之前至少在通道上使用此方法一次。
(返回顶部)select-ok()
确认事务模式。
此方法向客户端确认通道已成功设置为使用标准事务。
(返回顶部)commit() ➔ commit-ok
) ➔ commit-ok
提交当前事务。
此方法提交在当前事务中执行的所有消息发布和确认。在提交之后立即开始新的事务。
客户端不能在非事务通道上使用 Commit 方法。
错误代码:先决条件失败
commit-ok()
确认成功提交。
此方法向客户端确认提交成功。请注意,如果提交失败,服务器将引发通道异常。
(返回顶部)rollback() ➔ rollback-ok
) ➔ rollback-ok
放弃当前事务。
此方法放弃在当前事务中执行的所有消息发布和确认。在回滚之后立即开始新的事务。请注意,未确认的消息不会被回滚自动重新传递;如果需要重新传递,则应发出显式的恢复调用。
客户端不能在非事务通道上使用 Rollback 方法。
错误代码:先决条件失败
rollback-ok()
确认成功回滚。
此方法向客户端确认回滚成功。请注意,如果回滚失败,服务器将引发通道异常。
(返回顶部)confirm
使用确认。
Confirm 类允许发布者将通道置于确认模式,并在随后收到有关消息已被代理处理的通知。目的是,在确认模式下在通道上发布的所有消息将在某个时间点被确认。通过确认消息,代理承担对它的责任并表明它已经对其进行了它认为合理的操作。无法路由的强制或立即消息在 Basic.Return 方法之后立即被确认。当消息已路由到的所有队列都已传递消息并收到确认(如果需要)或已排队消息(如果需要则已持久化)时,将确认消息。已发布的消息将分配从 1 开始的递增序列号,从第一个 Confirm.Select 方法开始。服务器通过发送引用这些序列号的 Basic.Ack 方法来确认消息。
类语法
confirm = C:SELECT S:SELECT-OK
服务器必须确认通道置于确认模式后接收的所有消息。
服务器必须在消息被传递到的所有队列正确处理之后才确认消息。
服务器必须在发送 Basic.Return 后才确认无法路由的强制或立即消息。
关于消息确认的快慢没有保证。应用程序不应对此做出假设。
方法
select(
.
此方法将通道设置为使用发布者确认。客户端只能在非事务通道上使用此方法。
参数
no-wait nowait
(返回顶部)select-ok()
.
此方法向客户端确认通道已成功设置为使用发布者确认。
(返回顶部)规范中定义了以下域
名称 | 类型 | 描述 |
---|---|---|
bit | bit | [单个位] |
class-id | short | |
consumer-tag | shortstr | 消费者的标识符,在当前通道内有效。 |
delivery-tag | longlong | 服务器分配的特定于通道的传递标签
|
exchange-name | shortstr | 交换机名称是客户端选择的字符串,用于标识发布方法的交换机。 |
long | long | [32 位整数] |
longlong | longlong | [64 位整数] |
longstr | longstr | [长字符串] |
message-count | long | 队列中的消息数量,对于新声明的队列,此数量将为零。这是队列中存在的、未等待确认的、并且如果发布它们的通道是事务性的则已提交的消息数量。 |
method-id | short | |
no-ack | bit | 如果设置此字段,服务器将不期望对消息进行确认。也就是说,当消息传递给客户端时,服务器假设传递将成功并立即将其从队列中删除。此功能可能会提高性能,但以可靠性为代价。如果客户端在消息传递给应用程序之前死亡,消息可能会丢失。 |
no-local | bit | 如果设置 no-local 字段,服务器将不会将消息发送到发布它们的连接。 |
no-wait | bit | 如果设置,服务器将不会响应该方法。客户端不应等待回复方法。如果服务器无法完成该方法,它将引发通道或连接异常。 |
octet | octet | [单个字节] |
path | shortstr | 不受约束。 |
peer-properties | table | 此表提供一组对等属性,用于标识、调试和一般信息。 |
queue-name | shortstr | 队列名称标识 vhost 中的队列。在队列名称可能为空且没有特殊意义的方法中,这指的是通道的“当前”队列,即客户端在通道上声明的最后一个队列。如果客户端没有声明队列,并且该方法需要队列名称,则将导致 502(语法错误)通道异常。 |
redelivered | bit | 这表示消息之前已传递到此客户端或其他客户端。
|
reply-code | short | 回复代码。AMQ 回复代码在此正式规范开头定义为常量。 |
reply-text | shortstr | 本地化的回复文本。此文本可以被记录下来以帮助解决问题。 |
short | short | [16 位整数] |
shortstr | shortstr | [短字符串(最大 256 个字符)] |
table | table | [字段表] |
timestamp | timestamp | [64 位时间戳] |
许多常量是错误代码。如果是这样,它们将分为两类
- 通道错误:这些与影响当前通道但不影响从相同连接创建的其他通道的故障相关联。
- 连接错误:这些与阻止连接上任何进一步活动的故障相关联,并且要求关闭连接。
规范中定义了以下常量
名称 | 值 | 错误类 | 描述 |
---|---|---|---|
frame-method | 1 | ||
frame-header | 2 | ||
frame-body | 3 | ||
frame-heartbeat | 8 | ||
frame-min-size | 4096 | ||
frame-end | 206 | ||
reply-success | 200 | 表示该方法成功完成。此回复代码保留供将来使用 - 当前协议设计不使用正确认,并且只有在出现错误时才会发送回复代码。 | |
content-too-large | 311 | 通道 | 客户端尝试传输的内容大小超过服务器目前能够接受的大小。客户端可以在稍后重新尝试。 |
no-route | 312 | 通道 | 当 RabbitMQ 在“强制”消息无法传递到任何队列时使用“basic.return”返回时返回。 |
no-consumers | 313 | 通道 | 当交换机在设置立即标志时无法传递给消费者时。这是由于队列上的挂起数据或队列上没有消费者导致的。 |
connection-forced | 320 | 连接 | 操作员出于某种原因干预以关闭连接。客户端可以在稍后重新尝试。 |
invalid-path | 402 | 连接 | 客户端尝试使用未知的虚拟主机进行操作。 |
access-refused | 403 | 通道 | 客户端尝试使用由于安全设置而无法访问的服务器实体进行操作。 |
not-found | 404 | 通道 | 客户端尝试使用不存在的服务器实体进行操作。 |
resource-locked | 405 | 通道 | 客户端尝试使用由于其他客户端正在使用而无法访问的服务器实体进行操作。 |
precondition-failed | 406 | 通道 | 客户端请求了由于某些先决条件失败而被禁止的方法。 |
frame-error | 501 | 连接 | 发送方发送了接收方无法解码的格式错误的帧。这强烈暗示发送方对等体中的编程错误。 |
syntax-error | 502 | 连接 | 发送方发送了包含一个或多个字段的非法值的帧。这强烈暗示发送方对等体中的编程错误。 |
command-invalid | 503 | 连接 | 客户端发送了无效的帧序列,试图执行服务器认为无效的操作。这通常意味着客户端中的编程错误。 |
channel-error | 504 | 连接 | 客户端尝试使用未正确打开的通道进行操作。这很可能表示客户端层中的故障。 |
unexpected-frame | 505 | 连接 | 对等体发送了意外的帧,通常是在内容标头和正文的上下文中。这强烈暗示对等体的内容处理中的故障。 |
resource-error | 506 | 连接 | 服务器无法完成该方法,因为它缺少足够的资源。这可能是由于客户端创建了太多某种类型的实体造成的。 |
not-allowed | 530 | 连接 | 由于安全设置或其他条件,客户端尝试以服务器禁止的方式使用某个实体。 |
未实现 | 540 | 连接 | 客户端尝试使用服务器未实现的功能。 |
内部错误 | 541 | 连接 | 由于内部错误,服务器无法完成该方法。服务器可能需要操作员干预才能恢复正常运行。 |
获取帮助并提供反馈
如果您对本指南内容或与 RabbitMQ 相关的任何其他主题有任何疑问,请随时使用 GitHub 讨论 或我们的社区 Discord 服务器 提出问题。
帮助我们改进文档 <3
如果您想为该网站贡献改进,它的源代码在 GitHub 上可用。只需分叉存储库并提交拉取请求。谢谢!