OneNet5.0 新版产品应用开发API调用指南(三) 应用开发API

应用开发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

返回结果:

返回结果中的状态码解释如下:

1. 未激活
2. 在线
3. 离线

三. 设备状态历史数据查询

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