HTTP集成

概述
创建上行转换器
创建集成
发送上行消息
- 启用安全选项
下行转换器
下一步

概述

HTTP集成可将现有协议和负载格式转换为ThingsBoard消息格式，适用于多种部署场景：

从外部系统、IoT平台或连接提供商后端流式传输设备和/或资产数据。
从云上运行的自定义应用流式传输设备和/或资产数据。
将采用自定义基于HTTP协议的现有设备连接至ThingsBoard。

创建上行转换器

创建集成前，需在Data converters中创建上行转换器。上行转换器用于将设备入站数据转换为ThingsBoard展示所需的格式。点击”plus”按钮并选择”Create new converter”。要查看事件，请启用Debug。在decoder函数字段中，指定用于解析和转换数据的脚本。

调试模式

启用调试模式可追踪与integrations执行相关的事件、状态及潜在错误，便于开发和排障。

调试模式设置可组合使用或完全关闭。

可使用 TBEL（TBEL）或 JavaScript 开发用户自定义函数。建议使用 TBEL，其在ThingsBoard 中的执行效率远高于 JS。

TBELRecommended

JavaScript

Uplink converter 示例：

// Decode an uplink message from a buffer
// payload - array of bytes
// metadata - key/value object

/** Decoder **/
 
// decode payload to string
// var payloadStr = decodeToString(payload);

// decode payload to JSON
var data = decodeToJson(payload);

var deviceName = data.deviceName;
var deviceType = data.deviceType;

// Result object with device attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       model: data.model,
       serialNumber: data.param2,
   },
   telemetry: {
       temperature: data.temperature
   }
};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

可在创建 converter 时或创建后修改 decoder function。若 converter 已存在，点击「铅笔」图标进行编辑。复制 converter 的配置示例（或您自己的配置）并插入到 decoder function 中。点击「勾选」图标保存更改。

Uplink converter 示例：

// Decode an uplink message from a buffer
// payload - array of bytes
// metadata - key/value object

/** Decoder **/

// decode payload to string
// var payloadStr = decodeToString(payload);

// decode payload to JSON
var data = decodeToJson(payload);

var deviceName = data.deviceName;
var deviceType = data.deviceType;

// Result object with device attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       model: data.model,
       serialNumber: data.param2,
   },
   telemetry: {
       temperature: data.temperature
   }
};

/** Helper functions **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}
function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);
   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}

return result;

上行转换器创建完成后即可创建集成。

创建集成

进入“Integrations center”->“Integrations”页面，点击“plus”创建新集成。命名为“HTTP Integration”，选择类型“HTTP”。点击“Next”；

在此步骤可选择已有或新建上行转换器。选择刚创建的“HTTP Uplink Converter”。点击“Next”；

在添加下行转换器步骤中，也可选择已有或新建下行转换器。此处保持“Downlink data converter”为空。点击“Skip”；

在此步骤指定“Base URL”；
记录“HTTP endpoint URL”，后续会用到；
在“Advanced settings”中启用“Replace response status from ‘No-Content’ to ‘OK’”；
点击“Add”保存集成。

发送上行消息

发送上行消息需要用到之前从集成中复制的“HTTP endpoint URL”。

使用下列命令发送消息。请将 $DEVICE_NAME、$DEVICE_TYPE 和 $YOUR_HTTP_ENDPOINT_URL 替换为实际值。

curl -v -X POST -d "{\"deviceName\":\"$DEVICE_NAME\",\"deviceType\":\"$DEVICE_TYPE\",\"temperature\":33,\"model\":\"test\"}" $YOUR_HTTP_ENDPOINT_URL -H "Content-Type:application/json"

进入HTTP集成的“Events”标签。若配置正确，应能看到一条状态为’OK’的事件。

所创建设备及数据可在“Device groups”->“All”中查看。

发送和接收的数据也可在上行转换器中查看，位于“Events”标签的“In”和“Out”块。

使用Dashboards处理数据。仪表板是收集和展示数据集的现代化形式，通过各种部件呈现数据。
ThingsBoard提供多种仪表板示例。了解更多Solution templates请参阅此处。

启用安全选项

如需，可指定额外参数，缺少这些参数的数据将不会被纳入集成。勾选Enable security，点击Headers filter，填写任意值并保存。

Headers filter配置后，上行消息中需加入如下头：

-H "test-header:secret"

使用下列命令发送启用安全选项的消息。请将 $DEVICE_NAME、$DEVICE_TYPE、$YOUR_HTTP_ENDPOINT_URL 和 $VALUE 替换为实际值。

curl -v -X POST -d "{\"deviceName\":\"$DEVICE_NAME\",\"deviceType\":\"$DEVICE_TYPE\",\"temperature\":33,\"model\":\"test\"}" $YOUR_HTTP_ENDPOINT_URL -H "Content-Type:application/json" -H "$VALUE"

下行转换器

在“Data converters”页面创建下行转换器。要查看事件请启用“Debug mode”。

可使用 TBEL（TBEL）或 JavaScript 开发用户自定义函数。建议使用 TBEL，其在ThingsBoard 中的执行效率远高于 JS。

TBELRecommended

JavaScript

向 integration 添加 converter。可根据您的配置自定义 downlink。 Let’s consider an example where we send an attribute update message. So we should change code in the downlink encoder function under line //downlink data input:

data: JSON.stringify(msg)

where msg is the message that we receive and send back to the device.

Downlink converter 示例：

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

var result = {

    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",

    // downlink data
    data: JSON.stringify(msg),

    // Optional metadata object presented in key/value format
    metadata: {
    }
};

return result;

向集成添加转换器。您可以根据配置自定义下行。我们来看一个发送属性更新消息的示例。因此我们应修改 //下行数据 输入行下的下行编码器函数中的代码：

data: JSON.stringify(msg)

其中 msg 是我们接收并发回设备的消息。

下行转换器示例：

// 从传入规则引擎消息编码下行数据

// msg - 下行消息 JSON 负载
// msgType - 消息类型，例如 'ATTRIBUTES_UPDATED'、'POST_TELEMETRY_REQUEST' 等
// metadata - 包含消息附加数据的键值对列表
// integrationMetadata - 包含执行此转换器的集成中定义的附加数据的键值对列表

var result = {

    // 下行数据内容类型：JSON、TEXT 或 BINARY（base64 格式）
    contentType: "JSON",

    // 下行数据
    data: JSON.stringify(msg),

    // 以键/值格式呈现的可选元数据对象
    metadata: {
    }
};

return result;