跳至主要內容

设备 HTTP 接入

约 734 字大约 2 分钟

设备 HTTP 接入

对于一些非常单一的应用场景,比如只需要定期采集上报数据,不论是快速开发原型,还是小规模的应用,设备使用 HTTP 接入云平台也是不错的选择。

事实上,将 HTTP 协议的简单易用发挥到极致,便是 CoAP 协议,对于低功耗设备的单一数据上报,使用 CoAP 更加符合要求,这在相关章节会有介绍。

设备 HTTP 接入点

ThingsCloud 公有云支持全球多个区域,并随着设备接入量不断扩张。每个接入的设备有专用的 HTTP 接入点,获得设备 HTTP 接入点的正确方式,就是在控制台进入设备详情的【连接】页面,复制该设备的 HTTP 接入点。

我们提供多种 HTTP 接入点,如下:

接入类型用途接入点示例
HTTP普通方式,适合大多数普通设备或资源受限设备http:// <endpoint>
HTTPs基于 SSL 证书的加密传输方式,适合对通信安全要求严格的设备https:// <endpoint>

您可以根据需要任意选择使用以上接入点,也可以在不同的 API 中分别使用不同的接入点。

设备访问 API 一览

对于不同的消息类型,API 如下:

消息类型HTTP MethodHTTP URL
设备上报属性POST/device/v1/<AccessToken>/attributes
设备获取属性GET/device/v1/<AccessToken>/attributes
设备上报事件POST/device/v1/<AccessToken>/event/report

您只需要将以上的 HTTP URL 和接入点拼接即可获得最终 API URL,例如:

https://<endpoint>/device/v1/<AccessToken>/attributes

HTTP 身份认证

包括 HTTP 和 HTTPs 在内,调用设备访问 API 时,需要通过在 HTTP header 中加入 Project-Key 字段来配合云平台完成设备身份认证。如下:

Content-Type: application/json
Project-Key: <ProjectKey>

设备上报属性

设备希望向云平台上报属性时,调用如下 API:

POST https://<endpoint>/device/v1/<AccessToken>/attributes

HTTP 请求的正文部分,是 JSON 格式的消息结构。一个简单的属性上报消息如下:

{
    "temperature": 34.2,
    "humidity": 67,
    "switch": true
}

调用成功后,HTTP 响应正文如下:

{
  "result": 1,
  "ts": 1609143039050
}

设备获取属性

设备希望从云平台获取属性当前值,调用如下 API:

GET https://<endpoint>/device/v1/<AccessToken>/attributes

设备调用该 API 时,支持 GET 参数如下:

GET 参数说明
keys可选,用于指定希望获取的属性,用逗号分隔

例如:

GET https://<endpoint>/device/v1/<AccessToken>/attributes?keys=temperature,humidity

调用成功后,HTTP 响应正文如下:

{
  "result": 1,
  "attributes": {
    "temperature": 34.2,
    "humidity": 67
  }
}

设备上报事件

设备希望向云平台上报事件时,调用如下 API:

POST https://<endpoint>/device/v1/<AccessToken>/event/report

消息格式如下:

{
    "method": "{name}",
    "params": {
        "key1": "{value1}",
        "key2": "{value2}",
        ...
    },
    "id": {id}
}

{id} 的取值为不超过 6 位的整数,例如:1000

调用成功后,HTTP 响应正文如下:

{
  "result": 1,
  "ts": 1609143039050
}