跳到主要内容

PubSub+ JCSMP API中建立连接所需的会话属性

创建会话时，其设置将被赋予默认值，但可以根据需要进行修改。本节将解释如何修改以下设置。

  • 身份验证方案
  • 客户端名称
  • 主机
  • 本地主机
  • 消息 VPN

要查看完整的会话属性列表、有效参数以及默认值，请参阅 PubSub+ JCSMP 消息传递 API 参考。

有关如何在使用基本身份验证方案（默认方案）时定义所需的会话属性的示例，请参阅 Solace 开发者中心中的 DirectPubSub 示例。尽管其他示例使用了通用代码，但 DirectPubSub 示例明确包含了用于创建会话属性和创建会话的方法。

身份验证方案​

当主机事件代理最初接受客户端的连接时，该连接处于未认证状态，事件代理无法处理来自客户端的任何请求，直到连接被认证。

身份验证方案指定客户端将用于认证其与事件代理连接的凭据。身份验证方案可以是以下之一：

  • 基本身份验证

默认的客户端身份验证方案；它允许客户端使用有效的客户端用户名和密码与事件代理进行身份验证。有关详细信息，请参阅基本身份验证。

  • 客户端证书身份验证

客户端身份验证方案，允许客户端通过 X509v3 客户端证书向事件代理证明其身份。此身份验证方案还要求客户端使用安全连接。有关详细信息，请参阅客户端证书身份验证。

  • Kerberos 身份验证

客户端身份验证方案，使用 Kerberos 通过客户端从批准的票证授予服务（TGS）获得的票证来认证连接的客户端。有关详细信息，请参阅 Kerberos 身份验证。

  • OAuth 身份验证

客户端身份验证方案，允许客户端应用程序使用 OAuth 来认证其与事件代理的连接。您可以使用 OAuth2 或 OIDC 令牌。有关详细信息，请参阅 OAuth 身份验证。

所有这些客户端身份验证方案都需要明确的输入才能成功认证客户端。有关详细信息，请参阅在 PubSub+ JCSMP API 中定义客户端身份验证信息。

客户端名称​

当会话连接到事件代理时，需要一个唯一的客户端名称来在事件代理上注册该特定客户端。如果没有输入客户端名称，API 将自动生成一个唯一的客户端名称。默认情况下，此参数未指定。

客户端名称还用于在会话属性设置为生成发件人 ID 时，在消息的 senderId 字段中唯一标识发件人。

客户端名称属性与可以通过事件代理 CLI 或 SolAdmin 显示的 client 属性相同。

当会话属性设置为生成发件人 ID 时，客户端名称包含在消息的 senderId 字段中，以唯一标识发件人。

要设置客户端名称，请使用 JCSMPProperties.CLIENT_NAME：

properties.setProperty(JCSMPProperties.CLIENT_NAME, myClientName);

主机​

要连接或重新连接会话的主机事件代理。应用程序可以通过以下方式之一直接连接到主机事件代理：

  • 直接连接到主机事件代理
  • 通过代理连接到主机事件代理

直接连接到主机事件代理​

要直接连接到会话的事件代理，请使用由以下部分组成的主机条目：

[协议:]主机[:端口]

其中：

  • 协议 是用于传输通道的协议。有效值为：

    • 对于 JCSMP API，有效值为：
      • tcp: 或 tcp:// — 使用 TCP 通道进行应用程序和事件代理之间的通信。如果未设置协议，则默认使用 TCP。
      • tcps: 或 tcps:// — 使用 TCP 上的 TLS/SSL 通道进行应用程序和事件代理之间的安全通信。
      • ws: 或 ws:// — 使用 WebSockets 传输进行应用程序和事件代理之间的通信。
      • wss: 或 wss:// — 使用 WebSockets 上的 TLS/SSL 通道进行应用程序和事件代理之间的安全通信。

  • 主机 是一个或多个要连接的事件代理的 IP 地址或主机名。

    • 可以在逗号分隔的列表中列出多达 16 个潜在的主机以进行连接或重新连接。列出多个主机允许客户端在第一个事件代理不可用时尝试连接或重新连接到备用主机。按列表中呈现的顺序对主机进行连接或重新连接尝试。列出的主机事件代理可能位于不同的地理位置。
    • 当事件代理以高可用性（HA）冗余对运行时，不要将对中的两个事件代理都列为主机。冗余对使用相同的 IP 地址进行连接，因此它们在消息传递 API 中看起来像是一个事件代理。
    • 客户端的连接和重新连接行为由用于其与事件代理连接的通道或会话属性控制。其重新连接行为还受到客户端应用程序是否发布保证消息的影响。有关详细信息，请参阅每个主机的连接重试。
    • 在 Windows 环境中，应使用完全限定域名（FQDN）作为主机参数，并且它必须与事件代理用于 Kerberos 服务主体名称（SPN）的 FQDN 匹配。

  • 端口 是用于建立连接的端口号。

    • 只有当客户端需要使用自动分配的默认端口号之外的端口时，才需要提供值。TCP 的默认端口号为 55555（未使用压缩时）或 55003（使用压缩时）。TLS/SSL 的默认端口号为 55443，如果您使用 TLS 和压缩，则使用相同的端口。默认端口号为：
      • http/ws 为设备的 80 或软件事件代理的 8008
      • https/wss 为设备的 443 或软件事件代理的 1443

示例：

以下示例展示了如何直接连接到事件代理。除非另有说明，否则使用默认端口 55555。

  • 192.168.160.28 — 通过 TCP 连接到 IP 地址 192.168.160.28。
  • dev212 — 通过 TCP 连接到主机名 dev212。
  • dev212.solacesystems.com — 通过 TCP 连接到主机名 dev212.solacesystems.com。
  • tcp:192.168.160.28 — 通过 TCP 连接到 IP 地址 192.168.160.28。
  • tcps:192.168.160.28 — 使用 TCP 上的 TLS/SSL 连接到 IP 地址 192.168.160.28 和端口 55443。
  • tcp:192.168.160.28:65535 — 通过 TCP 连接到 IP 地址 192.168.160.28 和端口 65535。

当为客户端生成 SPN 时，使用以下格式：service_name/<客户提供的主机>@REALM。服务名称部分通过 KRB 服务名称会话属性配置（默认为 solace），领域部分由 KRB 库的配置文件确定。一个结果服务主体名称的示例是 solace/dev212@SIMPLESPNEXAMPLE.COM。

当使用多个主机时，用于当前连接的主机生成 SPN。

通过代理连接到主机事件代理​

您可以通过 HTTP 或 SOCKS5 代理服务器建立到您私有网络中的事件代理的连接，从而避免需要单独的防火墙例外。代理配置通过系统属性设置，这些属性通常在 java 命令行或 JVM 上设置。需要注意的是，设置在 JVM 实例上的系统属性适用于在相同 JVM 上运行的所有 java 应用程序。

代理服务器配置的属性示例 JVM 命令
代理服务器主机对于所有代理连接，此参数是必需的。它可以是主机名或 IP 地址：

以下代码片段设置了所有代理服务器参数：

java -Dsolace.proxy.type={http} -Dsolace.proxy.host={proxy.example.com} \
			-Dsolace.proxy.port={8080} -Dsolace.proxy.username={my_proxy_username} \
			-Dsolace.proxy.password={my_proxy_password} javaApp

本地主机​

应用程序运行的机器的主机名或 IP 地址。当应用程序运行在多宿主机器上时，可能需要此会话属性。

在多宿主机器上，本地主机名或 IP 地址有助于确保 API 使用正确的网络接口与事件代理进行通信。

要设置本地主机，请使用 JCSMPProperties.LOCAL_HOST：

properties.setProperty(JCSMPProperties.LOCAL_HOST, myHost);

消息VPN​

要连接客户端的主机事件代理上的消息 VPN 的名称。

消息 VPN 在事件代理上创建，以在连接到 Solace PubSub+ 的客户端组之间提供隔离。

如果未提供特定的消息 VPN，则使用名为 default 的消息 VPN。default 消息 VPN 总是存在于事件代理上。尽管网络管理员可以更改 default 的配置设置，但不能将其删除。

要设置消息 VPN，请使用 JCSMPProperties.VPN_NAME：

properties.setProperty(JCSMPProperties.VPN_NAME, myVPN);