rest call reply

将传入消息数据作为对Rule Engine的REST API调用的回复发送。回复根据元数据属性路由回发起服务和请求。 消息路由至 Success 连接（成功时）或 Failure 连接（错误时）。

用法

向Rule Engine发起REST API调用

要通过REST API向Rule Engine提交消息，使用以下POST端点之一：

• POST /api/rule-engine/ — 将消息推送到Rule Engine。
• POST /api/rule-engine/{entityType}/{entityId} — 将消息推送到特定实体（如设备、资产）。
• POST /api/rule-engine/{entityType}/{entityId}/{timeout} — 使用自定义超时值（毫秒）推送实体消息。
• POST /api/rule-engine/{entityType}/{entityId}/{queueName}/{timeout} — 将实体消息推送到特定队列并指定自定义超时值。

请求体应以JSON格式包含消息payload。 当端点中未指定实体时，消息发起者为发起请求的用户。 当指定实体时，消息发起者为该实体。 平台会自动将服务ID和请求ID添加到消息元数据，用于将回复路由回调用客户端。

流程

处理Rule Engine REST API调用并发送回复的典型流程如下：

1. 当外部系统或用户发送REST API调用向ThingsBoard Rule Engine提交消息时，会自动创建类型为 REST_API_REQUEST 的Rule Engine消息。 消息数据包含API调用的payload，元数据包含将回复作为HTTP响应路由回所需的服务ID和请求ID。

2. 在Rule Chain中处理该消息以准备响应。可能涉及用附加数据丰富消息、转换payload、调用外部系统或生成适当回复所需的任何其他业务逻辑。

3. 一旦消息数据中准备好响应，将消息路由至“rest call reply”节点。节点将使用元数据将回复发送回发起服务，作为对初始REST API调用的HTTP响应返回。

4. 重要：确保在消息处理过程中保留 serviceId 和 requestId 元数据属性。若这些值丢失或被覆盖，回复无法路由回，API调用将超时。

超时处理：若REST API调用在收到回复前超时，平台将返回 408 REQUEST TIMEOUT。 若Rule Chain中较早节点发生故障并阻止消息到达回复节点，即使存在“rest call reply”节点也可能发生此情况。 从浏览器发起此类超时请求时，浏览器可能会静默重试调用，导致同一请求的多次Rule Engine执行。 为避免此问题，请确保Rule Chain适当处理错误，且回复在超时前返回。 在原始REST API调用上设置足够的超时值，以允许完整处理。

配置

配置参数指定用于识别服务和请求的元数据键名，以便发送回复。

• Service Id - 服务标识符的元数据键名。默认值为 serviceId。标识应接收回复的发起服务。
• Request Id - 请求标识符的元数据键名。默认值为 requestUUID。标识要回复的具体REST API请求。

这些参数可为高级用例自定义，但默认值在大多数场景下工作良好，通常无需更改。REST API消息的元数据中已包含路由参数（服务ID和请求ID）。

JSON Schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TbSendRestApiCallReplyNodeConfiguration",
  "type": "object",
  "properties": {
    "serviceIdMetaDataAttribute": {
      "type": "string",
      "description": "Metadata key name for the service identifier."
    },
    "requestIdMetaDataAttribute": {
      "type": "string",
      "description": "Metadata key name for the request identifier."
    }
  },
  "required": [
    "serviceIdMetaDataAttribute",
    "requestIdMetaDataAttribute"
  ],
  "additionalProperties": false
}

消息处理算法

1. 节点使用配置的键名从消息元数据中提取服务ID和请求ID。若请求ID缺失，处理失败。
2. 节点验证元数据中存在服务ID。若缺失，处理失败。
3. 节点验证消息数据（回复体）非空。若为空，处理失败。
4. 节点将回复作为HTTP响应发送回发起的REST API调用。
5. 成功完成处理后，消息经 Success 连接转发。

输出连接

• Success
  • REST API回复已成功发送。传出消息与传入消息相同。
• Failure
  • 处理过程中发生错误，例如：
    • 元数据中缺少请求ID
    • 元数据中缺少服务ID
    • 消息数据（回复体）为空
    • 无法将请求ID解析为UUID

示例

示例1 — 简单REST API回复

传入消息

发起者：DEVICE。

数据：

1
2
3
4
5
6
{
  "status": "completed",
  "fileName": "sensor_data_2024_10_02.csv",
  "fileSize": 15360,
  "recordsProcessed": 1250
}

元数据：

1
2
3
4
{
  "serviceId": "monolith",
  "requestUUID": "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
}

节点配置

1
2
3
4
{
  "serviceIdMetaDataAttribute": "serviceId",
  "requestIdMetaDataAttribute": "requestUUID"
}

传出消息

传出消息与传入消息相同。经 Success 连接路由。

结果

用户向Rule Engine发起REST API调用以触发电外部FTP服务器下载数据文件。 Rule Chain通过连接FTP服务器、下载文件、处理记录并准备包含操作结果的响应来处理该请求。 “rest api reply”节点将此数据作为HTTP响应体发送回对服务 monolith、请求ID a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6 的原始REST API调用。