提供一组与物（即物联网中的设备）相关的服务接口，云端应用通过本组服务可以实现物信息的查询和控制，查询的内容包含物的基本信息及属性模版等。

获取物的属性

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/properties/get 1.0.2 获取物的所有属性快照数据 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey和deviceName为空时，该入参不允许为空
productKey String 否（特定条件下必填） 产品唯一标识符，当iotId为空时，该入参不允许为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该入参不允许为空

返回参数

参数 子参数 类型 描述
data Array 数据列表
attribute String 属性名称
batchId String 设备属性批量上报的批次
gmtModified Date 设备属性采集时间
iotId String 设备唯一值
value Object 属性值

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D242xxxx4F31A2697"
    }
}
  • 正常返回示例 
    {
    "code":200,
    "data":[
        {
            "attribute":"AppointmentTime",
            "batchId":"992751fxxxx5b00dac8f4f",
            "gmtModified":1566026333540,
            "iotId":"D95D2xxxxE4F31A2697",
            "value":0
        },
        {
            "attribute":"CO2",
            "batchId":"5729c1c31c6xxxx25fa3b8e",
            "gmtModified":156xxxx430,
            "iotId":"D95D24xxxxF31A2697",
            "value":825
        }
    ],
    "message":"success"
}

获取物的模板

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/tsl/get 1.0.2 获取物的tsl功能（包含属性、事件、服务的定义）模板 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey和deviceName为空时，该入参不允许为空
productKey String 否（特定条件下必填） 产品唯一标识符，当iotId为空时，该入参不允许为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该入参不允许为空

返回参数

无

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D2xxxx4F31A2697"
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": {
        "schema": "http://aliyun/iot/thing/desc/schema",
        "profile": {
            "productKey": "xxxxxxx",
            "deviceName": "xxxxxxxxxxxxxxxx"
        },
        "link": "/sys/a1xxxxpck/YzqExxxxjjo/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",
}

触发物的服务

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/service/invoke 1.0.2 触发物的服务 是

请求参数

参数 类型 必填 描述
iotId String 否 物的唯一标识符，该参数不为空时，优先使用该参数
productKey String 是 产品唯一标识符，该入参不允许为空
deviceName String 是 设备名称，该入参不允许为空
identifier String 是 服务标识符
args JSON 是 服务入参

返回参数

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

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D2429xxxx4F31A2697",
        "identifier": "xxxx",
        "args": {}
    }
}
  • 正常返回示例 
    {
  "code": 200,
  "data": null,
  "message": "success",
  "localizedMsg": ""
}

设置物的属性

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/properties/set 1.0.2 设置物的属性 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey和deviceName为空时，该入参不允许为空
productKey String 否（特定条件下必填） 产品唯一标识符，当iotId为空时，该入参不允许为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该入参不允许为空
items JSON 是 set参数

返回参数

无

示例

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

获取物的连接状态

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/status/get 1.0.2 获取物的连接状态 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey和deviceName为空时，该入参不允许为空
productKey String 否（特定条件下必填） 产品唯一标识符，当iotId为空时，该入参不允许为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该入参不允许为空

返回参数

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

示例

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

获取物的基本信息

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/info/get 1.0.2 获取物的基本信息 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey和deviceName为空时，该入参不允许为空
productKey String 否（特定条件下必填） 产品唯一标识符，当iotId为空时，该入参不允许为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该入参不允许为空

返回参数

参数 类型 描述
gmtModified Long 数据修改时间
activeTime Long 设备激活时间
gmtCreate Long 设备创建时间
productKey String 产品唯一标识符
statusLast Integer 上一次设备状态
mac String MAC地址
deviceSecret String 设备的deviceSecret
iotId String 设备唯一标识符
name String 设备名称
nickname String 设备昵称
sdkVersion String SDK版本
sn String 设备SN
thingType String 设备类型
region String 区域
firmwareVersion String 固件版本号
rbacTenantId String 租户id
status Integer 设备状态

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D24xxxxE4F31A2697"
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": {
        "gmtModified": 1517918765000,
        "activeTime": null,
        "deviceKey": "Kq7rgxxxxexwJh",
        "gmtCreate": 1500017648000,
        "productKey": "kQxxxxqA",
        "statusLast": null,
        "mac": null,
        "netAddress": null,
        "deviceSecret": "xxxxxxxxxxxxxxxxxxxxx",
        "iotId": "03iGXYVlxxxx9ccwgzHG",
        "name": "Kq7rgvxxxxexwJh",
        "tenantId": 7,
        "nickname": null,
        "sdkVersion": null,
        "sn": null,
        "thingType": "DEVICE",
        "region": "daily",
        "firmwareVersion": "1.0.0",
        "rbacTenantId": "ADSBCUYxxxx8327917",
        "ownerDomain": "kQxxxxqA",
        "status": 1
    },
    "message": "success",
    "localizedMsg": null
}

批量获取物

定义描述

path 版本 描述 是否需要cloudToken
/cloud/things/get 1.0.2 批量获取物 是

请求参数

参数 类型 必填 描述
productKey String 是 物的产品唯一标识符
status Int 是 设备状态
  • 0：未激活
  • 1：在线
  • 3：离线
  • 8：禁用
currentPage Int 是 分页查询
pageSize Int 是 分页大小

返回参数

参数 类型 必有 描述
totalNum Long 是 总记录数
items List 否 设备列表，列表中参数与获取物的基本信息的返回参数一致

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "productKey": "xxxxxxxxxxxxx",
        "status": 3,
        "currentPage": 1,
        "pageSize": 2
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "data": [
        {
            "gmtModified": 1517922329000,
            "offset": null,
            "activeTime": null,
            "deviceKey": "d7Clxxxxu1Lp",
            "gmtCreate": 1501110001000,
            "productKey": "wxxxxtR",
            "statusLast": null,
            "mac": null,
            "netAddress": null,
            "iotId": "d7CllTxxx0010990700",
            "deviceSecret": "u98xxxxzhy/4cV1ThAEGxxxxf48Cf6YX+sqcP1Ky7",
            "name": "\r\n",
            "tenantId": 7,
            "nickname": null,
            "limit": null,
            "sdkVersion": null,
            "sn": null,
            "thingType": "DEVICE",
            "region": "daily",
            "firmwareVersion": null,
            "rbacTenantId": "ADSBCxxxx327917",
            "ownerDomain": "wLxxxxtR",
            "status": 1
        },
        {
            "gmtModified": 1517922329000,
            "offset": null,
            "activeTime": null,
            "deviceKey": "K1XuExxxxWgiQaq",
            "gmtCreate": 1501123511000,
            "productKey": "wxxxR",
            "statusLast": null,
            "mac": null,
            "netAddress": null,
            "iotId": "K1XuEDskxxxxxxxxq0010d93300",
            "deviceSecret": "bZxxxj/hZs27AJsNKg3xxxxxxxxxxxxjqcP1Ky7",
            "name": "K1XuxxxxgiQaq",
            "tenantId": 7,
            "nickname": null,
            "limit": null,
            "sdkVersion": null,
            "sn": null,
            "thingType": "DEVICE",
            "region": "daily",
            "firmwareVersion": null,
            "rbacTenantId": "ADSBCUYxxxx27918327917",
            "ownerDomain": "wLxxxxtR",
            "status": 1
        }
    ],
    "message": "success",
    "localizedMsg": null
}

获取物的事件timeline数据

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/event/timeline/get 1.0.2 获取物的事件timeline数据，最多可以获取设备一年内的数据 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey和deviceName为空时，该入参不允许为空
productKey String 否（特定条件下必填） 产品唯一标识符，当iotId为空时，该入参不允许为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该入参不允许为空
identifier String 是 属性标识符
eventType String 是 事件类型
start Long 是 timeline起始时间
end Long 是 timeline终止时间
pageSize Int 是 分页查询条数
ordered Boolean 是 查询方式
  • true：顺序
  • false：逆序

返回参数

参数 类型 描述
eventCode String 事件标识符
iotId String 物的唯一标识符
eventName String 事件名称
eventType String 事件类型
eventBody Object 事件参数
batchId String 批次id
timestamp Long 时间采集时间

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D242941xxxxCCE4F31A2697",
        "identifier": "xxxx",
        "eventType": "xxxx",
        "start": 1517217645000,
        "end": 1517217645000,
        "pageSize": 10,
        "ordered": true
    }
}
  • 正常返回示例 
    {
    "code": 200,
    "message": "success",
    "localizedMsg": "",
    "data": {
        "items": [
            {
                "eventCode": "Error",
                "iotId": "YzqEnI5Dxxxxjjo0010840500",
                "eventName": "故障上报",
                "eventType": "info",
                "eventBody": {
                    "ErrorCode": 0
                },
                "batchId": "5ebc6a9c7dxxxxedde6d28c8fb3",
                "timestamp": 1516342985261
            },
            {
                "eventCode": "Error",
                "iotId": "YzqEnI5Dxxxxxxxxjo0010840500",
                "eventName": "故障上报",
                "eventType": "info",
                "eventBody": {
                    "ErrorCode": 0
                },
                "batchId": "4a0b5a7ac8xxxxd5ff77456f1",
                "timestamp": 1516342995305
            }
        ],
        "timestamp": 1516343075699
    }
}

获取物的属性timeline数据

定义描述

path 版本 描述 是否需要cloudToken
/cloud/thing/property/timeline/get 1.0.2 获取物的属性timeline数据，最多可以获取设备一年内的数据 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey和deviceName为空时，该入参不允许为空
productKey String 否（特定条件下必填） 产品唯一标识符，当iotId为空时，该入参不允许为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该入参不允许为空
identifier String 是 属性标识符
start Long 是 timeline起始时间
end Long 是 timeline终止时间
pageSize Int 是 分页查询条数（最大200）
ordered Boolean 是 查询方式
  • true：顺序
  • false：逆序

返回参数

参数 类型 描述
iotid String 设备标识符
data Object 设备timeline数据
modifytime Long 属性更新时间
property String 属性标识符
batchId String 批次id
timestamp Long 属性采集时间戳

示例

  • 请求示例 
    {
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "cloudToken": "token"
    },
    "params": {
        "iotId": "D95D24294xxxx1ECCE4F31A2697",
        "identifier": "xxxx",
        "start": 1517217645000,
        "end": 1517217645000,
        "pageSize": 10,
        "ordered": true
    }
}
  • 正常返回示例 
    {
  "code": 200,
  "message": "success",
  "localizedMsg": null,
  "data": {
    "items": [
      {
        "iotid": "xqxyZjSKzCxxxxvbv0O0010851c00",
        "data": 1.23,
        "modifytime": 1511812747287,
        "property": "LightVolt",
        "batchId": "2fc766c5e7xxxx3ed1f3e4b61803",
        "group": null,
        "timestamp": 1511812747245
      },
      {
        "iotid": "xqxyZjSKzxxxx0O0010851c00",
        "data": 1.24,
        "modifytime": 1511812747288,
        "property": "LightVolt",
        "batchId": "2fc766c5exxxx3ed1f3e4b61803",
        "group": null,
        "timestamp": 1511812747245
      }
    ],
    "timestamp": 1511812747245
  }
}

查询网关的子设备列表

定义描述

path 版本 描述 是否需要cloudToken
/living/cloud/device/subdevice/query 1.0.0 提供根据网关设备ID分页查询子设备列表的能力 是

请求参数

参数 类型 必填 描述
iotId String 否（特定条件下必填） 物的唯一标识符，当productKey或deviceName为空时，该入参不能为空
productKey String 否（特定条件下必填） 产品的Key，当iotId为空时，该参数不能为空
deviceName String 否（特定条件下必填） 设备名称，当iotId为空时，该参数不能为空
pageNo Int 是 分页查询的页码
pageSize Int 是 分页查询的每页大小，最大为20

返回参数

参数 一级子参数 二级子参数 类型 描述
data 网关的子设备列表
total Long 子设备总数
pageNo Int 当前页号，从1开始的页序号
pageSize Int 页大小
items JSON Array 设备证书列表
iotId String 设备ID
deviceName String 设备名称
productKey String 设备的productKey
thingType String 设备的类型：
  • VIRTUAL
  • WEB
  • APP
  • DEVICE
firmwareVersion String 固件版本号，需要设备端上报（如果未上报过，则不会返回该值）
sdkVersion String SDK版本号
status Int 设备状态
  • 0：未激活
  • 1：在线
  • 3：离线
  • 8：禁用
nodeType String 设备节点类型：
  • DEVICE
  • GATEWAY
region String 设备所属的站点
rbacTenantId String 设备所属的租户id
gmtCreate Long 记录创建时间，1970年01月01日起至现在的总毫秒数
gmtModified Long 记录修改时间，1970年01月01日起至现在的总毫秒数

示例

  • 请求示例 
    {
    "id": "15090xxxx4180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.0",
        "cloudToken": "tokenxxxxxxxx"
    },
    "params": {
      "iotId":"CHWlsAQxxxxxMy4zs000101",
      "pageNo":1,
      "pageSize":10
    }
}
  • 正常返回示例 
    {
    "code":200,
    "data":{
        "total":1,
        "pageNo":1,
        "pageSize":10,
        "items":[
            {
                "iotId":"c2NBjWQUxxxxxxxxTPFu8000101",
                "gmtModified":15789xxxx6000,
                "thingType":"DEVICE",
                "productKey":"a1HxxxxRiox",
                "region":"cn-hangzhou",
                "gmtCreate":15789xxxx6000,
                "deviceName":"tesxxxxv0",
                "rbacTenantId":"380D6988CxxxxxxxxxD9CBBDAC071",
                "status":0
            }
        ]
    },
    "id":"3f757e2b-xxxx-xxxx-9926-b435bfe4bb6e"
}