入门

HTTP 基础知识

HTTP是一种通用网络协议，可用于 IoT 应用程序。您可以在此处找到有关 HTTP 的更多信息。HTTP 协议基于 TCP 并使用请求-响应模型。
ThingsBoard 服务器节点充当支持 HTTP 和 HTTPS 协议的 HTTP 服务器。

客户端库设置

您可以在 Web 上找到适用于不同编程语言的 HTTP 客户端库。本文中的示例将基于curl。

HTTP 身份验证和错误代码

我们将在本文中使用访问令牌设备凭据，稍后将它们称为$ACCESS_TOKEN。应用程序需要在每个 HTTP 请求中包含$ACCESS_TOKEN作为路径参数。可能的错误代码及其原因：

  • 400 Bad Request - 无效的 URL、请求参数或正文。
  • 401 未经授权- 无效的 $ACCESS_TOKEN。
  • 404 Not Found - 找不到资源。

    键值格式

    默认情况下，ThingsBoard 支持 JSON 中的键值内容。键始终是字符串，而值可以是字符串、布尔值、双精度、长整型或 JSON。例如：
    1. {
    2. "stringKey":"value1", 
    3. "booleanKey":true, 
    4. "doubleKey":42.0, 
    5. "longKey":73, 
    6. "jsonKey": {
    7.   "someNumber": 42,
    8.   "someArray": [1,2,3],
    9.   "someNestedObject": {"key": "value"}
    10. }
    11. }

    遥测上传 API

    为了将遥测数据发布到 ThingsBoard 服务器节点，请将 POST 请求发送到以下 URL：
http(s)://host:port/api/v1/$ACCESS_TOKEN/telemetry

支持的最简单的数据格式是：

  1. {"key1":"value1", "key2":"value2"}

要么

  1. [{"key1":"value1"}, {"key2":"value2"}]

请注意，在这种情况下，服务器端时间戳将分配给上传的数据！
如果您的设备能够获取客户端时间戳，您可以使用以下格式：

  1. {"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

在上面的示例中，我们假设“1451649600512”是一个毫秒精度的unix 时间戳。例如，值“1451649600512”对应于“Fri, 01 Jan 2016 12:00:00.512 GMT”

  • 遥测数据作为object.json

    1. {
    2. "stringKey": "value1",
    3. "booleanKey": true,
    4. "doubleKey": 42.0,
    5. "longKey": 73,
    6. "jsonKey": {
    7.   "someNumber": 42,
    8.   "someArray": [1,2,3],
    9.   "someNestedObject": {"key": "value"}
    10. }
    11. }

  • 遥测数据作为array.json

    [{"key1":"value1"}, {"key2":true}]

  • 遥测数据与 ts.json

    {
"ts": 1451649600512,
"values": {
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1, 2, 3],
    "someNestedObject": {
      "key": "value"
    }
  }
}
}

    案例 ```shell

    将数据发布为没有时间戳的对象 (服务端时间戳将被私用). 将 $RELAPERIOT_HOST_NAME 和 $ACCESS_TOKEN 替换为相应的值。

    curl -v -X POST —data “{“temperature”:42,”humidity”:73}” http://$RELAPERIOT_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry —header “Content-Type:application/json”

    例如，$RELAPERIOT_HOST_NAME 参考实际服务器，$ACCESS_TOKEN 为 ABC123：

    curl -v -X POST —data “{“temperature”:42,”humidity”:73}” http://iot.relaper.com//api/v1/ABC123/telemetry —header “Content-Type:application/json”

使用文件中的数据将数据发布为不带时间戳的对象（将使用服务器端时间戳）。 将 $RELAPERIOT_HOST_NAME 和 $ACCESS_TOKEN 替换为相应的值。

curl -v -X POST -d @telemetry-data-as-object.json http://$RELAPERIOT_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry —header “Content-Type:application/json”

例如，$RELAPERIOT_HOST_NAME 参考现场演示服务器，$ACCESS_TOKEN 为 ABC123：

curl -v -X POST -d @telemetry-data-as-object.json http://iot.relaper.com/api/v1/ABC123/telemetry —header “Content-Type:application/json”

使用文件中的数据将数据发布为不带时间戳的对象数组（将使用服务器端时间戳）。 将 $RELAPERIOT_HOST_NAME 和 $ACCESS_TOKEN 替换为相应的值。

curl -v -X POST -d @telemetry-data-as-array.json http://$RELAPERIOT_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry —header “Content-Type:application/json”

例如，$RELAPERIOT_HOST_NAME 参考现场演示服务器，$ACCESS_TOKEN 为 ABC123：

curl -v -X POST -d @telemetry-data-as-array.json http://iot.relaper.com/api/v1/ABC123/telemetry —header “Content-Type:application/json”

使用文件中的数据将数据发布为带有时间戳的对象（将使用遥测时间戳）。 将 $RELAPERIOT_HOST_NAME 和 $ACCESS_TOKEN 替换为相应的值。

curl -v -X POST -d @telemetry-data-with-ts.json http://$RELAPERIOT_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry —header “Content-Type:application/json”

例如，$RELAPERIOT_HOST_NAME 参考现场演示服务器，$ACCESS_TOKEN 为 ABC123：

curl -v -X POST -d @telemetry-data-with-ts.json http://iot.relaper.com/api/v1/ABC123/telemetry —header “Content-Type:application/json” ```

属性 API

物联网平台属性API能够使设备具备如下功能：

  • 将客户端设备属性上传到服务端
  • 从服务端请求客户端和共享属性
  • 从服务端订阅共享属性
  • 通过服务端发布客户端属性
    将属性更新发布到服务器
    为了将客户端设备属性发布到 ThingsBoard 服务器节点，请将 POST 请求发送到以下 URL：
http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes

从服务器请求属性值

为了向 ThingsBoard 服务器节点请求客户端或共享设备属性，请将 GET 请求发送到以下 URL：

http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2 http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

请注意，客户端和共享设备属性键的交集是一种不好的做法！但是，仍然可以为客户端、共享甚至服务器端属性使用相同的密钥。

从服务器订阅属性更新

要订阅共享设备属性更改，请将带有可选“超时”请求参数的 GET 请求发送到以下 URL：

http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes/updates http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes/updates

一旦共享属性将被服务器端组件（REST API 或规则链）之一更改，客户端将收到以下更新：

JSON 值支持

我们向遥测和属性 API 添加了对 JSON 数据结构的支持，以简化设备配置工作。JSON 支持使您既可以从设备上传，也可以推送到设备嵌套对象。您可以将一个配置 JSON 存储为共享属性并将其推送到设备。您还可以在规则引擎中处理 JSON 数据并发出警报等。
因此，这一改进最大限度地减少了 ThingsBoard 存储数据时的数据库操作次数。例如，“温度”和“湿度”将作为单独的行存储在 SQL 或 NoSQL 数据库中，以便有效地聚合这些数据以进行可视化。由于不需要聚合 JSON 数据，我们可以将所有内容存储为一行，而不是为每个配置项单独一行。在我们的一些环境中，通过在一个 JSON 中聚合多个参数，可以将数据库操作的数量减少 10 倍以上。
通过视频了解有关 JSON 值支持的更多信息。

RPC API

服务器端 RPC

为了从服务器订阅 RPC 命令，将带有可选“timeout”请求参数的 GET 请求发送到以下 URL：

http(s)://host:port/api/v1/$ACCESS_TOKEN/rpc http(s)://host:port/api/v1/$ACCESS_TOKEN/rpc

订阅后，如果没有对特定设备的请求，客户端可能会收到 rpc 请求或超时消息。RPC 请求正文的示例如下所示：

1 2 3 4 5 6 7 8 { “id”: “1”, “method”: “setGpio”, “params”: { “pin”: “23”, “value”: 1 } } 1 2 3 4 5 6 7 8 { “id”: “1”, “method”: “setGpio”, “params”: { “pin”: “23”, “value”: 1 } }

在哪里

  • id - 请求 id，整数请求标识符
  • 方法- RPC 方法名称，字符串
  • params - RPC 方法参数，自定义 json 对象

并且可以使用对以下 URL 的 POST 请求回复他们：

http://host:port/api/v1/$ACCESS_TOKEN/rpc/{$id} http://host:port/api/v1/$ACCESS_TOKEN/rpc/{$id}

其中$id是一个整数请求标识符。

让我们看一个例子：

  • 使用RPC 调试终端仪表板；
  • 从服务器订阅 RPC 命令。为此，在第一个终端窗口中发送带有观察标志的 GET 请求；
  • 向设备发送 RPC 请求“连接”；
  • 在第二个终端窗口中模拟从设备向服务器发送响应；
  • 您应该会收到来自设备的响应：{“result”:“ok”}

image.png
image.png
image.png
image.png
image.png

客户端 RPC

为了向服务器发送 RPC 命令，请将 POST 请求发送到以下 URL：

http://host:port/api/v1/$ACCESS_TOKEN/rpc http://host:port/api/v1/$ACCESS_TOKEN/rpc

请求和响应正文都应该是有效的 JSON 文档。文档的内容特定于将处理您的请求的规则节点。

让我们看一个例子：

  • 将两个节点添加到规则链中：“脚本”和“rpc 调用回复”；
  • 在脚本节点中输入函数： | return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType}; | return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType}; | | —- | —- |

复制到剪贴板
HTTP设备API - 图10

  • 向服务器发送请求；
  • 您应该收到来自服务器的响应。

image.png
image.png
image.png
image.png
image.png

认领设备

请参阅相应文章以获取有关声明设备功能的更多信息。
为了启动认领设备，向以下 URL 发送 POST 请求：

http(s)://host:port/api/v1/$ACCESS_TOKEN/claim http(s)://host:port/api/v1/$ACCESS_TOKEN/claim

支持的数据格式为：

{“secretKey”:”value”, “durationMs”:60000} {“secretKey”:”value”, “durationMs”:60000}

请注意，上述字段是可选的。如果未指定secretKey，则使用空字符串作为默认值。如果没有指定durationMs ，则使用系统参数device.claim.duration（在文件/etc/thingsboard/conf/thingsboard.yml 中）。

设备配置

请参阅相应文章以获取有关设备配置功能的更多信息。
要启动设备配置，请将 POST 请求发送到以下 URL：

http(s)://host:port/api/v1/provision http(s)://host:port/api/v1/provision

支持的数据格式为：

1 2 3 4 5 { “deviceName”: “DEVICE_NAME”, “provisionDeviceKey”: “u7piawkboq8v32dmcmpp”, “provisionDeviceSecret”: “jpmwdn8ptlswmf4m29bw” } 1 2 3 4 5 { “deviceName”: “DEVICE_NAME”, “provisionDeviceKey”: “u7piawkboq8v32dmcmpp”, “provisionDeviceSecret”: “jpmwdn8ptlswmf4m29bw” }