应用开发API 入口:
https://openapi.heclouds.com/common?action=具体接口名称&version=1
第一部分 应用开发流程及项目分组
一. 应用开发流程
https://open.iot.10086.cn/doc/iot_platform/book/application-develop/application-process.html
1. 创建项目
2. 进入项目添加设备
3. 调用API
本篇文章的主题
4. 数据流转
此项内容会单独写一篇文章
二. 项目分组
1. 分组
项目中,我们可以创建分组,这样是的设备被分组管理,方便区分业务权限, 非常推荐使用
分完组后可以添加设备
我们看到有分组ID和分组key
想到第一篇中的设备鉴权描述, 确实是可以以项目/分组进行鉴权的
这样我们可以做到 客户1用自己的鉴权管理自己的设备的效果.
2. 分组鉴权的Token计算
根据文档, 我修改了这个程序,实测可用
import base64
import hmac
import time
from urllib.parse import quote
def token(projectid,groupid,access_key):
version = '2020-05-29'
res1 = 'projectid/%s' % projectid
res2 = '/groupid/%s' % groupid
res = res1+res2
# 用户自定义token过期时间
et = str(int(time.time()) + 3600*24*365)
# 签名方法，支持md5、sha1、sha256
method = 'sha1'
# 对access_key进行decode
key = base64.b64decode(access_key)
# 计算sign
org = et + '\n' + method + '\n' + res + '\n' + version
sign_b = hmac.new(key=key, msg=org.encode(), digestmod=method)
sign = base64.b64encode(sign_b.digest()).decode()
# value 部分进行url编码，method/res/version值较为简单无需编码
sign = quote(sign, safe='')
res = quote(res, safe='')
# token参数拼接
token = 'version=%s&res=%s&et=%s&method=%s&sign=%s' % (version, res, et, method, sign)
return token
if __name__ == '__main__':
projectid = 'Sd5MPm'
groupid = 'HkhwSb'
access_key = 'MjE5OWIwYzJmZGU5ZDVmMjY1NTQyNmY4ZjM5M2ZjMjY='
print(token(projectid,groupid,access_key))
while(1):
pass
第二部分 项目相关API
一. 项目概况
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryStatistics.html
这是一个GET请求 参数是项目ID
返回结果:
二. 项目集成产品列表
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryProductList.html
这是一个GET请求 参数是项目ID
返回如下, 说明我们这个项目里只有1类产品
三. 项目集成设备列表
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDeviceList.html
参数可限定查询的范围, 根据自己的需求选择
结果:
{
"data": {
"list": [
{
"created_time": "2020-10-19T03:59:05.365Z",
"device_name": "esp_mqtts_003",
"from": 1,
"last_time": null,
"node_type": 1,
"product_id": "IaiJ9078ZN",
"product_name": "esp_mqtts_test",
"status": 1
},
{
"created_time": "2020-10-19T03:43:14.953Z",
"device_name": "esp_mqtts_002",
"from": 1,
"last_time": null,
"node_type": 1,
"product_id": "IaiJ9078ZN",
"product_name": "esp_mqtts_test",
"status": 1
},
{
"created_time": "2020-10-16T00:27:39.858Z",
"device_name": "esp_mqtts_001",
"from": 1,
"group_id": "HkhwSb",
"group_name": "客户1的设备",
"last_time": "2020-10-19T01:21:03.965Z",
"node_type": 1,
"product_id": "IaiJ9078ZN",
"product_name": "esp_mqtts_test",
"status": 3
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 3
}
},
"requestId": "f4e04c9f4fcb412cae13c48e6fc64ae7",
"success": true
}
加入分组筛选
结果
四. 项目添加设备
https://open.iot.10086.cn/doc/iot_platform/book/api/application/addDevice.html
这个API是一个批量添加设备的API
先写好POST
再编辑body
返回:
如果添加的设备有对有错会怎么样?
虽然只报了两个错误, 但其实都没添加进去
五. 项目移除设备
https://open.iot.10086.cn/doc/iot_platform/book/api/application/removeDevice.html
和上面的用法完全一样
第三部分 分组相关API
一. 创建分组
https://open.iot.10086.cn/doc/iot_platform/book/api/application/createGroup.html
二. 移除分组
https://open.iot.10086.cn/doc/iot_platform/book/api/application/deleteGroup.html
和上面一样
三. 编辑分组
能够修改标签和描述
这个POST请求里有个tag, 是一个对象, 我们把要修改的标签内容放在这
结果:
四. 分组详情
一个简单的get请求
五. 分组列表
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryGroupList.html
返回结果: 我的分组清单
{
"data": {
"list": [
{
"created_time": "2020-10-20T00:50:51.048Z",
"desc": "这是API添加的描述",
"device_count": 0,
"id": "gdu8N0",
"key": "YTY5MzVmOGYxOWU2OWVkZDE2MDE2MTNlZGE1MjZlMjY=",
"name": "客户2的分组",
"project_id": "Sd5MPm",
"tag": {
"tag1": "客户2修改的分组"
}
},
{
"created_time": "2020-10-19T07:21:27.988Z",
"device_count": 1,
"id": "HkhwSb",
"key": "MjE5OWIwYzJmZGU5ZDVmMjY1NTQyNmY4ZjM5M2ZjMjY=",
"name": "客户1的设备",
"project_id": "Sd5MPm"
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 2
}
},
"requestId": "d2f4de7823234a7f8e3909de04468370",
"success": true
}
六. 分组添加设备
七. 分组移除设备
和上面用法一样
第四部分 设备相关API
一. 设备详情
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDeviceDetail.html
返回结果: (结果和设备管理API里的结果一样)
{
"data": {
"active_time": "2020-10-16T01:17:28.774Z",
"created_time": "2020-10-16T00:27:39.858Z",
"desc": "",
"device_name": "esp_mqtts_001",
"ip": "123.135.14.245",
"last_time": "2020-10-19T01:21:03.965Z",
"node_type": 1,
"product_id": "IaiJ9078ZN",
"product_name": "esp_mqtts_test",
"protocol": 2,
"sec_key": "x3NzP/HJi4s75RWFz+cJZUcRi9PZ7yH7VWVtPxeXVbU=",
"status": 3
},
"requestId": "69d049cc2e534c9896cf4a0621273d8a",
"success": true
}
二. 查询设备状态
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDeviceStatus.html
返回结果:
返回结果中的状态码解释如下:
- 未激活
- 在线
- 离线
三. 设备状态历史数据查询
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDeviceStatusHistory.html
设备状态:
0-离线
1-在线
返回结果:
{
"data": {
"list": [
{
"status": 0,
"time": 1603070463965
},
{
"status": 1,
"time": 1603069550700
},
{
"status": 0,
"time": 1602835011872
},
{
"status": 1,
"time": 1602830895892
},
{
"status": 0,
"time": 1602830895771
},
{
"status": 1,
"time": 1602823318899
},
{
"status": 0,
"time": 1602823317748
},
{
"status": 1,
"time": 1602823259833
},
{
"status": 0,
"time": 1602823251848
},
{
"status": 1,
"time": 1602823204386
}
],
"meta": {
"limit": 10,
"offset": 0
}
},
"requestId": "da051a335742444ba198174e774a0de6",
"success": true
}
四. 设备属性设置(重要!!)
https://open.iot.10086.cn/doc/iot_platform/book/api/application/setDeviceProperty.html
这个API调用起来很方便, 但是他是一个同步API, 所以设备侧必须给它正确的响应
调用:
如果你的设备没有订阅$sys/{pid}/{device-name}/thing/property/set主题,
会告诉你 bad request
此时设备端会收到:
这里我们看到消息有一个id , 我们的设备必须告诉服务器,这个id的属性设置命令已经收到下发
故而我们的设备应该订阅: $sys/{pid}/{device-name}/thing/property/set_reply主题, 并按照以下格式回复(id的值也要打引号)
{
"id": "2",
"code":200,
"msg":"success"
}
像这样:
具体程序可以参考文章:
收到结果:
五. 获取设备属性
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDevicePropertyDetail.html
这是一个同步下发命令的消息, 需要设备回复
如果设备订阅了$sys/{pid}/{device-name}/thing/property/get主题, 可以收到:
这里我们看到消息有一个id , 我们的设备回复时必须告诉服务器,这个id的数据请求命令已经收到下发,并做如下格式回应:
{
"id":"123",
"code":200,
"msg":"xxx",
"data":{
"temperature":39.5,
"humidity":20
}
}
具体程序可以参考文章:
收到结果:
六. 设备操作日志查询
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDeviceLog.html
回复内容如下:
{
"data": {
"list": [
{
"request_body": [
"temp",
"humi"
],
"request_time": "1603249729056",
"response_body": {
"code": 200,
"data": {
"humi": 50.16,
"temp": 21.17
},
"id": "56",
"msg": "success"
},
"response_time": "1603249731615",
"type": 1
},
{
"request_body": [
"temp",
"humi"
],
"request_time": "1603249711997",
"response_body": {
"code": 200,
"data": {
"humi": 50.32,
"temp": 21.16
},
"id": "55",
"msg": "success"
},
"response_time": "1603249712280",
"type": 1
},
{
"request_body": [
"temp",
"humi"
],
"request_time": "1603249176496",
"response_body": {
"code": 200,
"data": {
"humi": 50.69,
"temp": 21.09
},
"id": "54",
"msg": "success"
},
"response_time": "1603249176827",
"type": 1
},
{
"request_body": [
"temp",
"humi"
],
"request_time": "1603249105629",
"response_body": {
"code": 2006,
"id": "53",
"msg": "acc timeout"
},
"response_time": "1603249111641",
"type": 1
},
{
"request_body": [
"temp",
"humi"
],
"request_time": "1603249082004",
"response_body": {
"code": 2006,
"id": "52",
"msg": "acc timeout"
},
"response_time": "1603249088031",
"type": 1
},
{
"request_body": [
"temp"
],
"request_time": "1603249050023",
"response_body": {
"code": 2006,
"id": "51",
"msg": "acc timeout"
},
"response_time": "1603249056035",
"type": 1
},
{
"request_body": [
"temp"
],
"request_time": "1603246830306",
"response_body": {
"code": 2006,
"id": "50",
"msg": "acc timeout"
},
"response_time": "1603246836321",
"type": 1
},
{
"request_body": {
"switch": true
},
"request_time": "1603246815178",
"response_body": {
"code": 200,
"id": "49",
"msg": "success"
},
"response_time": "1603246816288",
"type": 0
},
{
"request_body": {
"switch": true
},
"request_time": "1603246684325",
"response_body": {
"code": 200,
"id": "48",
"msg": "success"
},
"response_time": "1603246684422",
"type": 0
},
{
"request_body": {
"switch": true
},
"request_time": "1603246501128",
"response_body": {
"code": 2006,
"id": "47",
"msg": "acc timeout"
},
"response_time": "1603246507163",
"type": 0
}
],
"meta": {
"limit": 10,
"offset": 0
}
},
"requestId": "1c52994f6572464f9ab5d91be66de35b",
"success": true
}
七. 设备属性最新数据查询
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDeviceProperty.html
结果
{
"data": {
"list": [
{
"access_mode": "只读",
"data_type": "array",
"description": "",
"expect_value": "",
"identifier": "$OneNET_LBS",
"name": "基站定位",
"time": "0",
"value": ""
},
{
"access_mode": "只读",
"data_type": "float",
"description": "",
"expect_value": "",
"identifier": "humi",
"name": "湿度",
"time": "1603251069037",
"value": "48.77"
},
{
"access_mode": "读写",
"data_type": "bool",
"description": "",
"expect_value": "false",
"identifier": "switch",
"name": "switch",
"time": "1603251069037",
"value": ""
},
{
"access_mode": "只读",
"data_type": "float",
"description": "",
"expect_value": "",
"identifier": "temp",
"name": "温度",
"time": "1603251069037",
"value": "21.36"
}
]
},
"requestId": "d35f128bd4e746d4b21227d4de8722e2",
"success": true
}
八. 设备属性历史数据查询
https://open.iot.10086.cn/doc/iot_platform/book/api/application/queryDevicePropertyHistory.html
注意:参数里有个sort 排序参数 1-正序 2-倒序
如果调用这个API查看历史数据, 大概率要用到offset和limit
注意 limit范围是1~100
返回结果示例:
{
"data": {
"list": [
{
"time": "1603070440958",
"value": "19.29"
},
{
"time": "1603070430957",
"value": "19.29"
},
{
"time": "1603070420958",
"value": "19.28"
},
{
"time": "1603070410956",
"value": "19.29"
},
{
"time": "1603070400954",
"value": "19.28"
},
{
"time": "1603070390956",
"value": "19.28"
},
{
"time": "1603070380971",
"value": "19.28"
},
{
"time": "1603070370968",
"value": "19.28"
},
{
"time": "1603070360957",
"value": "19.28"
},
{
"time": "1603070350956",
"value": "19.28"
}
],
"meta": {
"limit": 10,
"offset": 0
}
},
"requestId": "e4e783b2a2e64cfbba76d08044db8917",
"success": true
}
七. 设备属性期望设置
https://open.iot.10086.cn/doc/iot_platform/book/api/application/setDeviceDesiredProperty.html