HTTP协议

入门

HTTP基础

HTTP是可在IoT应用程序中使用的通用网络协议可以在此处找到有关HTTP的更多信息，HTTP协议基于TCP并使用请求-响应模型。

蟹立方物联网平台服务器节点充当同时支持HTTP和HTTPS协议的HTTP Server。

客户端

你可以在网络上找到用于不同编程语言的HTTP客户端库本文中的示例将基于curl工具可以使用我们的Hello World指南中的说明。

HTTP身份验证

我们将在本文中使用令牌访问设备这些凭证稍后将称为$ACCESS_TOKEN应用程序需要在每个HTTP请求中包括$ACCESS_TOKEN作为路径参数错误代码及其原因：

400 - 无效的请求地址.
401 - 无效的 $ACCESS_TOKEN
404 - 未找到

Key-value格式

蟹立方物联网平台支持以JSON格式的key-value字符串值可以是string、bool、float、long或者二进制格式的序列化字符串；有关更多详细信息请参见协议自定义。

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

也可以使用自定义二进制格式或某些序列化框架有关更多详细信息请参见自定义自定义文档。

遥测上传API

为了将遥测数据发布到蟹立方物联网平台服务器节点请将POST请求发送到以下URL：

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

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

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

或者

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

请注意在这种情况下服务器端时间戳将分配给上传的数据！

如果你的设备能够获得客户端时间戳则可以使用以下格式:

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

在上面的示例中我们假设”1451649600512“是具有毫秒精度的Unix时间戳例如值’1451649600512’对应于’星期五2016年1月1日12：00：00.512 GMT’

# Publish data as an object without timestamp (server-side timestamp will be used). Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST --data "{"temperature":42,"humidity":73}" http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST --data "{"temperature":42,"humidity":73}" https://demo.蟹立方物联网平台.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

# Publish data as an object without timestamp (server-side timestamp will be used) using data from file. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @telemetry-data-as-object.json http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @telemetry-data-as-object.json https://demo.蟹立方物联网平台.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

# Publish data as an array of objects without timestamp (server-side timestamp will be used)  using data from file. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @telemetry-data-as-array.json http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @telemetry-data-as-array.json https://demo.蟹立方物联网平台.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

# Publish data as an object with timestamp (telemetry timestamp will be used)  using data from file. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @telemetry-data-with-ts.json http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @telemetry-data-with-ts.json https://demo.蟹立方物联网平台.io/api/v1/ABC123/telemetry --header "Content-Type:application/json"

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

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

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

属性API

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

将客户端设备属性上传到服务器
从服务器请求客户端和共享设备属性
从服务器订阅共享设备属性

发布属性

为了将客户端设备属性发布到蟹立方物联网平台服务器节点请将POST请求发送到以下URL：

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

# Publish client-side attributes update. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" https://demo.蟹立方物联网平台.io/api/v1/ABC123/attributes --header "Content-Type:application/json"

# Publish client-side attributes update from file. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @new-attributes-values.json http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @new-attributes-values.json https://demo.蟹立方物联网平台.io/api/v1/ABC123/attributes --header "Content-Type:application/json"

{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

请求属性

为了向蟹立方物联网平台服务器节点请求客户端或共享设备属性请将GET请求发送到以下URL：

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

# Send HTTP attributes request. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X GET "http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X GET "https://demo.蟹立方物联网平台.io/api/v1/ABC123/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"

{"client":{"attribute1":"value1","attribute2":true}}

请注意客户端和共享设备属性键的交集是不好的做法！但是对于客户端、共享和服务器端属性具有相同的密钥。

订阅属性

为了订阅共享设备属性更改请将带有可选”timeout”请求参数的GET请求发送到以下URL：

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

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

# Send subscribe attributes request with 20 seconds timeout. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X GET http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X GET https://demo.蟹立方物联网平台.io/api/v1/ABC123/attributes/updates?timeout=20000

{"client":{"attribute1":"value1","attribute2":true}}

支持JSON

我们在遥测和属性 API 中添加了对 JSON 数据结构的支持，以简化设备配置工作。JSON 支持允许您从设备上传和推送到设备嵌套对象。您可以将一个配置 JSON 存储为共享属性，并将其推送到设备。您还可以在规则引擎中处理 JSON 数据并引发警报等。

因此，当蟹立方物联网平台存储数据时，这种改进最大限度地减少了 Database作的数量。例如，“temperature” 和 “humidity” 将作为单独的行存储在 SQL 或 NoSQL 数据库中，以便有效地聚合这些数据以进行可视化。由于不需要聚合 JSON 数据，我们可以将所有内容存储为一行，而不是为每个配置项单独存储一行。在我们的一些环境中，可以通过在一个 JSON 中聚合多个参数，将数据库作的数量减少 10 倍以上。

通过视频了解有关 JSON 值支持的更多信息。

RPC API

服务器端RPC

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

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

订阅后如果没有对特定设备的请求则客户端可以接收rpc请求或超时RPC请求正文的示例如下所示：

{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

说明

id - 请求ID，int
method - RPC方法名称, string
params - -RPC方法参数，自定义json对象

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

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

参见下面示例：

使用RPC debug terminal在仪表板调试
从服务器订阅RPC命令并在第一个终端窗口中带有observe标志的发送请求
将RPC请求”connect”发送到设备
在第二个终端窗口中模拟将响应从设备发送到服务器
收到设备的响应:

alt text

# Send rpc request with 20 seconds timeout. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X GET http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc?timeout=20000
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X GET https://demo.蟹立方物联网平台.io/api/v1/ABC123/rpc?timeout=20000

# Publish response to RPC request. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -v -X POST -d @rpc-response.json http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -v -X POST -d @rpc-response.json https://demo.蟹立方物联网平台.io/api/v1/ABC123/rpc/1 --header "Content-Type:application/json"

{"result":"ok"}

客户端RPC

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

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

请求和响应主体都应该是有效的JSON文档。

参见下面示例：

在规则链中添加两个节点”script”和”rpc call reply”
在script中输入函数：

return {msg: {time:String(new Date())}, metadata: metadata, msgType: msgType};

将请求发送到服务器
收到服务器的响应

alt text

# Post client-side rpc request. Replace $蟹立方物联网平台_HOST_NAME and $ACCESS_TOKEN with corresponding values.
curl -X POST -d @rpc-client-request.json http://$蟹立方物联网平台_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"
# For example, $蟹立方物联网平台_HOST_NAME reference live demo server, $ACCESS_TOKEN is ABC123:
curl -X POST -d @rpc-client-request.json https://demo.蟹立方物联网平台.io/api/v1/ABC123/rpc --header "Content-Type:application/json"

{"method": "getCurrentTime", "params":{}}

{"time":"2016 11 21 12:54:44.287"}

声明设备

请参阅相应的文章以获取有关声明设备功能的更多信息。

启动声明设备请将POST请求发送到以下URL：

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

支持的数据格式为：

{"secretKey":"value", "durationMs":60000}

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

设备预配置

请参阅相应的文章并获取有关[设备供应]Device provisioning功能的更多信息。

启动设备配置请将发布请求发送到以下URL：

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

支持数据格式如下：

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "u7piawkboq8v32dmcmpp",
  "provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}

硬件API

当蟹立方物联网平台通过HTTP启动固件更新时它会设置FW_TITLE，FW_VERSION，FW_CHECKSUM，FW_CHECKSUM_ALGORITHM共享属性。

要接收共享属性更新该设备必须获取请求。

http(s)://host/api/v1/${access_token}/firmware?title=${title}&version=${version}

说明 host - 本地主机或平台地址 ${access_token} - 设备访问令牌 ${title} - 固件标题 ${version} - 固件的目标版本

自定义协议

通过更改相应的模块可以针对特定用例完全定制HTTP传输。

下一步

入门指南 - 快速学习蟹立方物联网平台相关功能。

安装指南 - 学习如何在各种操作系统上安装蟹立方物联网平台。

可视化 - 学习如何配置复杂的蟹立方物联网平台仪表板说明。

数据处理 - 学习如何使用蟹立方物联网平台规则引擎。

数据分析 - 学习如何使用规则引擎执行基本的分析任务。

硬件样品 - 学习如何将各种硬件平台连接到蟹立方物联网平台。

高级功能 - 学习高级蟹立方物联网平台功能。

开发指南 - 学习蟹立方物联网平台中的贡献和开发。

HTTP协议 ​

入门 ​

HTTP基础 ​

客户端 ​

HTTP身份验证 ​

Key-value格式 ​

遥测上传API ​

属性API ​

发布属性 ​

请求属性 ​

订阅属性 ​

支持JSON ​

RPC API ​

服务器端RPC ​

客户端RPC ​

声明设备 ​

设备预配置 ​

硬件API ​

自定义协议 ​

下一步 ​