Request连接器配置

连接器配置：request.json
下一步

本指南将帮助您熟悉ThingsBoard IoT Gateway的Request连接器配置。
请使用通用配置指南启用此连接器。
该连接器的用途是连接外部HTTP(S) API端点并从中获取数据。
连接器还能根据ThingsBoard的更新或命令将数据推送到外部HTTP(S) API。

当您的设备有HTTP(S) API端点或外部资源中有数据并希望推送至ThingsBoard时，此连接器非常有用。

下面将说明连接器配置文件。

连接器配置：request.json

连接器配置为JSON文件，包含如何连接外部API端点、读取数据时使用的URL以及如何处理数据的说明。下面通过示例说明配置文件格式。

Request 连接器配置文件示例。

下列示例将连接到本地5000端口上的服务器。连接器将使用用户名和密码进行基本HTTP认证，然后根据mapping部分的URL从端点列表读取数据。更多说明见下文。

{
  "host": "http://127.0.0.1:5000",
  "SSLVerify": true,
  "security": {
    "type": "basic",
    "username": "user",
    "password": "password"
  },
  "mapping": [
    {
      "url": "getdata",
      "httpMethod": "GET",
      "httpHeaders": {
        "ACCEPT": "application/json"
      },
      "allowRedirects": true,
      "timeout": 0.5,
      "scanPeriod": 5,
      "converter": {
        "type": "json",
        "deviceNameJsonExpression": "SD8500",
        "deviceTypeJsonExpression": "SD",
        "attributes": [
          {
            "key": "serialNumber",
            "type": "string",
            "value": "${serial}"
          }
        ],
        "telemetry": [
          {
            "key": "Maintainer",
            "type": "string",
            "value": "${Developer}"
          },
          {
            "key": "Pressure",
            "type": "integer",
            "value": "${press}"
          }
        ]
      }
    },
    {
      "url": "get_info",
      "httpMethod": "GET",
      "httpHeaders": {
        "ACCEPT": "application/json"
      },
      "allowRedirects": true,
      "timeout": 0.5,
      "scanPeriod": 100,
      "converter": {
        "type": "custom",
        "deviceNameJsonExpression": "SD8500",
        "deviceTypeJsonExpression": "SD",
        "extension": "CustomRequestUplinkConverter",
        "extension-config": [
          {
            "key": "Totaliser",
            "type": "float",
            "fromByte": 0,
            "toByte": 4,
            "byteorder": "big",
            "signed": true,
            "multiplier": 1
          },
          {
            "key": "Flow",
            "type": "int",
            "fromByte": 4,
            "toByte": 6,
            "byteorder": "big",
            "signed": true,
            "multiplier": 0.01
          }
        ]
      }
    }
  ],
  "attributeUpdates": [
      {
        "httpMethod": "POST",
        "httpHeaders": {
          "CONTENT-TYPE": "application/json"
        },
        "timeout": 0.5,
        "tries": 3,
        "allowRedirects": true,
        "deviceNameFilter": "SD.*",
        "attributeFilter": "send_data",
        "requestUrlExpression": "sensor/${deviceName}/${attributeKey}",
        "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
      }
  ],
  "serverSideRpc": [
    {
      "deviceNameFilter": ".*",
      "methodFilter": "echo",
      "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
      "responseTimeout": 1,
      "httpMethod": "GET",
      "valueExpression": "${params}",
      "timeout": 0.5,
      "tries": 3,
      "httpHeaders": {
        "Content-Type": "application/json"
      }
    },
    {
      "deviceNameFilter": ".*",
      "methodFilter": "no-reply",
      "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
      "httpMethod": "POST",
      "valueExpression": "${params}",
      "httpHeaders": {
        "Content-Type": "application/json"
      }
    }
  ]
}

通用部分

参数	默认值	说明
host	http://127.0.0.1:5000	服务器的域名或IP地址。
SSLVerify	true	若可用，是否验证服务器上的SSL证书。

安全部分

本部分提供在外部服务器上进行客户端认证的配置。

Basic推荐

Anonymous无安全认证

Basic 认证是一种安全配置方式。 Request Connector 发送带有 Authorization 头的 HTTP 请求，该头包含 “Basic” 后跟空格及 base64 编码的 username:password 字符串。

参数	默认值	说明
type	basic	授权类型。
username	username	授权用户名。
password	password	授权密码。

配置文件中的 security 部分将如下所示：

    "security": {
      "type": "basic",
      "username": "username",
      "password": "password"
    }

匿名认证是最简单的选项，适合用于测试。

参数	默认值	说明
type	anonymous	授权类型。

配置文件中的 security 配置小节将如下所示：

    "security": {
      "type": "anonymous"
    }

映射部分

本配置部分包含网关连接服务器后尝试读取的端点对象数组，也包含处理传入消息（converter）的设置。请求后，将分析该URL的每个响应以提取设备名称、类型和数据（属性和/或时序值）。默认使用Json转换器，也可提供自定义转换器。参见源码中的示例。

注意：可在数组内指定多个映射对象。

参数	默认值	说明
url	getdata	发送请求的URL地址。
httpMethod	GET	请求的HTTP方法（GET、POST等）。
httpHeaders	{ “ACCEPT”: “application/json” }	包含请求的额外HTTP头的对象。
allowRedirects	true	是否允许请求重定向。
timeout	0.5	请求超时时间。
scanPeriod	5	重新扫描间隔。

转换器子节

本子节包含处理传入消息的配置。

请求转换器类型：

json -默认转换器
custom -自定义转换器（可自行编写，用于转换响应中的传入数据）

json推荐用于响应中接收JSON数据

custom推荐用于响应中接收字节或其他格式数据

Json converter 是默认 converter，根据本小节所述规则，在来自 broker 的消息中查找 deviceName、deviceType、attribute 和 telemetry：

参数	默认值	说明
type	json	指示 connector 使用默认 converter 转换响应数据。
deviceNameJsonExpression	SD8500	用于在消息中查找设备名称的简单 JSON 表达式（字符串 “SD8500” 将作为设备名称使用）。
deviceTypeJsonExpression	SD	用于在消息中查找设备类型的简单 JSON 表达式（字符串 “SD” 将作为设备类型使用）。
timeout	60000	触发”设备断开”事件的超时时间
attributes		本小节包含消息中将被解释为设备 attribute 的参数。
… type	string	当前 attribute 的输入数据类型。
… key	serialNumber	将发送到 ThingsBoard 实例的 attribute 名称。
… value	${serial}	用于在消息中查找 value 的简单 JSON 表达式，将作为 key 参数的值发送到 ThingsBoard 实例。
timeseries		本小节包含消息中将被解释为设备 telemetry 的参数。
… type	string	当前 telemetry 的输入数据类型。
… key	Maintainer	将发送到 ThingsBoard 实例的 telemetry 名称。
… value	${Developer}	用于在消息中查找 value 的简单 JSON 表达式，将作为 key 参数的值发送到 ThingsBoard 实例。
… type	integer	当前 telemetry 的输入数据类型。
… key	Pressure	将发送到 ThingsBoard 实例的 telemetry 名称。
… value	${press}	用于在消息中查找 value 的简单 JSON 表达式，将作为 key 参数的值发送到 ThingsBoard 实例。
… tsField	${timestampField}	可选。携带日期时间字符串的字段的 JSON-path 表达式。若未指定，将使用消息中的 `ts` 或 `timestamp` 作为数据条目时间戳。
… dayfirst	false	可选。指明第一个数字为日（`DD.MM.YY HH:mm:ss.SSS`）。 • `false` → `10.11.24 10:10:10.252` → 2024年10月11日 10:10:10.252 • `true` → `10.11.24 10:10:10.252` → 2024年11月10日 10:10:10.252
… yearfirst	false	可选。指明第一个数字为年（`DD.MM.YY HH:mm:ss.SSS`）。 • `false` → 遵循 `dayfirst` 规则 • `true` → `10.11.24 10:10:10.252` → 2010年11月24日 10:10:10.252

Mapping subsection 将如下所示：

    {
      "url": "getdata",
      "httpMethod": "GET",
      "httpHeaders": {
        "ACCEPT": "application/json"
      },
      "allowRedirects": true,
      "timeout": 0.5,
      "scanPeriod": 5,
      "converter": {
        "type": "json",
        "deviceNameJsonExpression": "SD8500",
        "deviceTypeJsonExpression": "SD",
        "attributes": [
          {
            "key": "serialNumber",
            "type": "string",
            "value": "${serial}"
          }
        ],
        "telemetry": [
          {
            "key": "Maintainer",
            "type": "string",
            "value": "${Developer}"
          },
          {
            "key": "Pressure",
            "type": "integer",
            "value": "${press}",
            "tsField": "${timestampField}",
            "dayfirst": true
          }
        ]
      }
    }

此外，可在 attribute、telemetry 和 serverSideRpc 部分组合 HTTP 请求中的值，例如：

{
      "url": "getdata",
      "httpMethod": "GET",
      "httpHeaders": {
        "ACCEPT": "application/json"
      },
      "allowRedirects": true,
      "timeout": 0.5,
      "scanPeriod": 5,
      "converter": {
        "type": "json",
        "deviceNameJsonExpression": "SD8500",
        "deviceTypeJsonExpression": "SD",
        "attributes": [],
        "telemetry": [
          {
            "type": "double",
            "key": "temperature",
            "value": "${temp}"
          },
          {
            "type": "double",
            "key": "humidity",
            "value": "${hum}"
          },
          {
            "type": "string",
            "key": "combine",
            "value": "${hum}:${temp}"
          }
        ]
      }
    }

Custom converter 是为特定设备编写的 converter：

参数	默认值	说明
type	custom	指示 connector 使用 custom converter 转换响应数据。
extension	CustomRequestUplinkConverter	Custom converter 类名。
extension-config		本小节为 custom converter 的配置。默认示例中包含解析响应字符串的设置。
key	Totaliser	本例中值 “Totaliser” 将作为 ThingsBoard 实例中的 telemetry key 解释。
type	float	本例中数据的类型。
fromByte	0	本例中响应字符串的起始字节位置。
toByte	4	本例中响应字符串的结束字节位置。
byteorder	big	本例中响应字符串的字节序。
signed	true	本例中用于表示响应中的数据是否为有符号数。
multiplier	1	本例中响应中的每个数据应乘以的系数。

配置中的 Mapping subsection 将如下所示：

    {
      "url": "get_info",
      "httpMethod": "GET",
      "httpHeaders": {
        "ACCEPT": "application/json"
      },
      "allowRedirects": true,
      "timeout": 0.5,
      "scanPeriod": 100,
      "converter": {
        "type": "custom",
        "deviceNameJsonExpression": "SD8500",
        "deviceTypeJsonExpression": "SD",
        "extension": "CustomRequestUplinkConverter",
        "extension-config": [
          {
            "key": "Totaliser",
            "type": "float",
            "fromByte": 0,
            "toByte": 4,
            "byteorder": "big",
            "signed": true,
            "multiplier": 1
          },
          {
            "key": "Flow",
            "type": "int",
            "fromByte": 4,
            "toByte": 6,
            "byteorder": "big",
            "signed": true,
            "multiplier": 0.01
          }
        ]
      }
    }

属性更新部分

本部分配置为可选。ThingsBoard支持预配设备属性，并可从设备应用拉取部分属性。可将其视为设备的远程配置，设备可从ThingsBoard请求共享属性。详见用户指南。

「attributeRequests」配置用于设置相应属性请求与响应消息的格式。

参数	默认值	说明
httpMethod	GET	请求的HTTP方法（GET、POST等）。
httpHeaders	{ “CONTENT-TYPE”: “application/json” }	包含请求额外HTTP头的对象。
timeout	0.5	请求超时时间。
tries	3	发送数据的重试次数。
allowRedirects	true	是否允许请求重定向。
deviceNameFilter	SD.*	设备名称的正则表达式过滤，用于确定执行哪个函数。
attributeFilter	send_data	属性名称的正则表达式过滤，用于确定执行哪个函数。
requestUrlExpression	sensor/${deviceName}/${attributeKey}	用于创建发送消息的URL地址的JSON-path表达式。
valueExpression	{\”${attributeKey}\”:\”${attributeValue}\”}	用于创建将发送至URL的消息数据的JSON-path表达式。

attributeUpdates部分示例如下：

  "attributeUpdates": [
      {
        "httpMethod": "POST",
        "httpHeaders": {
          "CONTENT-TYPE": "application/json"
        },
        "timeout": 0.5,
        "tries": 3,
        "allowRedirects": true,
        "deviceNameFilter": "SD.*",
        "attributeFilter": "send_data",
        "requestUrlExpression": "sensor/${deviceName}/${attributeKey}",
        "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
      }
  ]

服务端RPC部分

ThingsBoard支持向直接或通过网关连接到ThingsBoard的设备发送RPC命令。

本部分提供的配置用于从ThingsBoard向设备发送RPC请求。

参数	默认值	说明
deviceNameFilter	SmartMeter.*	设备名称的正则表达式过滤，用于确定执行哪个函数。
methodFilter	echo	方法名称的正则表达式过滤，用于确定执行哪个函数。
requestUrlExpression	sensor/${deviceName}/request/${methodName}/${requestId}	用于创建发送RPC请求的URL地址的JSON-path表达式。
responseTimeout	0.5	请求超时时间。
httpMethod	GET	请求的HTTP方法（GET、POST等）。
valueExpression	${params}	用于创建发送至外部端点数据的JSON-path表达式。
timeout	0.5	请求超时时间。
tries	3	发送数据的重试次数。
httpHeaders	{ “CONTENT-TYPE”: “application/json” }	包含请求额外HTTP头的对象。

  "serverSideRpc": [
    {
      "deviceNameFilter": ".*",
      "methodFilter": "echo",
      "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
      "responseTimeout": 1,
      "httpMethod": "GET",
      "valueExpression": "${params}",
      "timeout": 0.5,
      "tries": 3,
      "httpHeaders": {
        "Content-Type": "application/json"
      }
    },
    {
      "deviceNameFilter": ".*",
      "methodFilter": "no-reply",
      "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
      "httpMethod": "POST",
      "valueExpression": "${params.hum}",
      "httpHeaders": {
        "Content-Type": "application/json"
      }
    }
  ]

下一步

探索与ThingsBoard主要功能相关的指南：

数据可视化 -如何可视化采集的数据
设备属性 -如何使用设备属性
遥测数据采集 -如何采集遥测数据
使用RPC功能 -如何向/从设备发送命令
规则引擎 -如何使用规则引擎分析设备数据