向外部端点发送HTTP请求，支持可配置的请求方法、请求头、认证和代理设置。支持GET、POST、PUT、PATCH和DELETE操作，及包括TLS/SSL加密在内的多种认证方式。
配置
端点URL模式
指定请求将发送到的端点URL。支持模板。
请求方法
请求使用的HTTP方法。可用选项：GET、POST、PUT、PATCH、DELETE。
请求头
要包含在请求中的HTTP头键值对。键和值均支持模板。
消息设置
解析为纯文本
控制在发送前如何处理消息data：
- Disabled（默认）— 消息data原样发送
- Enabled — 若消息data为JSON编码的字符串（用双引号包裹），则移除外层JSON编码
示例：
消息data："\"Temperature is 25.5°C\""
- Parse to plain text OFF：发送
"\"Temperature is 25.5°C\""（带JSON编码） - Parse to plain text ON：发送
"Temperature is 25.5°C"（无外层引号）
注意：此设置仅影响JSON编码的字符串（用双引号包裹的字符串）。普通JSON对象如 {"temperature":25.5} 无论如何设置均原样发送。
不包含请求体
- Disabled（默认）— POST、PUT、PATCH、DELETE的请求体包含消息data
- Enabled — 不发送请求体，即使对于通常包含请求体的方法
注意：启用请求体时，若消息metadata包含blob实体ID的 attachments 字段，将使用第一个blob实体的内容作为请求体，而非消息data。
连接设置
读取超时（毫秒）
等待服务器响应的最大时间（毫秒）。
- 0（默认）— 无限超时（永久等待）
- > 0 — 在指定毫秒后超时
最大并行请求数
限制节点可发送的并发请求数。
- 0（默认）— 并行处理无限制
- > 0 — 可同时进行中的最大请求数
达到限制时，新消息需等待有请求完成。若等待时间超过读取超时，消息将因超时错误失败。
最大响应大小（KB）
可在内存中缓冲的HTTP响应体最大大小。超过此限制的响应将失败并报错。默认：256 KB
系统通过 tb.http.maxInMemoryBufferSizeInKb 系统属性（默认：25000 KB）强制执行最大限制。若配置值超过该限制，节点将无法初始化。
代理设置
启用代理
- Disabled（默认）— 直接连接端点
- Enabled — 通过代理服务器路由请求
启用后，可选择手动配置代理或使用系统代理属性。
Use system proxy properties
当Enable proxy已启用时，此选项决定代理配置来源：
- Disabled（默认）— 在下方手动配置代理
- Enabled — 使用系统代理属性
系统属性（至少需配置一组）：
HTTP代理：
http.proxyHost— HTTP代理主机名http.proxyPort— HTTP代理端口
HTTPS代理：
https.proxyHost— HTTPS代理主机名https.proxyPort— HTTPS代理端口
SOCKS代理：
socksProxyHost— SOCKS代理主机名socksProxyPort— SOCKS代理端口socksProxyVersion— SOCKS版本（4或5，默认5）
认证属性（用于所有代理类型）：
tb.proxy.user— 代理用户名tb.proxy.password— 代理密码
注意：若启用系统代理属性但未配置，节点将无法初始化。
Manual proxy configuration
当Use system proxy properties为禁用时，手动配置代理：
- Proxy host — 代理服务器的主机名或IP地址
- Proxy port — 代理服务器的端口号（1-65535）
- Proxy user — 代理认证用户名
- Proxy password — 代理认证密码
Credentials
连接端点的认证凭据。可用凭据类型：
Anonymous
不提供认证。当端点允许匿名访问或通过请求头处理认证时使用。
Basic
使用用户名和密码的HTTP Basic认证。
配置：
- Username — 认证用户名
- Password — 认证密码
凭据会自动编码并以 Basic <base64-encoded-credentials> 格式在 Authorization 头中发送。
PEM Certificate
使用PEM编码文件的基于证书认证。提供双向TLS认证。
配置：
- Server CA certificate file — 签署服务器证书的证书颁发机构（CA）证书。用于验证服务器身份。
- Client certificate file — 客户端的公钥证书。发送给服务器用于客户端认证。
- Client private key file — 与客户端证书对应的客户端私钥。
- Private key password — 私钥文件加密时的密码。
注意：使用PEM凭据时，需提供Server CA证书文件，或同时提供Client证书与Client私钥文件。
注意：证书和密钥文件可直接上传，或从Secrets storage引用以增强安全性。
Advanced settings
Force acknowledgement
强制确认机制由 ACTORS_RULE_EXTERNAL_NODE_FORCE_ACK 环境变量控制。当该变量设为 true 时，适用于包括本REST API调用节点在内的所有外部节点。
启用强制确认时的行为：
- 入站消息立即被确认
- 执行HTTP请求
- 请求完成后，响应放入新消息
- 新消息加入队列供下一节点处理
- 可避免慢速端点导致的消息处理超时
禁用强制确认时（默认）：
- 原始入站消息在HTTP请求完成前保持占用
- 原始消息用响应数据转换
- 转换后的消息传递至下一节点
JSON Schema
规则节点初始化
规则节点初始化时，会创建具有已配置设置的HTTP客户端。客户端使用连接池，最大连接数可通过 TB_RE_HTTP_CLIENT_POOL_MAX_CONNECTIONS 环境变量配置（默认由Reactor Netty库决定）。
初始化完成后，客户端即可处理消息。
消息处理
对每条入站消息，节点执行以下步骤：
- 若Force acknowledgement已启用，入站消息立即被确认。
- 若配置了Max number of parallel requests，节点等待可用槽位。若在读取超时时间内无可用槽位，消息将因超时错误失败。
- 节点处理Endpoint URL pattern，用入站消息data和metadata中的值替换模板以构建最终URL。
- 准备HTTP头：
- 添加已配置的头并经模板处理
- 对于Basic凭据，添加带base64编码凭据的
Authorization头
- 准备请求体：
- 若Without request body已启用，不发送请求体
- 否则，对于POST、PUT、PATCH、DELETE方法：
- 若消息metadata包含blob实体ID的
attachments字段，使用第一个blob实体的内容作为请求体 - 否则使用消息data作为请求体
- 若Parse to plain text已启用，解除JSON编码字符串的外层包装
- 若消息metadata包含blob实体ID的
- 将HTTP请求发送至端点。
- 收到响应后：
- 成功（2xx状态码）：将响应信息添加到消息，并经
Success连接转发 - 失败（非2xx状态码或异常）：将错误信息添加到消息，并经
Failure连接转发 - 响应/错误信息的结构详见“Outgoing message format”部分
- 成功（2xx状态码）：将响应信息添加到消息，并经
- 若配置了Max number of parallel requests，释放请求槽位供下一条消息使用。
出站消息格式
成功（2xx响应）：
消息metadata中添加以下键：
status— HTTP状态名称（如 “OK”、”CREATED”）statusCode— HTTP状态码（如 “200”、”201”）statusReason— HTTP状态原因短语- 响应头 — 每个响应头作为metadata键值对添加
- 单值头：作为字符串值添加
- 多值头：作为JSON数组字符串添加
消息data替换为响应体。若无响应体，data设为 {}。
失败（非2xx响应或异常）：
消息metadata中添加以下键：
error— 格式为ExceptionClass: error message的错误描述status— HTTP状态名称（若有）statusCode— HTTP状态码（若有）statusReason— HTTP状态原因短语（若有）error_body— 失败请求的响应体（若有）- 响应头（若有）
消息data保持与原始消息相同。
强制确认行为：
当Force acknowledgement禁用时，原始入站消息用上述响应信息转换。
当Force acknowledgement启用时，创建包含上述响应信息的新消息。
输出连接
- Success
- HTTP请求成功完成且状态码为2xx
- Failure
- HTTP请求返回非2xx状态码
- 因网络问题、超时或连接错误导致请求失败
- 处理过程中发生意外错误
- 等待可用请求槽位时超时
示例
示例1
智能设备需向外部设备管理系统发送控制命令并接收执行结果。端点需要Basic认证，期望请求体为JSON命令。强制确认已禁用。
入站消息
Originator: DEVICE（Smart Lock）
Data:
1
2
3
4
5
{
"command": "unlock",
"duration": 30,
"reason": "owner_request"
}
Metadata:
1
2
3
4
{
"deviceId": "lock-bedroom-01",
"deviceType": "smartLock"
}
节点配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"restEndpointUrlPattern": "https://api.smart-home.com/v1/devices/${deviceId}/commands",
"requestMethod": "POST",
"headers": {
"Content-Type": "application/json"
},
"readTimeoutMs": 5000,
"maxParallelRequestsCount": 10,
"parseToPlainText": false,
"enableProxy": false,
"credentials": {
"type": "basic",
"username": "api-client",
"password": "secure-password"
},
"ignoreRequestBody": false,
"maxInMemoryBufferSizeInKb": 256
}
出站消息（假设成功响应，状态码200）
Data:
1
2
3
4
5
6
7
8
9
10
{
"commandId": "cmd-98765",
"status": "executed",
"executedAt": "2023-01-01T10:30:00Z",
"result": {
"success": true,
"lockState": "unlocked",
"autoLockIn": 30
}
}
Metadata:
1
2
3
4
5
6
7
8
9
{
"deviceId": "lock-bedroom-01",
"deviceType": "smartLock",
"status": "OK",
"statusCode": "200",
"statusReason": "OK",
"Content-Type": "application/json",
"X-Request-Id": "req-789xyz"
}
结果
节点构建端点URL为 https://api.smart-home.com/v1/devices/lock-bedroom-01/commands，准备以下请求头：
Content-Type: application/jsonAuthorization: Basic YXBpLWNsaWVudDpzZWN1cmUtcGFzc3dvcmQ=
请求体包含命令：{"command":"unlock","duration":30,"reason":"owner_request"}，发送POST请求。
命令已成功发送至外部端点。响应确认命令执行并返回当前锁状态。消息经 Success 连接路由，执行结果可供下游节点进一步处理。