Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

使用 AMQ Ruby 客户端

Red Hat AMQ Clients 2.11

用于 AMQ Clients 2.11

摘要

本指南论述了如何安装和配置客户端，运行实践示例，并将您的客户端与其他 AMQ 组件一起使用。

使开源包含更多
复制链接

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情，请参阅我们的首席技术官 Chris Wright 提供的消息。

第 1 章 概述
复制链接

AMQ Ruby 是一个用于开发消息传递应用程序的库。它允许您编写发送和接收 AMQP 消息的 Ruby 应用程序。

重要

AMQ Ruby 客户端只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。

有关红帽技术预览功能支持范围的详情，请参考 https://access.redhat.com/support/offerings/techpreview/。

AMQ Ruby 是 AMQ 客户端的一部分，这是支持多种语言和平台的一系列消息传递库。有关客户端的概述，请参阅 AMQ 客户端概述。有关此发行版本的详情，请参考 AMQ Clients 2.11 发行注记。

AMQ Ruby 基于 Apache Qpid 中的 Proton API。有关详细的 API 文档，请参阅 AMQ Ruby API 参考。

1.1. 主要特性
复制链接

  • 简化了与现有应用程序集成的事件驱动的 API
  • 用于安全通信的 SSL/TLS
  • 灵活的 SASL 身份验证
  • 自动重新连接和故障转移
  • AMQP 和语言原生数据类型之间的无缝转换
  • 访问 AMQP 1.0 的所有特性和功能

1.2. 支持的标准和协议
复制链接

AMQ Ruby 支持以下行业识别的标准和网络协议：

1.3. 支持的配置
复制链接

有关 AMQ Ruby 支持的配置 的当前信息，请参阅红帽客户门户网站上的 Red Hat AMQ 支持的配置。

1.4. 术语和概念
复制链接

本节介绍核心 API 实体，并描述它们如何一起工作。

Expand
表 1.1. API 术语
实体描述

Container

连接的顶级容器。

连接

网络上两个对等点间的通信的频道。它包含会话。

会话

发送和接收消息的上下文。它包含发送者和接收器。

sender

将信息发送到目标的频道。它有一个目标。

receiver

从源接收消息的频道。它有一个源。

源

用于消息的命名源点。

目标

消息的命名目的地。

消息

特定于应用程序的信息片段。

交付

消息传输。

AMQ Ruby 发送并 接收消息。通过 发送方 和接收器在连接的对等点之间传输消息。发件人和接收器通过会话 建立。会话通过 连接建立。连接在两个唯一标识 的容器 之间建立。虽然连接可以有多个会话，但通常不需要这样做。API 允许您忽略会话，除非您需要它们。

发送对等点会创建发送邮件的发送者。发件人具有在远程对等点上标识队列或主题 的目标。接收对等点会创建一个接收消息的接收器。接收器有一个 源，用于标识远程对等点上的队列或主题。

消息发送称为发送。消息是发送的内容，包括标头和注解等所有元数据。交付是与该内容传输相关联的协议交换。

要指示发送已经完成，发送是发送，可以是发送，也可以是接收方。当另一端了解了它时，它将不再传达该交付。接收器也可以指示它接受或拒绝该消息。

1.5. 文档惯例
复制链接

sudo 命令

在本文档中，sudo 用于任何需要 root 特权的命令。使用 sudo 时请谨慎操作，因为任何更改都可能会影响整个系统。有关 sudo 的更多信息，请参阅使用 sudo 命令。

文件路径

在本文档中，所有文件路径都对 Linux、UNIX 和类似操作系统（例如 /home/andrea）有效。在 Microsoft Windows 上，您必须使用对应的 Windows 路径（例如 C:\Users\andrea）。

变量文本

本文档包含代码块，其中的变量必须替换为特定于您的环境的值。变量文本以箭头括号括起，样式为方便的 monospace。例如，使用以下命令将 < project-dir&gt; 替换为环境的值： 

$ cd <project-dir>
Copy to Clipboard Toggle word wrap

第 2 章 安装
复制链接

本章介绍了在您的环境中安装 AMQ Ruby 的步骤。

2.1. 前提条件
复制链接

  • 您必须具有访问 AMQ 发行文件和软件仓库 的订阅。
  • 要在 Red Hat Enterprise Linux 上安装软件包，您必须 注册您的系统。
  • 要使用 AMQ Ruby，您必须在您的环境中安装 Ruby。

2.2. 在 Red Hat Enterprise Linux 上安装
复制链接

流程

  1. 使用 subscription-manager 命令订阅所需的软件包存储库。将 <version > 替换为主发行流的 2，或将 2.11 替换用于长期支持发行流。如有必要，将 < variant> 替换为您的 Red Hat Enterprise Linux 变体的值（如 server 或 workstation）。

    Red Hat Enterprise Linux 7

    $ sudo subscription-manager repos --enable=amq-clients-<version>-for-rhel-7-<variant>-rpms
    Copy to Clipboard Toggle word wrap

    Red Hat Enterprise Linux 8

    $ sudo subscription-manager repos --enable=amq-clients-<version>-for-rhel-8-x86_64-rpms
    Copy to Clipboard Toggle word wrap

  2. 使用 yum 命令安装 rubygem-qpid_proton 和 rubygem-qpid_proton-doc 软件包。 

    $ sudo yum install rubygem-qpid_proton rubygem-qpid_proton-doc
    Copy to Clipboard Toggle word wrap

有关使用软件包的详情请参考 附录 B, 使用 Red Hat Enterprise Linux 软件包。

第 3 章 开始使用
复制链接

本章介绍了设置环境并运行简单的消息传递程序的步骤。

3.1. 前提条件
复制链接

  • 您必须为您的环境 完成安装过程。
  • 您必须有一个 AMQP 1.0 消息代理侦听接口 localhost 和端口 5672 上的连接。它必须启用匿名访问权限。如需更多信息，请参阅 启动代理。
  • 您必须有一个名为 example 的队列。如需更多信息，请参阅创建队列。

3.2. 运行 Hello World
复制链接

Hello World 示例创建了一个与代理的连接，发送一条消息，其中包含到 示例 队列的问候消息，然后接收它。成功时，它会将收到的消息输出到控制台。

更改到 examples 目录，再运行 helloworld.rb 示例。 

$ cd /usr/share/proton/examples/ruby/
$ ruby helloworld.rb amqp://127.0.0.1 examples
Hello World!
Copy to Clipboard Toggle word wrap

第 4 章 例子
复制链接

本章演示了通过示例程序使用 AMQ Ruby。

如需了解更多示例，请参阅 AMQ Ruby 示例套件和 Qpid Proton Ruby 示例。

4.1. 发送消息
复制链接

此客户端程序使用 < connection-url > 连接到服务器，为目标 <address& gt; 创建发件人，发送一条消息，包含 <message-body >、关闭连接并退出。

示例：发送消息

require 'qpid_proton'

class SendHandler < Qpid::Proton::MessagingHandler
  def initialize(conn_url, address, message_body)
    super()

    @conn_url = conn_url
    @address = address
    @message_body = message_body
  end

  def on_container_start(container)
    conn = container.connect(@conn_url)
    conn.open_sender(@address)
  end

  def on_sender_open(sender)
    puts "SEND: Opened sender for target address '#{sender.target.address}'\n"
  end

  def on_sendable(sender)
    message = Qpid::Proton::Message.new(@message_body)
    sender.send(message)

    puts "SEND: Sent message '#{message.body}'\n"

    sender.close
    sender.connection.close
  end
end

if ARGV.size == 3
  conn_url, address, message_body = ARGV
else
  abort "Usage: send.rb <connection-url> <address> <message-body>\n"
end

handler = SendHandler.new(conn_url, address, message_body)
container = Qpid::Proton::Container.new(handler)
container.run
Copy to Clipboard Toggle word wrap

运行示例

要运行示例程序，请将其复制到本地文件中，并使用 ruby 命令调用它。如需更多信息，请参阅 第 3 章 开始使用。 

$ ruby send.rb amqp://localhost queue1 hello
Copy to Clipboard Toggle word wrap

4.2. 接收信息
复制链接

此客户端程序使用 < connection-url > 连接到服务器，为源 <address& gt; 创建一个接收器，并接收信息直到终止或到达 < count> 信息。

示例：接收信息

require 'qpid_proton'

class ReceiveHandler < Qpid::Proton::MessagingHandler
  def initialize(conn_url, address, desired)
    super()

    @conn_url = conn_url
    @address = address

    @desired = desired
    @received = 0
  end

  def on_container_start(container)
    conn = container.connect(@conn_url)
    conn.open_receiver(@address)
  end

  def on_receiver_open(receiver)
    puts "RECEIVE: Opened receiver for source address '#{receiver.source.address}'\n"
  end

  def on_message(delivery, message)
    puts "RECEIVE: Received message '#{message.body}'\n"

    @received += 1

    if @received == @desired
      delivery.receiver.close
      delivery.receiver.connection.close
    end
  end
end

if ARGV.size > 1
  conn_url, address = ARGV[0..1]
else
  abort "Usage: receive.rb <connection-url> <address> [<message-count>]\n"
end

begin
  desired = Integer(ARGV[2])
rescue TypeError
  desired = 0
end

handler = ReceiveHandler.new(conn_url, address, desired)
container = Qpid::Proton::Container.new(handler)
container.run
Copy to Clipboard Toggle word wrap

运行示例

要运行示例程序，请将其复制到本地文件中，并使用 ruby 命令调用它。如需更多信息，请参阅 第 3 章 开始使用。 

$ ruby receive.rb amqp://localhost queue1
Copy to Clipboard Toggle word wrap

第 5 章 网络连接
复制链接

5.1. 连接 URL
复制链接

连接 URL 对用于建立新连接的信息进行编码。

连接 URL 语法

scheme://host[:port]
Copy to Clipboard Toggle word wrap

  • scheme - 连接传输，用于未加密的 TCP 的 amqp 或使用 SSL/TLS 加密的 TCP 的 amqp。
  • Host - 远程网络主机。该值可以是主机名或数字 IP 地址。IPv6 地址必须包括在方括号中。
  • port - 远程网络端口。这个值是可选的。对于 amqp 方案，默认值是 5672，amqps 方案的 5671。

连接 URL 示例

amqps://example.com
amqps://example.net:56720
amqp://127.0.0.1
amqp://[::1]:2000
Copy to Clipboard Toggle word wrap

第 6 章 发件人和接收器
复制链接

客户端使用发送方和接收器链接来代表传递消息的频道。发件人和接收器是单向的，消息来源的源结尾和消息目的地的目标结尾。

源和目标通常指向消息代理上的队列或主题。源也用于代表订阅。

6.1. 根据需要创建队列和主题
复制链接

有些消息服务器支持按需创建队列和主题。附加发送方或接收器时，服务器使用发送者目标地址或接收器源地址来创建名称与地址匹配的队列或主题。

邮件服务器通常默认为创建队列（用于一对一消息发送）或主题（用于一对多消息发送）。客户端可以通过在源或目标上设置 队列或主题 功能来指示首选情况。

如需了解更多详细信息，请参阅以下示例：

6.2. 创建持久订阅
复制链接

持久化订阅是远程服务器上的一个状态，代表一个消息接收器。通常，当客户端关闭时，消息接收方会被丢弃。但是，由于持久订阅是持久的，客户端可以从它们分离，之后再重新连接。当客户端重新附加时，任何在分离时收到的消息都可用。

持久化订阅通过组合客户端容器 ID 和接收器名称来组成订阅 ID 来唯一标识。它们必须具有稳定的值，以便可以恢复订阅。

示例

6.3. 创建共享订阅
复制链接

共享订阅是远程服务器中代表一个或多个消息接收器的状态。由于它是共享的，多个客户端可以从同一消息流使用。

客户端通过在接收器源上设置 共享功能来配置共享 订阅。

共享订阅通过组合客户端容器 ID 和接收器名称来组成订阅 ID 来唯一标识。它们必须具有稳定的值，以便多个客户端进程可以找到相同的订阅。如果除了 共享 外设置了 全局 功能，则仅接收方名称用于标识订阅。

示例

第 7 章 日志记录
复制链接

7.1. 启用协议日志记录
复制链接

客户端可以将 AMQP 协议帧记录到控制台。诊断问题时，这些数据通常至关重要。

要启用协议日志记录，请将 PN_TRACE_FRM 环境变量设置为 1：

示例：启用协议日志记录

$ export PN_TRACE_FRM=1
$ <your-client-program>
Copy to Clipboard Toggle word wrap

要禁用协议日志记录，请取消设置 PN_TRACE_FRM 环境变量。

第 8 章 互操作性
复制链接

本章讨论了如何将 AMQ Ruby 与其他 AMQ 组件结合使用。有关 AMQ 组件的兼容性概述，请参阅 产品简介。

8.1. 与其他 AMQP 客户端交互
复制链接

AMQP 消息使用 AMQP 类型系统 组成。这种通用格式是以不同语言的 AMQP 客户端能够相互互操作的原因之一。

在发送消息时，AMQ Ruby 会自动将语言原生类型转换为 AMQP 编码的数据。收到信息时，反向转换就发生。

注意

有关 AMQP 类型的更多信息，请访问由 Apache Qpid 项目维护 的交互式类型参考。

Expand
表 8.1. AMQP 类型
AMQP 类型描述

null

一个空值

布尔值

true 或 false 值

char

单个 Unicode 字符

string

一系列 Unicode 字符

二进制

一个字节序列

byte

签名的 8 位整数

short

签名的 16 位整数

int

签名的 32 位整数

long

签名的 64 位整数

ubyte

未签名的 8 位整数

ushort

未签名的 16 位整数

uint

未签名的 32 位整数

ulong

未签名的 64 位整数

浮点值

32 位浮点号

double

64 位浮点号

数组

单个类型的值的序列

list

变量类型的序列值

map

从不同键到值的映射

uuid

通用唯一标识符

符号

来自受限域的 7 位 ASCII 字符串

timestamp

一个绝对时间点

Expand
表 8.2. 在编码前和解码后 AMQ Ruby 类型
AMQP 类型在编码前 AMQ Ruby 类型解码后 AMQ Ruby 类型

null

nil

nil

布尔值

true, false

true, false

char

-

字符串

字符串

字符串

字符串

二进制

-

字符串

byte

-

整数

short

-

整数

int

-

整数

long

整数

整数

ubyte

-

整数

ushort

-

整数

uint

-

整数

ulong

-

整数

浮点值

-

浮点值

double

浮点值

浮点值

数组

-

Array

list

Array

Array

map

hash

hash

符号

符号

符号

timestamp

日期、时间

Time

Expand
表 8.3. AMQ Ruby 和其他 AMQ 客户端类型(2 为 1)
在编码前 AMQ Ruby 类型AMQ C++ 类型AMQ JavaScript 类型

nil

nullptr

null

true, false

bool

布尔值

字符串

std::string

字符串

整数

int64_t

number

浮点值

double

number

Array

std::vector

Array

hash

std::map

object

符号

proton::symbol

字符串

日期、时间

proton::timestamp

number

Expand
表 8.4. AMQ Ruby 和其他 AMQ 客户端类型(2 个)
在编码前 AMQ Ruby 类型AMQ .NET 类型AMQ Python 类型

nil

null

None

true, false

system.Boolean

bool

字符串

system.String

unicode

整数

System.Int64

long

浮点值

system.Double

浮点值

Array

Amqp.List

list

hash

Amqp.Map

dict

符号

Amqp.Symbol

str

日期、时间

System.DateTime

long

8.2. 使用 AMQ JMS 进行交互
复制链接

AMQP 定义标准映射到 JMS 消息传递模型。本节讨论该映射的各个方面。如需更多信息，请参阅 AMQ JMS Interoperability 章节。

JMS 消息类型

AMQ Ruby 提供了一个单一消息类型，其正文类型可能会有所不同。相反，JMS API 使用不同的消息类型来代表不同类型的数据。下表标明特定的正文类型如何映射到 JMS 消息类型。

若要更明确地控制生成的 JMS 消息类型，您可以设置 x-opt-jms-msg-type 消息注释。如需更多信息，请参阅 AMQ JMS Interoperability 章节。

Expand
表 8.5. AMQ Ruby 和 JMS 消息类型
AMQ Ruby 正文类型JMS 消息类型

字符串

TextMessage

nil

TextMessage

-

BytesMessage

任何其他类型

ObjectMessage

8.3. 连接到 AMQ Broker
复制链接

AMQ Broker 旨在与 AMQP 1.0 客户端互操作。检查以下内容以确保为 AMQP 消息传递配置了代理：

附录 A. 使用您的订阅
复制链接

AMQ 通过软件订阅提供。要管理您的订阅，请访问红帽客户门户中的帐户。

A.1. 访问您的帐户
复制链接

流程

  1. 转至 access.redhat.com。
  2. 如果您还没有帐户，请创建一个帐户。
  3. 登录到您的帐户。

A.2. 激活订阅
复制链接

流程

  1. 转至 access.redhat.com。
  2. 导航到 My Subscriptions。
  3. 导航到 激活订阅 并输入您的 16 位激活号。

A.3. 下载发行文件
复制链接

要访问 .zip、.tar.gz 和其他发布文件，请使用客户门户查找要下载的相关文件。如果您使用 RPM 软件包或 Red Hat Maven 存储库，则不需要这一步。

流程

  1. 打开浏览器并登录红帽客户门户网站 产品下载页面，网址为 access.redhat.com/downloads。
  2. 查找 INTEGRATION 目录中的红帽 AMQ 条目。
  3. 选择所需的 AMQ 产品。此时会打开 Software Downloads 页面。
  4. 单击组件的 Download 链接。

A.4. 为系统注册软件包
复制链接

要在 Red Hat Enterprise Linux 上安装此产品的 RPM 软件包，必须注册您的系统。如果您使用下载的发行文件，则不需要这一步。

流程

  1. 转至 access.redhat.com。
  2. 进入 Registration Assistant。
  3. 选择您的操作系统版本，再继续到下一页。
  4. 使用您的系统终端中列出的命令完成注册。

有关注册您的系统的更多信息，请参阅以下资源之一：

附录 B. 使用 Red Hat Enterprise Linux 软件包
复制链接

这部分论述了如何使用作为 Red Hat Enterprise Linux 的 RPM 软件包提供的软件。

要确保此产品的 RPM 软件包可用，您必须首先 注册您的系统。

B.1. 概述
复制链接

库或服务器等组件通常关联有多个软件包。您不必安装它们。您只能安装您需要的用户。

主软件包通常具有最简单的名称，而不带有其他限定符。这个软件包提供了在程序运行时使用组件所需的所有接口。

名称以 -devel 结尾的软件包包含 C 和 C++ 库的标头。在编译时，需要它们来构建依赖于此软件包的程序。

名称以 -docs 结尾的软件包包含组件的文档和示例程序。

有关使用 RPM 软件包的更多信息，请参阅以下资源之一：

B.2. 搜索软件包
复制链接

要搜索软件包，请使用 yum search 命令。搜索结果包括软件包名称，您可以在本节中列出的其他命令中用作 & lt;package > 的值。 

$ yum search <keyword>...
Copy to Clipboard Toggle word wrap

B.3. 安装软件包
复制链接

要安装软件包，请使用 yum install 命令。 

$ sudo yum install <package>...
Copy to Clipboard Toggle word wrap

B.4. 查询软件包信息
复制链接

要列出系统中安装的软件包，请使用 rpm -qa 命令。 

$ rpm -qa
Copy to Clipboard Toggle word wrap

要获取有关特定软件包的信息，请使用 rpm -qi 命令。 

$ rpm -qi <package>
Copy to Clipboard Toggle word wrap

要列出与软件包关联的所有文件，请使用 rpm -ql 命令。 

$ rpm -ql <package>
Copy to Clipboard Toggle word wrap

附录 C. 使用带有示例的 AMQ Broker
复制链接

AMQ Ruby 示例需要一个正在运行的消息代理，其中包含名为 example 的队列。使用以下步骤安装和启动代理并定义队列。

C.1. 安装代理
复制链接

按照 AMQ Broker 入门 中的说明 来安装代理 并创建代理实例。启用匿名访问。

以下流程将代理实例的位置称为 < broker-instance-dir>。

C.2. 启动代理
复制链接

流程

  1. 使用 artemis run 命令启动代理。 

    $ <broker-instance-dir>/bin/artemis run
    Copy to Clipboard Toggle word wrap

  2. 检查控制台输出，以查看启动期间记录的所有关键错误。代理日志服务器 现在在服务器就绪时处于实时 状态。 

    $ example-broker/bin/artemis run
           __  __  ____    ____            _
     /\   |  \/  |/ __ \  |  _ \          | |
    /  \  | \  / | |  | | | |_) |_ __ ___ | | _____ _ __
   / /\ \ | |\/| | |  | | |  _ <| '__/ _ \| |/ / _ \ '__|
  / ____ \| |  | | |__| | | |_) | | | (_) |   <  __/ |
 /_/    \_\_|  |_|\___\_\ |____/|_|  \___/|_|\_\___|_|

 Red Hat AMQ <version>

2020-06-03 12:12:11,807 INFO  [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server
...
2020-06-03 12:12:12,336 INFO  [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live
...
    Copy to Clipboard Toggle word wrap

C.3. 创建队列
复制链接

在新终端中，使用 artemis queue 命令创建名为 example 的队列。 

$ <broker-instance-dir>/bin/artemis queue create --name examples --address examples --auto-create-address --anycast
Copy to Clipboard Toggle word wrap

系统将提示您回答一系列 yes 或没有问题。全部答案为 N。

创建队列后，代理就可以与示例程序一起使用。

C.4. 停止代理
复制链接

运行完示例后，请使用 artemis stop 命令来停止代理。 

$ <broker-instance-dir>/bin/artemis stop
Copy to Clipboard Toggle word wrap

更新于 2023-09-26

法律通告
复制链接

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2026 Red Hat