Saydo REST消息编码
Solace REST 消息功能使用标准的 HTTP 机制对消息进行编码。Solace REST 消息包含以下部分：
- 一个 POST 请求目标，其中编码了 SolacePubSub+ 事件代理目标（参阅 HTTP 请求目标）
- 识别 REST 消息属性的 HTTP 标头（参阅 Solace REST 对 HTTP 标头的使用）
- 作为 HTTP 消息内容传输的消息负载（参阅消息编码注意事项）
HTTP请求目标
Solace 事件代理 REST HTTP 接口支持 HTTP 请求目标的 RFC 7230 §5.3.2 起始形式（即，以 / 开头的路径）或绝对形式（即，<scheme>://<authority>/<path>）。
当 Solace 事件代理充当 HTTP 服务器时，它会从消息生产者那里接收 REST HTTP 请求。Solace 事件代理将收到的 HTTP 请求目标转换为 Solace 消息主题，然后在该主题上路由消息。
相反，当 Solace 事件代理在 REST 交付点（RDP）中充当 HTTP 客户端时，它会在将 HTTP 请求发送到消息消费者之前，从传出的 Solace 消息中构造 HTTP 请求目标。
HTTP 请求目标与 Solace 消息之间的转换取决于相应的消息 VPN 是否配置为 REST HTTP 消息模式或微网关模式。
消息模式
REST HTTP 客户端到 Solace 事件代理 HTTP 服务器
当 Solace 事件代理从 REST HTTP 生产者客户端接收 HTTP POST 请求时，HTTP POST 请求目标的路径必须是以下之一：
/QUEUE/queue-name
Solace 事件代理将 HTTP POST 请求中的消息排队到名为 queue-name 的消息池队列中。
/TOPIC/topic-string
Solace 事件代理将 HTTP POST 请求中的消息发布到主题 topic-string。
如果在请求目标路径的开头省略了 /TOPIC 和 /QUEUE，则假定为 /TOPIC，并将传入的消息视为来自 /TOPIC/<topic-string>。
Solace 事件代理 RDP 到 REST HTTP 消费者服务器
当 Solace 事件代理 RDP 向 REST HTTP 消费者服务器发送 HTTP POST 请求时，它使用为相应队列绑定配置的请求目标。有关详细信息，请参阅配置 POST 请求目标。
微网关模式
REST HTTP 客户端到 Solace 事件代理 HTTP 服务器
当 Solace 事件代理从 REST HTTP 生产者客户端接收 HTTP 请求时，Solace 事件代理使用主题：
method/path
其中：
method 是 HTTP 请求的方法（DELETE、GET、HEAD、OPTIONS、PATCH、POST 或 PUT 之一）
path 是 HTTP 请求目标的路径，删除任何开头的 / 字符。
如果 HTTP 请求目标中有查询，它不会成为 Solace 事件代理用于发布消息的主题的一部分。
必须遵守 Solace 事件代理对结果消息主题的长度和字符的限制。
HTTP 请求目标可以使用百分号编码来 表示对应用程序有意义但在 HTTP 请求目标中非法或具有其他含义的字符（参阅 RFC 3986 §2）。
如果 REST HTTP 客户端在请求目标路径中以百分号编码发送以下字符，它们将出现在 Solace 主题中，保持百分号编码：
! $ % & ' ( ) * + , / : ; = ? @ [ ]
来自 REST HTTP 客户端的 HTTP 请求目标中的任何其他百分号编码字符将在 Solace 消息主题中被解码。
Solace 事件代理 RDP 到 REST HTTP 消费者服务器
当 Solace 事件代理 RDP 向 REST HTTP 消费者服务器发送 HTTP 请求时，它使用消息的元数据来构造 HTTP 请求目标。如果 Solace 事件代理最初是从 REST HTTP 生产者客户端接收的消息，那么这些元数据应该用于重建原始请求目标。
如果消息没有描述传出 HTTP 请求的请求目标的元数据，Solace 事件代理将从消息的主题中重建请求目标路径。顶级主题必须是支持的 HTTP 方法（DELETE、GET、HEAD、OPTIONS、PATCH、POST 或 PUT 之一）。如果不是，则传出消息将被丢弃为无法格式化。第二级及后续主题级别形成请求目标的路径。
当从 Solace 主题重建 HTTP 请求目标路径时，Solace 主题中的以下字符不会在请求目标中进行百分号编码：
! $ & ' ( ) * + , - . / 0…9 : ; = ? @ A…Z [ ] _ a…z ~
如果 RDP 队列绑定（从中取消了消息）未配置为 replace-target authority（参阅在传出 URI 中 替换权威值），并且消息包含指示请求目标权威主机的元数据，则传出的 HTTP 请求目标将为绝对形式。方案将根据连接到 REST HTTP 消费者服务器是否使用 TLS 传输而为 https 或 http。权威（主机和可选端口）将来自消息的元数据。
否则，传出的 HTTP 请求目标将为起始形式，没有任何方案或权威。
在所有情况下，如果消息包含包含请求目标查询的元数据，该查询将被附加到传出的 HTTP 请求目标。
Saydo REST使用HTTP标头
Solace REST 消息传递使用标准的 HTTP 标头，并引入了一些特定于 Solace REST 实现的自定义标头。以下部分详细介绍了使用的 HTTP 标头，并提供了有关其使用的上下文。
- 在消息模式中，未特别提及的任何 HTTP 标头字段将被忽略并丢弃。
- 在微网关模式中，未特别提及的任何收到的 HTTP 标头字段将作为 Solace 消息的元数据附加。作为 HTTP 消息发送的任何 Solace 消息将把 Solace 消息元数据转换回 HTTP 标头字段。
在提及最大字段长度的地方，事件代理会强制执行这些最大值，并丢弃违反它们的任何消息。在适用的情况下，会向 HTTP 发布者返回适当的 HTTP 错误，以指示失败。
Saydo上的HTTP请求的标准HTTP标头
SolacePubSub+ 事件代理在来自 REST HTTP 客户端的 HTTP 请求上使用以下 HTTP 标准标头字段：
| 标头键/值 | 描述 |
|---|---|
| 授权：基本 base64（用户名： | |
| 密码） | 参阅配置客户端认证，了解有关客户端认证的详细信息。 |
| 授权：承载者 | 参阅 OAuth 认证，了解有关 OAuth 客户端认证的详细信息。 |
| 连接：关闭 | 参阅 RFC 7230 §6.1。 |
| 内容编码 | 在消息和微网关模式下，收到的 内容编码 始终作为元数据附加到 Solace 消息中。 |
| 内容长度：数字 | 参阅 RFC 7230 §3.3.2。 |
| 内容类型：字符串 | 该字段指示事件代理在将 REST 发布者的实体正文编码为 Solace 消息时，是否将 REST 消息内容视为文本或二进制。HTTP 内容实体标头和消息负载类型概述了此实体标头的值如何映射到 Solace 消息类型。注意，文本消息内容必须是 UTF-8 编码。有关详细信息，请参阅消息编码注意事项。 |
在消息和微网关模式下，任何收到的 内容类型 始终作为元数据附加到 Solace 消息中。 | |
| 转发：字符串 | |
| X-Forwarded-For：字符串 | 如 RFC 7239 所述，如果在原始 HTTP 客户端和事件代理之间存在中间代理（例如，代理或交换机），则从原始 HTTP 客户端到倒数第二个中间代理的 IP 地址将列在 X-Forwarded-For 标头中。SolacePubSub+ 事件代理在访问控制列表（ACL）、CLI 和管理屏幕中使用此信息，以显示有关原始客户端 IP 的适当额外详细信息。 |
在微网关模式中，如果事件代理收到带有 转发 或 X-Forwarded-For 标头的 HTTP 请求，并且事件代理 RDP 随后将该消息作为 HTTP 请求发送，则事件代理将在发送到事件代理的直接连接 HTTP 客户端的 IP 地址的 转发：for= 标头字段中附加另一个 转发：for= 标头字段。 | |
| Max-Forwards：整数 | 在消息模式中，事件代理忽略此标头。 |
在微网关模式中，如果事件代理收到带有 Max-Forwards 标头的 HTTP 请求，并且 Max-Forwards 值小于或等于零，则 HTTP 请求将被丢弃，并返回 400 Max-Forwards 超出 错误。如果 Max-Forwards 值未超出，并且事件代理随后将该消息作为 HTTP 请求发送，则 HTTP 请求也将有一个 Max-Forwards 标头，其值减 1。 | |
| 转移编码：分块 | SolacePubSub+ 事件代理支持 RFC 7230 中概述的分块传输编码发送的 HTTP POST 请求。Solace 事件代理忽略并丢弃任何尾随标头。 |
| 用户代理：字符串 | 当您在事件代理上发出 show client details CLI 命令时，将显示此标头。 |
Saydo上的HTTP响应的标准HTTP标头
SolacePubSub+ 事件代理始终在对 REST HTTP 客户端的 HTTP 响应中提供以下 HTTP 标准标头字段：
| 标头键/值 | 描述 |
|---|---|
| 缓存控制：无缓存 | 在消息模式中，Solace 事件代理始终发送 缓存控制：无缓存 标头字段。 |
在微网关模式中，任何 缓存控制 标头字段都作为 Solace 消息元数据透明地通过 Solace 事件代理传递。 | |
| 内容编码 | 在消息和微网关模式下，Solace 事件代理发送附加到 Solace 响应消息的任何 内容编码 元 数据。 |
| 内容长度：数字 | 参阅 RFC 7230 §3.3.2。 |
| 内容类型：字符串 | 在消息和微网关模式下，Solace 事件代理发送附加到 Solace 响应消息的任何 内容类型 元数据。 |
在消息模式中，如果 Solace 响应消息没有附加 内容类型 元数据，SolacePubSub+ 事件代理将根据 Solace 消息的消息类型设置此标头。有关详细信息，请参阅 HTTP 内容实体标头和消息负载类型。对于文本消息，值为 text/plain 或 text/xml。对于所有其他消息，值为 application/octet-stream，以表示二进制。 | |
服务器：Solace_<platform>/<version> | 在消息模式中，platform 组件指示 Solace 平台类型（例如，3560）。version 是事件代理运行的 SolacePubSub+ 版本（例如，7.x.x.x）。 |
在微网关模式中，任何 服务器 标头字段都作为 Solace 消息元数据透明地通过 Solace 事件代理传递。 | |
| Set-Cookie：字符串 | 在消息模式中，用于唯一标识 HTTP 发布者客户端的字符串。这使得中间设备（如 HTTP 代理或负载均衡器）可以通过将来自单个 REST 发布者的流量保持在相同的 HTTP 连接上，从而优化未来的流量。 |
在微网关模式中，任何 Set-Cookie 标头字段都作为 Solace 消息元数据透明地通过 Solace 事件代理传递。 | |
| 警告：299 - “字符串” | 根据 RFC 7234，这是可选的。如果存在，表明事件代理已将 Solace 消息转换为 HTTP 响应，但 Solace 消息的某些方面无法在 HTTP 响应中表示并被省略。更多信息可能在 Solace-警告 HTTP 标头中传达。 |
Saydo上的HTTP请求的标准HTTP标头
从 SolacePubSub+ 事件代理到 RDP 消费者 HTTP 服务器的 HTTP 请求中，事件代理提供以下标准 HTTP 标头字段：
| 标头键/值 | 描述 |
|---|---|
| 授权：基本 base64（配置的认证字符串） | 如果事件代理配置为在建立传出连接到 RDP 消费者 HTTP 服务器时使用基本认证，则事件代理在每个 HTTP 请求上提供 授权 标头。如果未为传出连接到 RDP 消费者 HTTP 服务器配置基本认证，则事件代理不提供 授权 标头字段。 |
| 缓存控制：无缓存 | 在消息模式中，Solace 事件代理始终发送 缓存控制：无缓存 标头字段。 在微网关模式中，任何 缓存控制 标头字段都作为 Solace 消息元数据透明地通过 Solace 事件代理传递。 |
| 内容长度：数字 | 参阅 RFC 7230 §3.3.2。 |
| 内容类型：字符串 | 在消息和微网关模式下，Solace 事件代理发送附加到 Solace 消息的任何 内容类型 元数据。 在消息模式中，如果 Solace 消息没有附加 内容类型 元数据，SolacePubSub+ 事件代理将根据事件代理消息的消息类型设置此标头。有关详细信息，请参阅 HTTP 内容实体标头和消息负载类型。对于文本消息，值为 text/plain 或 text/xml。对于所有其他消息，值为 application/octet-stream，以表示二进制。 |
| 主机：host:port | 参阅 RFC 7230 §5.4。 |
| 用户代理：Solace_platform/version | 在微网关模式中，任何 用户代理 标头字段都作为 Solace 消息元数据透明地通过 Solace 事件代理传递。 在消息模式中，platform 组件指示 Solace 平台类型（例如，3560）。version 是事件代理运行的 SolacePubSub+ 版本（例如，7.1.x.x）。 |
| 警告：299 - “字符串” | 根据 RFC 7234，这是可选的。如果存在，此警告表明事件代理已将 Solace 消息转换为 HTTP 请求，但 Solace 消息的某些方面无法在 HTTP 请求中表示并被省略。更多信息可能在 Solace-警告 HTTP 标头中传达。 |
RDP消费者HTTP服务器到Saydo的HTTP响应的标准HTTP标头
SolacePubSub+ 事件代理在来自 RDP 消费者 HTTP 服务器的 HTTP 响应中解释以下标准 HTTP 标头字段：
| 标头键/值 | 描述 |
|---|---|
| 连接：关闭 | 除 关闭 外的任何 连接 标头值都将被忽略。 |
| 内容编码 | 在消息和微网关模式下，Solace 事件代理发送附加到 Solace 消息的任何 内容编码 元数据。 |
| 内容长度：数字 | 参阅 RFC 7230 §3.3.2。 |
| 内容类型：字符串 | 该字段指示事件代理在将实体正文编码为 Solace 消息时，是否将 HTTP 响应消息内容视为文本或二进制。HTTP 内容实体标头和消息负载类型概述了此实体标头的值如何映射到 Solace 消息类型。 |
在消息和微网关模式下，Solace 事件代理还将任何 内容类型 附加到 Solace 消息元数据中。 | |
| 转 移编码：分块 | 事件代理支持 RFC 7230 中概述的分块传输编码发送的 HTTP 响应。事件代理忽略并丢弃任何尾随标头。 |
Saydo特定HTTP标头
所有特定于 Solace 的 HTTP 标头都以 Solace 开头。为了避免混淆，应用程序不应使用 Solace 作为应用程序特定标头的前缀。
在消息和微网关模式下，下面描述的特定于 Solace 的 HTTP 标头不会透明地附加到 Solace 消息的元数据中。相反，当事件代理收到带有这些标头的 HTTP 消息时，Solace 事件代理会根据下面描述的本地操作进行处理。相反，当 Solace 事件代理传输 HTTP 消息时，它可能会附加这些标头，以反映其对消息执行的一些本地处理。
| 标头键/值 | 描述 |
|---|---|
| Solace-客户端名称：Solace 字符串 | |
| （参阅标头值编码 - Solace 字符串） | 指定 HTTP 客户端的事件代理客户端名称。客户端名称必须在 HTTP 连接的 Solace 消息 VPN 中唯一。如果未提供此参数，事件代理将自动生成一个唯一的 Solace 事件代理客户端名称。 |
| 要设置事件代理客户端名称，只需在 HTTP 连接的生命周期内提供一次此标头。如果值保持不变，也可以在每个 HTTP 请求上提供它。 | |
如果 HTTP 客户端发送了 Solace-客户端名称 的新值，则事件代理将使用此新客户端名称创建新的客户端会话。您必须确保此名称在消息 VPN 中唯一，否则事件代理将遵循全局认证设置以替换重复的客户端连接。 | |
Solace-客户 端名称 的最大长度为 160 字节。 | |
Solace-客户端名称 不用于从 Solace 事件代理发送到 RDP 消费者 HTTP 服务器的 HTTP 请求。 | |
| Solace-客户端描述：Solace 字符串（参阅标头值编码 - Solace 字符串） | 指定 HTTP 客户端的事件代理客户端描述。SolacePubSub+ 事件代理客户端描述字段显示在 Solace 事件代理管理屏幕上；它提供了有关客户端的额外详细信息。 |
| 要设置 Solace 事件代理客户端描述，只需在 HTTP 连接的生命周期内最初提供一次此标头。然而，如果值保持不变，也可以为每个 HTTP 请求提供它。 | |
如果 HTTP 客户端发送了 Solace-客户端描述 的新值，则 Solace 事件代理客户端会话将使用此新描述进行更新。 | |
Solace-客户端描述 的最大长度为 254 字节。 | |
Solace-生存时间（毫秒）：<毫秒> | 为从收到的 HTTP 消息创建的 Solace 保证消息指定生存时间值。如果此标头不存在，消息将没有生存时间。 |
Solace-DMQ-资格：[true|false] | 指示从收到的 HTTP 消息创建的 Solace 保证消息是否被标记为有资格进入死信队列（DMQ）。如果此标头不存在，消息将没有资格进入死信队列。 |
| Solace-相关 ID：Solace 字符串（参阅标头值编码 - Solace 字符串） | 指定 Solace 消息相关 ID 字符串。 |
| 有关消息相关的更多信息，请参阅消息相关。 | |
Solace-相关 ID 的最大长度为 2023 字节。 | |
Solace-传递模式：[直接|非持久|持久] | 指定收到的 HTTP 请求的 Solace 传递模式。如果在收到的 HTTP 请求中缺少此标头，则在消息模式中，默认为持久传递模式；在微网关模式中，默认为直接传递模式。 |
| Solace-消息 ID：Solace 字符串 | 指定 Solace 消息 ID 字符串。 |
| 有关更多信息，请参阅消息相关。 | |
Solace-消息 ID 的最大长度为 2023 字节。 | |
Solace-回复到目标：/(QUEUE|TOPIC)/<destination_string> | 指定收到的 HTTP 请求的回复到目标。事件代理将此目标编码到 Solace 消息中，以便 Solace 消息 API（包括 JMS 实现）识别该目标作为回复到目标。 |
使用 Solace-回复到目标 时，此字段的格式必须遵循 REST HTTP 客户端到 Solace 事件代理 HTTP 服务器中概述的约定。但是，在这种情况下，目标类型字符串 /QUEUE/（用于持久队列）和 /TOPIC/ 是强制性的。 | |
当使用 Solace-回复到目标 时，应用程序可以发送请求，并稍后接收这些请求的异步回复。参与消息交换的应用程序负责将请求和异步回复相关联。 | |
Solace-回复到目标 标头字段仅在消息模式中使用。Solace-回复到目标 标头字段与 Solace-回复等待时间（毫秒） 标头字段互斥。 | |
destination_string 的最大长度为 250 字节。 | |
Solace-回复等待时间（毫秒）：<毫秒> | 指示来自 HTTP 客户端的收到的 HTTP 请求是请求-回复消息交换模式的请求，并且 Solace 事件代理必须等待指定的超时值，以获取应用程序回复，Solace 事件代理将该回复编码到发送到 HTTP 客户端的 HTTP 响应中。 |
在微网关模式中，所有收到的 HTTP 请求本质上都是请求-回复消息交换模式的请求，Solace-回复等待时间（毫秒） 用于将超时从默认的 30 秒更改过来。 | |
在消息模式中，Solace-回复等待时间（毫秒） 的存在作为标志，表明 HTTP 请求是请求-回复消息交换模式的请求；如果在消息模式中缺少 Solace-回复等待时间（毫秒），Solace 事件代理将向 HTTP 客户端发送一个 HTTP 响应，其中不包含应用程序级别的回复负载。 | |
除了整数值外，Solace-回复等待时间（毫秒） 标头还可以有一个值 FOREVER，这意味着 Solace 事件代理将永远等待应用程序回复。在失败场景中，必须关闭 HTTP 连接以解除阻塞。 | |
当 Solace 事件代理向 RDP 消费者 HTTP 服务器发送 HTTP 请求时，对于请求-回复消息交换模式的 HTTP 请求，Solace 事件代理将 Solace-回复等待时间（毫秒） 标头值设置为 FOREVER。 | |
Solace-回复到目标 标头字段与 Solace-回复等待时间（毫秒） 标头字段互斥。 | |
Solace-时间戳：<自 1970-01-01 00:00 UTC 以来的毫秒数> | 指定消息最初生成的时间，以自 1970 年 1 月 1 日 00:00 UTC 以来的毫秒数表示的 64 位十进制整数。如果缺少此字段，Solace 消息不会设置时间戳。如果存在，事件代理不会对这个时间戳的值进行任何验证或强制执行。 |
Solace-用户属性-<name>：<value> [; type=<type>] | 此标头允许用户指定通过事件代理端到端传输的属性。这些属性在结果 Solace 消息中作为用户属性进行编码。 |
| 有关如何在 REST 消息中添加自定义标头的详细信息，请参阅 Solace 消息自定义属性。 | |
| Solace-警告：“字符串” | 此字符串伴随标准 警告 标头，并提供有关警告原因的额外信息。它用于故障排除目的。 |
消息相关
在请求-回复消息交换模式中，HTTP 客户端向 Solace 事件代理发送 HTTP 请求。Solace 事件代理将 HTTP 请求转换为 Solace 请求消息，然后根据 HTTP 消息的请求目标将该消息路由到某个服务提供者。服务提供者生成并发送回复消息回 Solace 事件代理。Solace 事件代理将回复消息转换为 HTTP 响应，并将 HTTP 响应发送到 HTTP 客户端。此请求-回复消息交换模式用于微网关模式下的所有 HTTP 消息，以及消息模式下带有 Solace-回复等待时间（毫秒） 标头的 HTTP 请求。
Solace 消息有一对元数据字段，消息 ID 和相关 ID，它们在请求-回复消息交换中用于将回复消息与其相关请求相关联。Solace 消息的消息 ID 可通过 SMF 消息标头 ApplicationMessageID 和 JMS 标头 JMSMessageID 访问；Solace 消息的相关 ID 可通过 SMF 消息标头 ApplicationCorrelationID 和 JMS 标头 JMSCorrelationID 访问。
向 Solace 事件代理发送 HTTP 请求的 HTTP 客户端可以分别使用 Solace-消息 ID 和 Solace-相关 ID HTTP 标头提供自己的消息 ID 和相关 ID。如果 HTTP 客户端向 Solace 事件代理发送请求-回复消息交换模式的 HTTP 请求，并且 HTTP 客户端未提供 Solace-消息 ID 标头，则 Solace 事件代理将为请求消息合成一个唯一的消息 ID。此合成的消息 ID 的形式为 ID:Solace-<unique_val>，其中 <unique_val> 是以十六进制表示的唯一 64 位整数。同样，如果 HTTP 客户端未提供 Solace-相关 ID 标头，Solace 事件代理将为请求消息合成一个唯一的相关 ID。如果 Solace 事件代理同时合成了消息 ID 和相关 ID，则两者使用相同的值。Solace 事件代理将消息 ID 和相关 ID 作为元数据附加到 Solace 请求消息上。Solace 事件代理还附加回复到元数据到 Solace 消息上，允许回复服务提供者将回复消息路由回 HTTP 客户端。
当 Solace 事件代理收到路由到 HTTP 客户端的可能回复消息时，它会验证回复消息的消息 ID 或相关 ID 是否与请求消息匹配。具体来说：
- 回复的消息 ID 必须与请求的消息 ID 匹配，或者
- 回复的相关 ID 必须与请求的消息 ID 匹配，或者
- 回复的相关 ID 必须与请求的相关 ID 匹配。
如果发生上述任何匹配，Solace 事件代理将回复消息作为 HTTP 响应发送到 HTTP 客户端。HTTP 要求每个 HTTP 请求必须有一个 HTTP 响应，因此每个匹配的消息 ID 或相关 ID 只能用于一次请求-回复消息交换模式。如果回复消息没有匹配的消息 ID 或相关 ID，或者如果回复消息的匹配消息 ID 或相关 ID 已被早期回复消息使用，则丢弃回复消息。
当 Solace 事件代理将 Solace 消息作为 HTTP 请求发送到 RDP 消费者 HTTP 服务器时，Solace 事件代理将 Solace 消息的消息 ID 和相关 ID 元数据的 Solace-消息 ID 和 Solace-相关 ID HTTP 标头分别设置为这些值。当 Solace 事件代理从 RDP 消费者 HTTP 服务器收到 HTTP 响应时，它创建一个与 HTTP 响应对应的 Solace 回复消息。Solace 事件代理将 Solace 回复消息的消息 ID 设置为以下值之一，按优先顺序排列：
-
收到的 HTTP 响应的
Solace-消息 ID； -
发送的 HTTP 请求的
Solace-消息 ID； -
无
Solace 事件代理将 Solace 回复消息 的相关 ID 设置为以下值之一，按优先顺序排列：
-
收到的 HTTP 响应的
Solace-相关 ID； -
发送的 HTTP 请求的
Solace-相关 ID； -
发送的 HTTP 请求的
Solace-消息 ID； -
收到的 HTTP 响应的
Solace-消息 ID； -
无
注意，上述内容允许 RDP 消费者 HTTP 服务器在请求-回复消息交换模式中生成回复，而无需 RDP 消费者 HTTP 服务器本身了解 Solace-消息 ID 和 Solace-相关 ID 标头。Solace 事件代理将合成必要的消息 ID 和相关 ID，以便 RDP 消费者 HTTP 服务器的 HTTP 响应可以用作回复消息。
当 Solace 事件代理将 HTTP 响应发送到 HTTP 客户端时，Solace 消息中的任何消息 ID 和相关 ID 元数据将出现在 HTTP 响应的 Solace-消息 ID 和 Solace-相关 ID 标头中。
HTTP标头值编码
以下注释与 HTTP 标头值编码有关。
当 HTTP 标头期望值为 Solace 字符串 时，这表示一个文本字符串，满足以下条件，既支持 ASCII 可见字符，也支持所有其他 UTF-8 字符。
Saydo PubSub+事件代理消息字段默认值
SolacePubSub+ 事件代理将从 HTTP 客户端收到的消息转换为内部 Solace 消息格式，以便可以将它们路由到连接到事件代理的任何客户端。在这样做 的过程中，事件代理为以下 Solace 消息字段分配默认行为，这些字段无法通过 Solace REST 消息传递进行配置。
Solace 消息字段默认值
| Solace 消息字段 | REST 默认值 |
|---|---|
| 可省略资格 | 从 REST 生产者收到的消息没有资格被省略。（SolacePubSub+ 的消息省略功能使客户端能够仅接收它们订阅的主题上发布的最新直接消息。）此字段的值为 false。 |
| 消息 COS | 从 REST 生产者收到的消息具有值为 1 的服务等级（COS）值。对于直接消息，这是最低的服务等级；对于持久和非持久消息，这意味着低优先级。对于持久和非持久消息（即，保证消息），如果目标队列或主题端点启用在过度拥塞时拒绝低优先级消息，则分配的 COS 值决定了每条消息的丢弃资格。 |
| 仅交付一次 | 从 REST 生产者收到的消息没有被标记为仅交付一次（DTO）（即，此字段的值为 false）。 |
| 发送者 ID | 从 REST 生产者收到的消息没有设置发送者 ID 字段，该字段在 Solace 消息中不存在。 |
| JMS 消息优先级 | 从 REST 生产者收到的消息没有设置 JMS 消息优先级字段，该字段在 Solace 消息中不存在。 |
消息编码注意事项
一般来说，消息内容在 POST 正文中以 UTF-8 文本或二进制字节的形式进行编码。以下部分概述了一些需要考虑的方面。
HTTP内容实体标头和消息负载类型
Solace PubSub+ 支持以下消息类型：
- 二进制 — 未结构化的字节
- 文本 — 包含字符串作为消息内容的结构化消息
- 映射 — 包含 Solace 结构化数据的键值对的结构化消息
- 流 — 包含 Solace 结构化数据类型的流（即，一系列没有键的数据字段）
REST API 支持二进制和文本消息类型。
不支持 Map 和 Stream 消息类型的编码。如果特定的消息交换模式导致事件代理将 Solace 消息的不支持类型发送到 REST 消费者，或者将 Solace 响应的不支持类型发送回 REST 生产者，HTTP 正文将从 HTTP 消息中省略。此外，HTTP 消息包含 警告 和 Solace-警告 标头，表明 HTTP 正文已被省略以及原因。
相应地，JMS Map、Stream 和 Object 消息在 REST 消息传递中不受支持。
以下部分概述了 HTTP 内容类型 和 内容编码 标头的详细信息以及这些标头如何影响结果 Solace 消息。
HTTP 内容类型映射到 Solace 消息类型
当 REST 生产者向事件代理发送 HTTP 请求时，或者 REST 消费者向事件代理发送 HTTP 响应时，事件代理使用 HTTP 内容类型、HTTP 字符集 和 HTTP 内容编码 来确定是创建 Solace 文本消息还是二进制消息。
在以下条件下，事件代理创建带有 文本 附件的 Solace 消息：
| HTTP 内容类型为以下之一：| | HTTP 字符集为以下之一：| | HTTP 内容编码为以下之一：|
| --- | --- | --- |
| - text/*
application/jsonapplication/xmlapplication/xml-dtdapplication/javascriptapplication/ecmascriptapplication/*+jsonapplication/*+xml| 并且 | -UTF-8US-ASCII- 参数缺失 | 并且 | -
identity - 标头缺失 |
否则，事件代理创建带有 二进制 附件的 Solace 消息。
HTTP 内容编码 和 HTTP 内容类型 也作为 Solace API 属性包含在 Solace 消息中，以便终端应用程序在处理消息时可以使用这些标头字段值。以下概述了这些标头如何在 Solace 消息中编码的规则：
- 如果 Solace 消息中存在 HTTP
内容编码标头，并且该属性具有字符串值，则将其转换为HTTP_Content_Encoding属性，该属性作为 Solace 消息中的 Solace API 属性携带。此属性的值是 HTTP内容编码值的原文字符串。 - 如果 Solace 消息中存在 HTTP
内容类型标头，并且该属性具有字符串值，则将其转换为HTTP_Content_Type属性，该属性作为 Solace 消息中的 Solace API 属性携带。此属性的值是 HTTP内容类型值的原文字符串。 - HTTP
内容编码和内容类型可能会参数化（例如，内容类型：text/plain; charset=utf-8）；任何此类参数也会被捕获在 Solace 消息中的用户属性值中。 - HTTP
内容编码和内容类型的值长度限制为每个 252 字节，包括参数。
有关如何在其他 Solace API 中设置和访问这些参数的详细信息，请参阅与 PubSub+ 消息传递 API 的交互。
Solace 消息类型映射到 HTTP 内容类型
当 SolacePubSub+ 事件代理将 Solace 消息转换为 HTTP 消息时，无论是将 HTTP POST 请求发送到 REST 消费者，还是在请求/回复消息交换中将 HTTP POST 响应发送到 REST 生产者，事件代理都遵循以下规则来设置适当的 HTTP 内容类型 和 内容编码 标头。
以下步骤概述了如何设置 内容编码 HTTP 标头：
- 如果 Solace 消息中存在
HTTP_Content_Encoding属性，并且此属性具有字符串值，则该字符串值用作 HTTP 消息的内容编码标头值。 - 否则，发送的 HTTP 消息没有 HTTP
内容编码标头。
以下步骤概述了如何设置 内容类型 HTTP 标头：
- 如果 Solace 消息中存在
HTTP_Content_Type属性，并且此属性具有字符串值，则该字符串值用作 HTTP 消息的内容类型标头值。 - 否则，如果 HTTP
内容长度为零（即，没有 HTTP 负载），HTTP 消息没有 HTTP内容类型标头。 - 否则，事件代理根据 Solace 消息的类型自动确定 HTTP
内容类型，如下表所示：
| Solace 消息类型 | HTTP 内容类型 |
|---|---|
| Solace 文本消息 | 如果消息内容在事件代理 SMF 消息的 XML 附件中： |
内容类型：text/xml
否则：内容类型：text/plain| | Solace 二进制消息 |内容类型：application/octet-stream| | Solace 映射消息 | 对于 REST 生产者不支持 | | Solace 流消息 | 对于 REST 生产者不支持 | | 所有返回给 REST 客户端的 HTTP 错误响应 |内容类型：text/xml|
有关如何在其他 Solace API 中设置和访问这些参数的详细信息，请参阅与 PubSub+ 消息传递 API 的交互。
事件代理不会检查 HTTP_Content_Encoding 或 HTTP_Content_Type 值是否会导致有效的 HTTP 标头。消息发布者有责任为这些字段设置适当的值。
HTTP_Content_Encoding或HTTP_Content_Type值的长度没有特定限制。这些字段在 Solace 消息中作为自定义用户属性进行编码，必须符合 REST API 对自定义用户属性的最大值限制。- 包含 XML 附件和二进制附件的 Solace 消息在 REST 中无法表示。这种消息格式是对 Solace SMF 消息格式的异常使用。应用程序应发送内容在二进制附件或 XML 附件中的消息，而不是两者都包含。Solace 事件代理将任何同时包含 XML 附件和二进制附件的 Solace 消息转换为没有正文的 HTTP 消息，并且
警告和Solace-警告HTTP 标头表明问题的具体情况。
在 Solace 之间发送 REST 生产者和 REST 消费者之间的内容类型
鉴于上述规则，这些规则规定了 HTTP 标头 内容类型 和 内容编码 如何编码到 Solace 消息中以及如何从 Solace 消息中解码，可以在 Solace HTTP REST 消息传递中端到端保留这些标头，从 REST 生产者到 REST 消费者。当 HTTP 消息发布到 Solace 时，这些值将作为用户属性编码在结果 Solace 消息格式中。当事件代理将此消息转换回 HTTP 消息时，无论是将 HTTP POST 请求发送到 REST 消费者，还是在请求/回复消息交换中将 HTTP POST 响应发送到 REST 生产者，这些 Solace 消息属性将再次用作 POST 的 HTTP 标头。
Saydo消息自定义属性
以 Solace-用户属性 开头的 HTTP 标头可以用来指定通过事件代理端到端传输的属性。这些属性在结果 Solace 消息中作为用户属性进行编码。
HTTP 标头必须遵循以下格式：
Solace-用户属性-<name>: <value> [; type=<type>]
违反上述规则将导致事件代理拒绝整个 HTTP 消息，并带有适当的错误指示。
Solace 用户属性 <name>
自定义属性名称包含在 HTTP 标头名称中，位于 Solace-用户属性 前缀之后，用 - 分隔，如上述格式所示。
自定义标头名称必须产生有效的 HTTP 标头名称。提供的 <name> 字符串将完全按照在 HTTP 请求消息中找到的方式编码到 Solace 消息中。也就是说，字符大小写得以保留。从 Solace 消息中解码 <name> 时也是如此。自定义用户属性名称将完全按照在 Solace 消息中找到的方式使用。
对于特殊字符，可以使用百分号编码来创建有效的 HTTP 标头名称，事件代理在生成结果 Solace 消息时会解释此百分号编码。
事件代理始终发送百分号编码的标头名称。
不支持设置两个具有相同键名的属性（重复键名），并且行为是未定义的。不要发送具有相同键名的两个 Solace 用户属性的 HTTP 消息。
Solace 用户属性 <type>
类型参数是可选的。默认情况下，REST 消息中的所有 Solace 用户属性都被假定为类型 “string”。以下是有效类型的列表：
string、wchar、bool、int8、int16、int32、int64、uint8、uint16、uint32、uint64、float、double、null
以下是在其他 Solace API 中支持但在 Solace REST 消息传递中不支持的类型：
SmfMessage、Destination、Map、Stream、byte[]
类型值不区分大小写。对于类型 为 null 的情况，值将被忽略。除了上述类型之外的任何 Solace 用户属性类型都将导致整个 HTTP 标头被忽略。
事件代理省略所有类型为字符串的 HTTP Solace 用户属性的类型字段。
值字段
值字段根据类型值进行解释。以下规则概述了限制：
- 类型为
string的值可以包含任何 UTF-8 编码的字符，长度限制为 252 字节。 - 类型为
wchar的值表示任何 Unicode 值。 - 类型为
int8的值是 8 位有符号值。 - 类型为
int16的值是 16 位有符号值。 - 类型为
int32的值是 32 位有符号值。 - 类型为
int64的值是 64 位有符号值。 - 类型为
uint8的值是 8 位无符号值。 - 类型为
uint16的值是 16 位无符号值。 - 类型为
uint32的值是 32 位无符号值。 - 类型为
uint64的值是 64 位无符号值。 - 所有
int*或uint*值可以以十六进制（前缀0x）、八进制（前缀0）或十进制（第一个字符为1到9）的形式指定。 - 类型为
float的值是 32 位浮点数，可以以十进制数（包括可选的小数点或指数）或十六进制数（前缀0x）的形式指定。 - 类型为
double的值是 64 位浮点数，可以以十进制数（包括可选的小数点或指数）或十六进制数（前缀0x）的形式指定。 - 由于精度误差，
float或double值可能在 IEEE 754binary32或binary64值无法 精确表示时，由事件代理在传出的Solace-用户属性HTTP 标头中发送时略有修改。 - 类型为
bool的值规范为true或false，但事件代理也接受数值或字符串。大小写不敏感的标记false、空字符串或任何等于零的数值等同于false；其他任何值等同于true。 - 如果省略了类型为
string的值字段，则值默认为空字符串。 - 如果省略了数值字段，则值默认为 0。
- 事件代理拒绝任何 HTTP 消息，其中数值
Solace-用户属性不符合其指定的类型。
Solace 用户属性字段值必须以以下两种方式之一进行编码：
- 双引号字符串（“quoted-string” 在 RFC7320 附录 B 的 ABNF 中）
- 裸（即，未加引号）的百分号编码字符串
当发送 REST 消息时，事件代理始终使用百分号编码字符串发送 Solace 用户属性标头。
示例
以下是一些自定义用户属性的示例：
Solace-用户属性-UserStringProp1: UserPropVal1
Solace-用户属性-integer-example: 1234; type=int32
Solace-用户属性-currency: %e2%82%ac50.40
Solace-用户属性-spaced: "Inner spaces only"
在 JMS 中，这些属性将如下设置和从消息中检索：
// 设置
TextMessage msg = session.createTextMessage();
msg.setStringProperty("UserStringProp1", "UserPropVal1");
msg.setIntProperty("integer-example", 1234);
msg.setStringProperty("currency", "€50.40");
msg.setStringProperty("spaced", "Inner spaces only");
// 检索
msg.getStringProperty("UserStringProp1");
msg.getIntProperty("integer-example");
msg.getStringProperty("currency");
msg.getStringProperty("spaced");
从 HTTP 到 Solace 消息的转换
当事件代理将收到的 HTTP 消息转换为 Solace SMF 消息时，Solace-用户属性 元组被转换为 Solace 消息的用户属性映射中的条目。转换保留每个 HTTP 用户属性的名称、类型和值。
如果无法将 HTTP 消息成功编码为 Solace 消息，事件代理将丢弃该消息，并向 REST 生产者发送错误通知。
从 Solace 消息到 HTTP 的转换
当从 Solace 消息转换为 REST HTTP 消息时，事件代理将 Solace 消息的用户属性字段转换为 Solace-用户属性 HTTP 标头。
如果无法将 Solace 消息完全编码为 HTTP 消息，无论是因为：
- Solace 消息中有超过 96 个用户属性字段
- Solace 消息中的一些用户属性字段是不支持的类型
那么，有问题的字段将从 HTTP 标头中省略，并且事件代理将在 HTTP 消息中包含 警告 和 Solace-警告 HTTP 标头，以表明问题的性质。
其他HTTP标头字段
在微网关模式下，Solace 事件代理将任何未在本文档中提到的收到的 HTTP 标头字段附加到 Solace 消息的用户属性元数据中。HTTP 标头字段 <header_name>：<header_value> 在用户属性中具有键 JMS_Solace_HTTP_field_<header_name> 和字符串值 <header_value>。对这些 HTTP 标头字段附加到 Solace 消息的用户属性元数据的大小没有特定限制，但此类元数据确实计入整体 Solace 消息大小限制。最多将 128 个 Solace 消息的用户属性元数据，其键为 JMS_Solace_HTTP_field_<header_name>，转换为由 Solace 事件代理发送的 HTTP 消息中的字段名 <header_name>：的 HTTP 标头。
在消息模式下，Solace 事件代理将忽略并丢弃本文档中未提到的任何收到的 HTTP 标头字段。
Saydo消息用户属性元数据
在微网关模式下 HTTP 消息和 Solace 消息之间的转换中，以下 HTTP 信息存储在 Solace 消息用户属性中。与 Solace 事件代理交换消息的 SMF 客户端或 AMQP 客户端可以操作这些用户属性。
| 用户属性键 | 描述 |
|---|---|
JMS_Solace_HTTP_method | 当 Solace 事件代理发送或接收 HTTP 请求时，此用户属性包含 HTTP 请求方法。 |
JMS_Solace_HTTP_target_scheme | 当 Solace 事件代理收到具有绝对形式的请求目标的 HTTP 请求时，此用户属性包含请求目标的方案（http 或 https）。此值对 Solace 消息是否最终通过 Solace 事件代理在明文或 TLS 连接上转发没有影响。 |
JMS_Solace_HTTP_target_host | 当 Solace 事件代理收到具有绝对形式的请求目标的 HTTP 请求时，此用户属性包含请求目标的主机。如果 Solace 事件代理通过禁用了 replace-target-authority 的队列绑定将此消息作为 HTTP 请求发送到 RDP 消费者 HTTP 服务器，则 HTTP 请求目标为绝对形式，此用户属性值作为其主机值，以及 HTTP Host: 标头的值。 |
JMS_Solace_HTTP_target_port | 当 Solace 事件代理收到具有明确指定端口的绝对形式的请求目标的 HTTP 请求时，此用户属性包含请求目标的端口。如果 Solace 事件代理通过禁用了 replace-target-authority 的队列绑定将此消息作为 HTTP 请求发送到 RDP 消费者 HTTP 服务器，则 HTTP 请求目标为绝对形式，此用户属性值作为其端口值，以及 HTTP Host: 标头的端口值。 |
JMS_Solace_HTTP_target_path_query_verbatim | 此用户属性包含请求目标的路径和查询，删除了开头的 /。也就是说，请求目标为 / 将在 |
| User: 继续说 | |
| Kimi: 此用户属性值中表示为空字符串。请求目标和此用户属性之间的任何百分号编码保持不变。如果 Solace 事件代理将此消息作为 HTTP 请求发送到 RDP 消费者，此用户属性提供请求目标的路径和查询。 |
| 用户属性键 | 描述 |
|---|---|
JMS_Solace_HTTP_field_<header_name> | |
JMS_Solace_HTTP_status_code | 当 Solace 事件代理发送或接收 HTTP 响应时，此用户属性包含 HTTP 状态代码。如果此用户属性缺失，状态代码默认为 200。 |
JMS_Solace_HTTP_reason_phrase | 当 Solace 事件代理发送或接收 HTTP 响应时，此用户属性包含 HTTP 原因短语。如果此用户属性缺失，原因短语默认为 OK。 |
JMS_Solace_HTTP_max_forwards | 当 Solace 事件代理收到带有 HTTP Max-Forwards 标头的 HTTP 请求时，消息的 JMS_Solace_HTTP_max_forwards 用户属性包含该 Max-Forwards 标头的值减 1。如果收到的 HTTP 请求中不包含 HTTP Max-Forwards 标头，则省略此用户属性。当 Solace 事件代理将带有此用户属性的消息作为 HTTP 请求发送时，HTTP 请求的 Max-Forwards 标头被设置为此用户属性的值。 |