提供一组与物(设备)相关的服务接口,客户端应用通过本组服务接口可以实现物信息的查询和控制,查询的内容涉及物的基本信息,物的上报数据信息以及物的TSL定义。

设备状态查询和控制

设备扩展属性

设备定时

App小组件控制设备

获取物的基本信息

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/info/get 1.0.2 获取物的信息,例如设备名称、MAC地址、设备激活时间等内容 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符

返回参数

参数 类型 必有 描述
gmtModified Long 设备记录数据修改时间(系统内部使用字段,可无需关心)
activeTime Long 设备首次激活时间
gmtCreate Long 设备记录创建时间,对于生活物联网平台而言,是量产时生成设备证书的时间
productKey String 产品key
statusLast Integer 上一次设备状态
mac String mac地址
deviceSecret String 设备secret
iotId String 设备唯一标识符
name String 设备名称
sdkVersion String sdk版本
sn String 设备sn
thingType String 设备类型
  • VIRTUAL:虚拟设备
  • VIRTUAL_SHADOW:虚拟设备
  • DEVICE:真实设备
firmwareVersion String 固件版本号
rbacTenantId String 租户id
status Integer 设备状态
  • 0:未激活
  • 1:在线
  • 3:离线
  • 8:禁用
netAddress String ip地址

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D2429xxxxE4F31A2697"
        }
    }      
  • 正常返回示例
    {
        "code": 200,
        "data": {
            "gmtModified": 1517918765000,
            "activeTime": null,
            "gmtCreate": 1500017648000,
            "productKey": "kQxxxxqA",
            "statusLast": null,
            "mac": null,
            "netAddress": null,
            "deviceSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "iotId": "D95D242xxxxxxxx4F31A2697",
            "name": "Kq7rgxxxxxwJh",
            "nickname": null,
            "sdkVersion": null,
            "sn": null,
            "thingType": "DEVICE",
            "firmwareVersion": "1.0.0",
            "rbacTenantId": "ADSBCxxxx918327917",
            "status": 1
        },
        "message": "success",
        "localizedMsg": null
    }

获取物的属性timeline数据

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/device/property/timeline/get 1.0.0 获取物的属性timeline数据(最多可以获取设备一年内的数据)。
说明 调用/living/device/reset后,再调用该接口时不再获取到设备的历史数据。
是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符
identifier String 属性标识符
start Long timeline起始时间
end Long timeline终止时间
limit Int 最大查询条数,上限200
order String
  • asc:时间顺序
  • desc:时间逆序

返回参数

参数 类型 必有 描述
iotid String 设备标识符
data String 设备timeline数据
modifytime Long 属性更新时间
property String 属性标识符
batchId String 批次id,设备端同一批上报的属性具有相同的批次Id
timestamp Long 属性采集时间戳

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D24xxxxCCE4F31A2697",
            "identifier": "xxxx",
            "start": 1517217645000,
            "end": 1517217645000,
            "limit": 10,
            "order": "asc"
        }
    }     
  • 正常返回示例
    {
      "code": 200,
      "message": "success",
      "localizedMsg": null,
      "data": {
        "items": [
          {
            "iotid": "D95D24294xxxxxxxx4F31A2697",
            "data": "1.23",
            "modifytime": 1511812747287,
            "property": "Lixxxxt",
            "batchId": "2fc766cxxxxxxxxed1f3e4b61803",
            "timestamp": 1511812747245
          },
          {
            "iotid": "xqxyZjSKzxxxxxxxx010851c00",
            "data": 1.24,
            "modifytime": 1511812747288,
            "property": "Lxxxxlt",
            "batchId": "2fc766cxxxx1f3e4b61803",
            "timestamp": 1511812747245
          }
        ],
        "timestamp": 1511812747245
      }
    }   

获取物的事件timeline数据

定义描述

path 版本 描述 是否需要用户身份的鉴权
/living/device/event/timeline/get 1.0.0 获取物的事件timeline数据,最多可以获取设备一年内的数据 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符
identifier String 属性标识符
eventType String 事件类型
start Long timeline起始时间
end Long timeline终止时间
limit Int 最大查询条数,上限200
order Boolean
  • asc:时间顺序
  • desc:时间逆序

返回参数

参数 类型 必有 描述
eventCode String 事件标识符
iotId String 物的唯一标识符
eventName String 事件名称
eventType String 事件类型
eventBody String 事件参数
batchId String 批次id,设备同一批上报的事件具有相同的批次id
timestamp Long 时间采集时间

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D24xxxxE4F31A2697",
            "identifier": "xxxx",
            "eventType": "xxxx",
            "start": 1517217645000,
            "end": 1517217645000,
            "limit": 10,
            "order": "asc"
        }
    }      
  • 正常返回示例
    {
        "code": 200,
        "message": "success",
        "localizedMsg": "",
        "data": {
            "items": [
                {
                    "eventCode": "Error",
                    "iotId": "D95D24xxxxECCE4F31A2697",
                    "eventName": "故障上报",
                    "eventType": "info",
                    "eventBody": "{\"ErrorCode\": 0}",
                    "batchId": "5ebc6axxxx3edde6d28c8fb3",
                    "timestamp": 1516342985261
                },
                {
                    "eventCode": "Error",
                    "iotId": "YzqEnI5xxxxo0010840500",
                    "eventName": "故障上报",
                    "eventType": "info",
                    "eventBody": "{\"ErrorCode\": 0}",
                    "batchId": "4a0b5a7xxxxxxxx8d5ff77456f1",
                    "timestamp": 1516342995305
                }
            ],
            "timestamp": 1516343075699
        }
    }  

设置物的属性

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/properties/set 1.0.2 设置物的属性 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符
items JSON set参数

返回参数

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D242xxxxE4F31A2697",
            "items": {
                "LightSwitch1": 0,
                "LightSwitch2": 0
            }
        }
    }        
  • 正常返回示例
    {
      "code": 200,
      "data": null,
      "message": "success",
      "localizedMsg": ""
    }   

获取物的事件

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/events/get 1.0.2 获取物最新上报的事件,如果该事件未上报,则不会返回 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符

返回参数

参数 类型 必有 描述
identifier String 事件标识符
time Long 时间采集时间
type String 事件类型
value Object 事件出参

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D24xxxxCE4F31A2697"
        }
    }
  • 正常返回示例
    {
        "code": 200,
        "data": [
            {
                "identifier": "Error",
                "time": 1517420842314,
                "type": "info",
                "value": {
                    "Shrink5": 12,
                    "Shrink20": {
                        "testKey2": "val2",
                        "testKey": "val"
                    }
                }
            }
        ],
        "message": "success",
        "localizedMsg": null
    }

根据设备id获取物的模板

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/tsl/get 1.0.2 获取物的tsl功能模板(包含属性、事件、服务的定义) 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符

返回参数

参数 类型 必有 描述
data JSON String 物的模板json对象

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D2xxxxCE4F31A2697"
        }
    }       
  • 正常返回示例
    {
     "code": 200,
        "data": {
            "schema": "http://aliyun/iot/thing/desc/schema",
            "profile": {
                "productKey": "xxxxxxx",
                "deviceName": "xxxxxxxxxxxxxxxx"
            },
            "link": "/sys/a1xxxxpck/YzqEnxxxx2pjjo/thing/",
            "services": [
                {
                    "outputData": [
    
                    ],
                    "identifier": "ToggleLightSwitch",
                    "inputData": [
    
                    ],
                    "method": "thing.service.ToggleLightSwitch",
                    "name": "翻转主灯开关",
                    "required": false,
                    "callType": "async"
                }
            ],
            "properties": [
                {
                    "identifier": "LightSwitch",
                    "dataType": {
                        "specs": {
                            "0": "关闭",
                            "1": "开启"
                        },
                        "type": "bool"
                    },
                    "name": "主灯开关",
                    "accessMode": "rw",
                    "required": true
                }
            ],
            "events": [
                {
                    "outputData": [
                        {
                            "identifier": "ErrorCode",
                            "dataType": {
                                "specs": {
                                    "0": "正常"
                                },
                                "type": "enum"
                            },
                            "name": "故障代码"
                        }
                    ],
                    "identifier": "Error",
                    "method": "thing.event.Error.post",
                    "name": "故障上报",
                    "type": "info",
                    "required": true
                }
            ]
        },
        "message": "success",
        "localizedMsg": null
    }

根据产品key获取物的模板

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/tsl/getByProducyKey 1.0.2 获取物的tsl功能模板(包含属性、事件、服务的定义) 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
productKey String 产品Key
deviceName String deviceName

返回参数

参数 类型 必有 描述
data JSON String 物的模板json对象

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "ProductKey": "xxxxxxxx",
            "deviceName": "xxxxxxxx"
        }
    }      
  • 正常返回示例
    {
     "code": 200,
        "data": {
            "schema": "http://aliyun/iot/thing/desc/schema",
            "profile": {
                "productKey": "xxxxxxx",
                "deviceName": "xxxxxxxxxxxxxxxx"
            },
            "link": "/sys/a1xxxck/YzqEnxxxxpjjo/thing/",
            "services": [
                {
                    "outputData": [
    
                    ],
                    "identifier": "ToggleLightSwitch",
                    "inputData": [
    
                    ],
                    "method": "thing.service.ToggleLightSwitch",
                    "name": "翻转主灯开关",
                    "required": false,
                    "callType": "async"
                }
            ],
            "properties": [
                {
                    "identifier": "LightSwitch",
                    "dataType": {
                        "specs": {
                            "0": "关闭",
                            "1": "开启"
                        },
                        "type": "bool"
                    },
                    "name": "主灯开关",
                    "accessMode": "rw",
                    "required": true
                }
            ],
            "events": [
                {
                    "outputData": [
                        {
                            "identifier": "ErrorCode",
                            "dataType": {
                                "specs": {
                                    "0": "正常"
                                },
                                "type": "enum"
                            },
                            "name": "故障代码"
                        }
                    ],
                    "identifier": "Error",
                    "method": "thing.event.Error.post",
                    "name": "故障上报",
                    "type": "info",
                    "required": true
                }
            ]
        },
        "message": "success",
        "localizedMsg": null
    }

获取物的属性

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/properties/get 1.0.2 获取物的所有属性快照数据 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的标识符

返回参数

参数 子参数 类型 必有 描述
identifier 属性id
value Object 属性对应的数据
time Long 属性采集时间

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D24xxxxCE4F31A2697"
        }
    }
  • 正常返回示例
    {
      "code": 200,
      "data": {
        "_sys_device_mid": {
          "time": 1516356290173,
          "value": "example.demo.module-id"
        },
        "WorkMode": {
          "time": 1516347450295,
          "value": 0
        },
        "_sys_device_pid": {
          "time": 1516356290173,
          "value": "example.demo.partner-id"
        }
      },
      "message": "success",
      "localizedMsg": null
    }      

调用物的服务

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/service/invoke 1.0.2 调用物的服务 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的标识符
identifier String 服务标识符
args JSON String 服务入参

返回参数

参数 类型 必有 描述
data String 该返回值类型及值取决于设备端实现逻辑

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D2xxxxCE4F31A2697",
            "identifier": "xxxx",
            "args": {}
        }
    }             
  • 正常返回示例
    {
      "code": 200,
      "data": xxx,  //xxx为服务的实际返回值
      "message": "success",
      "localizedMsg": ""
    }     

获取物的连接状态

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/status/get 1.0.2 获取物的连接状态 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符

返回参数

参数 类型 必有 描述
status Integer 设备状态
  • 0:未激活
  • 1:在线
  • 3:离线
  • 8:禁用
time Long 状态变更时间

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D2xxxxCCE4F31A2697"
        }
    } 
  • 正常返回示例
    {
      "code": 200,
      "data": {
        "time": 1517923297000,
        "status": 3
      },
      "message": "success",
      "localizedMsg": null,
    }    

执行恢复出厂设置任务

定义描述

path 版本 描述 是否需要登录
/living/device/reset 1.0.0 恢复设备的出厂设置,并通知设备端,同时会清除云端设备快照数据;该接口调用会返回一个恢复出厂设置任务的id,任务后台异步执行,通过该任务id可查询任务的执行状态(配合“查询恢复出厂设置任务的执行状态”接口使用)
说明 调用该接口时,可删除设备历史数据。

请求参数

参数 类型 必填 描述
iotId String 设备的唯一标识

返回参数

参数 类型 描述
taskId String 执行恢复出厂设置任务的id

示例

  • 请求示例
    {
        "id":"xxx",   // 请求的 requestId
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"  // 接口的版本号
        },
        "params":{
            "iotId":"xxx"
        }
    }
  • 正常返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data":"taskId"
    }

查询恢复出厂设置任务的执行状态

定义描述

path 版本 描述 是否需要登录
/living/device/reset/task/state/get 1.0.0 查询恢复出厂设置任务的执行状态

请求参数

参数 类型 必填 描述
taskId String 执行恢复出厂设置任务的id

返回参数

参数 类型 描述
data String 任务的执行状态,可取值包括:SUCCESS、FAILED、TIMEOUT、RUNNING

示例

  • 请求示例
    {
        "id":"xxx",   // 请求的 requestId
        "version":"1.0.0",
        "request":{
            "language":"zh-CN",
            "appKey":"xxx",
            "iotToken":"xxx",
            "apiVer":"1.0.0"  // 接口的版本号
        },
        "params":{
            "taskId":"xxx"
        }
    }
  • 正常返回示例
    {
        "code":200,
        "message":"success",
        "localizedMsg":"",
        "data": "SUCCESS"
    }

设置设备扩展信息

单个设备的标签不能超过10个。

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/extended/property/set 1.0.2 设置物的扩展属性数据 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符
dataKey String 扩展属性标识符(小于64个字符)
dataValue String 扩展属性的值(小于128个字符)

返回参数

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D242xxxxxxxx4F31A2697",
            "dataKey": "xxxx",
            "dataValue": "xxxx"
        }
    } 
  • 正常返回示例
    {
      "code": 200,
      "message": "success",
      "localizedMsg": null,
      "data": null
    }        

获取设备扩展信息

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/extended/property/get 1.0.2 获取物的扩展属性的数据 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符
dataKey String 扩展属性标识符

返回参数

参数 类型 必有 描述
data String 扩展属性的值

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D2xxxxxxxxF31A2697",
            "dataKey": "xxxx"
        }
    }  
  • 正常返回示例
    {
      "code": 200,
      "message": "success",
      "localizedMsg": null,
      "data": "xxxx"
    }         

删除设备扩展信息

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/extended/property/delete 1.0.0 删除物的扩展属性数据 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
iotId String 物的唯一标识符
dataKey String 扩展属性标识符

返回参数

示例

  • 请求示例
    {
        "id": "1509086454181",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
            "iotToken": "token"
        },
        "params": {
            "iotId": "D95D24xxxx4F31A2698",
            "dataKey": "xxxx"
        }
    }      
  • 正常返回示例
    {
      "code": 200,
      "message": "success",
      "localizedMsg": null,
      "data": null
    }         

查询用户的小组件设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/iotx/ilop/queryComponentProduct 1.0.0 查询用户的小组件设备列表 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

返回参数

参数 类型 必有 描述
data JSON Array 小组件设备列表;单个设备数据结构请参考下文“小组件设备详情”表格

小组件设备详情

参数 类型 必有 描述
productKey string 产品pk
deviceName string 设备名称
iotId string 设备id
properties JSON Array 属性列表,详细结构参见下文表格
nickName string 别名
productName string 产品名称
iconUrl string 图片地址
deviceStatus int 设备状态

属性列表详情

参数 类型 必有 描述
propertyIdentifier string 属性id
propertyName string 属性名称
propertyValue string 属性取值
propertyDataType string 属性取值类型

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
            "iotToken": "token"
        },
        "params": {
        }
    }       
  • 正常返回示例
    {
      "code": 200,
      "message": "success",
      "localizedMsg": null,
      "data": [{
        "deviceName":"xxx",
        "deviceStatus":1,
        "iconUrl":"http://iotx-paas-admin.oss-cn-shanghai.aliyuncs.com/publish/image/xxxxxx.png",
        "iotId":"xxxxxx",
        "productKey":"xxx",
        "productName":"a",
        "properties":[{
          "propertyDataType":"bool",
          "propertyIdentifier":"PowerSwitch",
          "propertyName":"电源开关",
          "propertyValue":"1"}]
          },{
        "deviceName":"xxxx",
        "deviceStatus":1,
        "iconUrl":"http://iotx-paas-admin.oss-cn-shanghai.aliyuncs.com/publish/image/xxxxx.png",
        "iotId":"xxxx",
        "productKey":"xxx",
        "productName":"xxx",
        "properties":[{
          "propertyDataType":"bool",
          "propertyIdentifier":"LightSwitch",
          "propertyName":"主灯开关",
          "propertyValue":"0"
        }]
      }]
    }            

更新用户的小组件设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/iotx/ilop/updateComponentProduct 1.0.0 更新用户的小组件设备列表 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
data 数组 小组件设备列表

小组件设备详情

参数 类型 必有 描述
productKey string 产品productKey
iotId string 设备id
properties 数据 属性列表
属性列表详情
参数 类型 必有 描述
propertyIdentifier string 属性id

返回参数

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
            "iotToken": "token"
        },
        "params": {
          "componentProductList": [{
            "iotId":"xxxxxx",
            "productKey":"xxx"
          },{
            "iotId":"xxxxxx",
            "productKey":"xxx"
          }]
       }
    }
  • 正常返回示例
    {
      "code": 200,
      "message": "success",
      "localizedMsg": null,
      "data": null
    }    

查询用户小组件设备的属性列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/iotx/ilop/queryComponentProperty 1.0.0 查询用户小组件设备的属性列表 是,客户端SDK需启用身份的鉴权,进行身份认证

请求参数

参数 类型 必填 描述
productKey string 产品key
iotId string 设备id
query struct 查询条件

查询条件详情

参数 类型 必填 描述
dataType string 属性数据类型
I18Language string 多语言
languageList array 多语言列表
allLanguage bool 是否取全部多语言
replaceOrigin bool 是否替换默认语言

返回参数

参数 类型 必有 描述
propertyIdentifier string 属性id
propertyName string 属性名称
propertyValue string 属性取值
propertyDataType string 属性取值类型
added_component bool 是否添加至小组件中

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.0",
            "iotToken": "token"
        },
        "params": {
          "iotId":"xxxxxx",
          "productKey":"xxx",
          "query":{
            "dataType":"BOOL"
          }
        }
    }          
  • 正常返回示例
    {
      "code": 200,
      "message": "success",
      "localizedMsg": null,
      "data": [
        {"added_component":false,
         "dataType":"BOOL",
         "i18nDTO":{
           "i18nData":{"name":{"zh-CN":"电源开关"}}
         },
         "productKey":"xxxx",
         "propertyIdentifier":"PowerSwitch",
         "propertyName":"电源开关"}
      ]
    }