4、HTTP节点概述：REST API调用节点（REST API Call）功能、适用场景、与其他节点的区别
REST API Call 节点是 ThingsBoard 规则链中用于发起外部 HTTP 请求的核心节点。它允许规则链在消息处理过程中，将设备数据、告警信息或业务上下文通过 RESTful 接口发送到第三方系统，或从外部服务获取数据后继续流转。该节点是打通 IoT 平台与外部业务系统的关键桥梁。
4.1 核心功能
REST API Call 节点封装了完整的 HTTP 客户端能力，支持以下关键特性：
| 功能维度 | 说明 |
|---|---|
| 请求方法 | 支持 GET、POST、PUT、DELETE、PATCH 五种标准 HTTP 方法 |
| 动态 URL | URL 支持使用 ${metadataKey} 或 ${msg.field} 模板语法动态拼接 |
| 请求头定制 | 可添加自定义 Header，如 Authorization、Content-Type、X-Request-ID |
| 请求体构造 | 支持 JSON、纯文本、表单格式；可使用消息体或元数据动态填充 |
| 响应处理 | 将 HTTP 响应状态码、响应体、响应头写入元数据或消息体，供下游节点使用 |
| 超时与重试 | 可配置请求超时时间（默认 10s），失败后支持重试策略 |
| 安全认证 | 支持 Basic Auth、Bearer Token、自定义 Header 认证方式 |
关键设计原则：REST API Call 节点是同步阻塞调用。规则链会等待外部 HTTP 响应返回后，再继续执行后续节点。对于不需要等待响应的场景，建议使用“发送到外部系统”节点或异步队列方式。
4.2 适用场景
REST API Call 节点在 IoT 集成中承担着数据上行与指令下行的双重角色，典型场景包括：
- 设备数据推送：将传感器数据实时推送到企业 ERP、MES 或大数据平台
- 告警通知：触发告警时调用第三方短信、邮件或即时通讯 API（如钉钉、Slack）
- 状态同步：设备上线/离线时同步状态到资产管理系统
- 外部数据查询：在规则链中调用外部天气、地理编码或设备档案 API 获取补充信息
- 命令下发：接收用户指令后，通过 REST 接口转发到边缘网关或执行器
- 鉴权与令牌刷新：在规则链中动态获取 OAuth2 令牌并缓存到元数据
4.3 与其他节点的区别
ThingsBoard 规则链中涉及外部通信的节点还有“发送邮件”、“发送 SMS”、“MQTT 发布”等。REST API Call 节点在通用性和灵活性上具有明显差异：
| 对比维度 | REST API Call 节点 | 发送邮件 / SMS 节点 | MQTT 发布节点 |
|---|---|---|---|
| 通信协议 | HTTP/HTTPS | SMTP / 运营商协议 | MQTT |
| 数据格式 | JSON、文本、表单（灵活） | 固定模板（邮件正文、短信内容） | 二进制 / JSON（灵活） |
| 响应处理 | 支持读取响应体、状态码、Header | 仅返回成功/失败状态 | 无响应（发布即忘） |
| 动态 URL | 支持模板语法动态拼接 | 不支持 | 支持动态 Topic |
| 认证方式 | Basic、Bearer、自定义 Header | 账号密码（固定） | 用户名密码 / 证书 |
| 适用场景 | 通用 REST API 集成 | 特定通知渠道 | IoT 设备双向通信 |
选型建议：当需要与第三方 Web 服务、微服务、云 API 集成时，优先选择 REST API Call 节点。如果仅需发送邮件或短信，使用专用节点配置更简单。MQTT 发布节点更适合设备端到端的实时通信场景。
4.4 节点内部处理流程
REST API Call 节点在规则链中的执行逻辑可分为五个阶段，理解这一流程有助于排查调用失败问题：
- 消息入站：上游节点将消息（含消息体、元数据）传递到 REST API Call 节点
- 模板解析：节点解析 URL、Header、Body 中的模板变量，替换为实际值
- HTTP 请求发送：根据配置的方法、超时、认证信息发起 HTTP 调用
- 响应接收：等待外部服务返回响应，记录状态码、响应体、响应时间
- 结果路由：根据 HTTP 状态码或自定义条件，将消息路由到 Success / Failure 链
4.5 节点配置参数速查
在 ThingsBoard UI 中配置 REST API Call 节点时，以下参数需要重点关注：
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 请求方法 | 枚举 | 是 | GET / POST / PUT / DELETE / PATCH |
| 端点 URL | 字符串 | 是 | 支持模板变量，如 https://api.example.com/v1/devices/${deviceId} |
| 请求头 | 键值对 | 否 | 可添加多个自定义 Header，支持模板 |
| 请求体 | 文本 | 否 | POST/PUT 时使用，支持 JSON 模板 |
| 超时 (ms) | 整数 | 否 | 默认 10000ms，超过则触发 Failure |
| 重试次数 | 整数 | 否 | 0-5 次，仅在 Failure 时重试 |
| 认证类型 | 枚举 | 否 | None / Basic / Bearer Token |
| 响应处理 | 开关 | 否 | 是否将响应体写入消息体或元数据 |
常见陷阱：
- URL 模板变量未定义时，节点会直接失败，不会发送请求
- 响应体过大（超过 1MB）可能导致规则链内存溢出，建议在外部服务端做分页或截断
- Bearer Token 过期后不会自动刷新，需配合“生成令牌”节点或自定义逻辑处理
- 同步调用会阻塞规则链线程，高并发场景建议使用异步节点或增加规则链并行分支