建立连接所需的会话属性
当创建会话时，会为其设置分配默认值，但如有需要，可以对其进行修改。本节解释了如何修改以下设置：
- 认证方案
- 客户端名称
- 主机
- 本地主机
- 消 息VPN
有关会话属性的完整列表、有效参数以及默认值，请参阅适用于相应消息API的PubSub+消息API文档。
- 对于Java RTO、C和.NET API：
有关如何在使用基本认证方案时定义所需的会话属性的示例，请参阅DirectPubSub示例。尽管其他消息API示例使用了通用代码，但DirectPubSub示例明确包含了用于创建会话属性和创建会话的方法。
- 对于JavaScript和Node.js API：
请参阅TopicSubscriber和TopicPublisher示例。
认证方案
当主机事件代理最初接受客户端的连接时，该连接处于未认证状态，事件代理无法处理客户端的任何请求，直到连接通过认证。
认证方案指定了客户端用于向事件代理认证其连接的凭据。认证方案可以是以下之一：
- 基本认证
默认的客户端认证方案；它允许客户端使用有效的客户端用户名和密码向事件代理进行认证。更多信息，请参阅基本认证。
- 客户端证书认证
客户端认证方案，允许客户端通过X509v3客户端证书向事件代理证明其身份。此认证方案还要求客户端使用安全连接。更多信息，请参阅客户端证书认证。
- Kerberos认证
客户端认证方案，使用Kerberos通过客户端从批准的票据授予服务（TGS）获取的票据来认证连接的客户端。更多信息，请参阅Kerberos认证。
- OAuth认证
客户端认证方案，允许客户端应用程序使用OAuth认证其与事件代理的连接。可以使用OAuth2或OIDC令牌。更多信息，请参阅OAuth认证。
所有这些客户端认证 方案都需要明确输入，才能成功认证客户端。更多信息，请参阅定义客户端认证信息。
JavaScript和Node.js API不支持所有认证方案。JavaScript API仅支持基本认证和OAuth认证，而Node.js API支持基本认证、客户端证书认证和OAuth认证。
客户端名称
当会话连接到事件代理时，需要一个唯一的客户端名称，以便将该特定客户端注册到事件代理。如果没有输入客户端名称，API将自动生成一个唯一的客户端名称。默认情况下，此参数未指定。
客户端名称还用于在会话属性设置为生成发送者ID时，标识消息中的senderId字段中的发送者。
客户端名称属性与可以通过事件代理CLI或SolAdmin显示的client属性相同。
当会话属性设置为生成发送者ID时，客户端名称将包含在消息的senderId字段中，以唯一标识发送者。
| PubSub+消息API | 使用方法 |
|---|---|
| Java RTO | SessionHandle.PROPERTIES.CLIENT_NAME |
| C | SOLCLIENT_SESSION_PROP_CLIENT_NAME |
| .NET | SessionProperties.ClientName |
| JavaScript和Node.js | solace.SessionProperties.ClientName |
如何设置客户端名称：
主机
会话连接或重新连接到的主机事件代理。应用程序可以通过以下方式之一直接连接到主机事件代理：
- 直接连接到主机事件代理
- 通过代理连接到主机事件代理（Java RTO、C、.NET和JavaScript API ）
直接连接到主机事件代理
要直接将会话连接到事件代理，请使用以下格式的主机条目：
[协议：]主机[:端口]
其中：
-
协议是用于传输通道的协议。有效值如下：-
对于Java RTO、C和.NET API，有效值为：
tcp:或tcp://— 使用TCP通道进行应用程序和事件代理之间的通信。如果未设置协议，则默认使用TCP。tcps:或tcps://— 使用TLS/SSL通道（基于TCP）进行应用程序和事件代理之间的安全通信。ws:或ws://— 使用WebSockets传输进行应用程序和事件代理之间的通信。wss:或wss://— 使用TLS/SSL通道（基于WebSockets）进行应用程序和事件代理之间的安全通信。
-
除了上述值外，对于Java RTO、C和.NET API，以及JavaScript和Node.js API，还支持以下值：
http:或http://— 使用超文本传输协议（HTTP）进行应用程序和事件代理之间的通信。https:或https://— 使用TLS/SSL通道（基于HTTP）进行应用程序和事件代理之间的安全通信。
-
-
主机是一个或多个事件代理的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（对于软件事件代理）。
- 只有当客户端需要使用非自动分配的默认端口号时，才需要指定值。TCP的默认端口号为55555（未使用压缩时）或55003（使用压缩时）。TLS/SSL的默认端口号为55443，如果使用TLS且启用压缩，则使用相同的端口号。
示例：
以下示例展示了如何直接连接到事件代理。除非另有说明，否则默认使用端口55555。
192.168.160.28— 连接到IP地址192.168.160.28，使用TCP。dev212— 连接到 主机名dev212，使用TCP。dev212.solacesystems.com— 连接到主机名dev212.solacesystems.com，使用TCP。tcp:192.168.160.28— 连接到IP地址192.168.160.28，使用TCP。tcps:192.168.160.28— 连接到IP地址192.168.160.28，端口55443，使用TLS/SSL（基于TCP）。tcp:192.168.160.28:65535— 连接到IP地址192.168.160.28，端口65535，使用TCP。
当为客户端生成SPN时，使用以下格式：service_name/<客户提供的主机>@REALM。服务名称部分通过KRB服务名称会话属性配置（默认为solace），而领域部分由KRB库的配置文件确定。一个示例服务主体名称为solace/dev212@SIMPLESPNEXAMPLE.COM。
当使用多个主机时，当前连接所使用的主机将生成SPN。
通过代理连接到主机事件代理（Java RTO、C、.NET和JavaScript API）
要通过HTTP或SOCKS协议版本5代理服务器连接到事件代理，配置的主机设置必须包含标准直接连接到事件代理所需的所有参数，但还必须包括代理服务字符串：
[协议：]主机[:端口][%代理服务]
其中：
代理服务 — 用于连接到事件代理的代理服务器。代理服务字符串的格式指定为：
[代理协议]://[用户名：密码@]代理主机[:代理端口]
其中：
-
代理协议— 用于与代理服务器通信的协议。有效值为：socks5— 使用SOCKS协议版本5（RFC 1928，IETF标准文档）连接到服务器。httpc— 使用HTTP连接协议（RFC 2817，IETF标准文档）连接到服务器。
-
用户名：密码@— 如果代理服务器需要认证，则可以在代理主机之前指定用户名和密码。 -
代理主机— 代理服务器的IP地址（或主机名）。 -
代理端口— 用于连接的端口号。如果未指定端口号，则SOCKS5的默认端口为1080，HTTP连接的默认端口为3128。
示例：
以下示例展示了如何通过代理服务器连接到事件代理。
192.168.160.28%socks5://192.168.1.1— 通过位于192.168.1.1的SOCKS5代理服务器连接到位于192.168.160.28的事件代理。192.168.160.28%httpc://192.168.1.1— 通过位于192.168.1.1的HTTP-Connect代理服务器连接到位于192.168.160.28的事件代理。tcps:solace.company.com%socks5://User:PassWord@proxy.company.com:13128— 使用SSL（基于TCP）连接到位于solace.company.com的事件代理，通过位于proxy.company.com、端口13128的SOCKS5代理服务器。使用用户名User和密码PassWord对代理服务器进行认证。http://192.168.160.28:44444%httpc://proxy.company.com:11050— 使用HTTP连接到位于192.168.160.28、端口44444的事件代理。通过位于proxy.company.com、端口11050的代理服务器进行连接。
| PubSub+消息API | 使用方法 |
|---|---|
| Java RTO | SessionHandle.PROPERTIES.HOST |
| C | SOLCLIENT_SESSION_PROP_HOST |
| .NET | SessionProperties.Host |
| JavaScript和Node.js | solace.SessionProperties.url |
如何设置主机：
本地主机
运行应用程序的机器的主机名或IP地址。当应用程序运行在多宿主机器上时，可能需要此会话属性。
在多宿主机器上，本地主机名或IP地址有助于确保API使用正确的网络接口与事件代理通信。
| PubSub+消息API | 使用方法 |
|---|---|
| Java RTO | SessionHandle.PROPERTIES.BIND_IP |
| C | SOLCLIENT_SESSION_PROP_BIND_IP |
| .NET | SessionProperties.BindIP |
| JavaScript和Node.js | 不适用 |
如何设置本地主机：
消息VPN
主机事件代理上要连接客户端的消息VPN的名称。
消息VPN是在事件代理上创建的，用于隔离连接到Solace PubSub+的客户端组。
如果未指 定特定的消息VPN，则使用名为default的消息VPN。default消息VPN始终存在于事件代理上。虽然网络管理员可以更改default的配置设置，但不能将其删除。
| PubSub+消息API | 使用方法 |
|---|---|
| Java RTO | SessionHandle.PROPERTIES.VPN_NAME |
| C | SOLCLIENT_SESSION_PROP_VPN_NAME |
| .NET | SessionProperties.VPNName |
| JavaScript和Node.js | solace.SessionProperties.vpnName |
如何设置消息VPN：
Java RTO、C或.NET API的Web传输协议
使用Java RTO、C或.NET API的客户端应用程序可以为会话使用Web传输。Web传输不适用于JMS API。
C会话属性SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL指定了会话连接中要使用的Web传输协议。有关更多信息，请参阅Web传输协议。
如果尝试使用给定传输协议建立会话连接失败，API将自动尝试使用效率较低的传输协议。例如，如果选择了HTTP_BINARY_STREAMING，但无法建立连接，则将尝试HTTP_BINARY。可以使用SOLCLIENT_SESSION_PROP_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS属性指定传输协议连接尝试之间的时间（以毫秒为单位）。默认情况下，API使用最佳可用Web传输协议。
Solace建议将SESSION_TRANSPORT_PROTOCOL_DOWNGRADE_TIMEOUT_MS保持在其默认值3000，并将SESSION_RECONNECT_RETRY_WAIT_MS设置为10000。这些设置允许客户端在重新连接尝试发生之前，依次尝试每种协议类型。
客户端也可以使用SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST属性指定一个逗号分隔的传输协议列表。如果连接尝试失败且指定了列表，则API将自动尝试使用列表中的下一个协议进行连接。
要禁用传输协议的自动协商，客户端可以为SOLCLIENT_SESSION_PROP_WEB_TRANSPORT_PROTOCOL_LIST指定一个单一协议。
JavaScript和Node.js API的Web传输协议
对于JavaScript API，solace.sessionProperties.webTransportProtocolList属性定义了要使用的可能的Web传输协议。有关Web传输协议的更多信息，请参阅Web传输协议。
如果启用保证消息支持，则必须使用WS_BINARY协议。如果启用了任何其他协议支持，则会自动禁用保证消息。
Node.js API仅支持WS_BINARY Web传输协议。
版本7 API行为配置文件的JavaScript API默认支持所有传输协议。此外，行为配置文件还允许API在初始尝试失败后，自动尝试使用效率较低的传输协议进行连接。例如，如果选择了WS_BINARY，但无法建立连接，则将尝试HTTP_BINARY_STREAMING。下表显示了每个Web API支持的传输协议。有关JavaScript和Node.js API行为配置文件的更多信息，请参阅初始化和监控API。
通过WebSockets进行保证消息传递
Java RTO、C和.NET API允许用户通过WebSockets进行保证消息传递。
| PubSub+消息API | 最低API版本 | 属性名称 |
|---|---|---|
| Java RTO | 7.14.0.8或更新版本 | SessionHandle.PROPERTIES.GUARANTEED_WITH_WEB_TRANSPORT |
| C | 7.14.0.8或更新版本 | SOLCLIENT_SESSION_PROP_GUARANTEED_WITH_WEB_TRANSPORT |
| .NET | 10.9.0或更新版本 | SessionProperties.GdWithWebTransport |
要使用此新功能，必须设置相应的会话属性。