Tuya物联网平台数据格式与开发指南_云市场(Marketplace)-阿里云帮助中心

数据格式

消息类型与Topic对应关系

消息类型	topic	说明
设备上报消息	/${productKey}/${deviceName}/thing/event/property/post	设备属性上报
	/${productKey}/${deviceName}/thing/event/${identifier}/post	设备事件上报
	/${productKey}/${deviceName}/thing/event/property/history/post	设备历史属性上报
	/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/history/post	设备历史事件上报
	/${productKey}/${deviceName}/user/${TopicShortName}	设备自定义消息，您可以自定义TopicShortName的内容
设备状态变化通知	/as/mqtt/status/${productKey}/${deviceName}	设备上下线状态
设备生命周期变更	/${productKey}/${deviceName}/thing/lifecycle	设备创建、删除
拓扑关系变化	/${productKey}/${deviceName}/thing/topo/lifecycle	子设备和网关之间建立或者解除拓扑关系
网关子设备列表上报	/${productKey}/${deviceName}/thing/list/found	网关检测到子设备并上报
OTA 升级设备状态通知	/${productKey}/${deviceName}/ota/upgrade	设备OTA升级成功、失败或OTA任务被取消
OTA 升级设备状态通知	/${productKey}/${deviceName}/ota/progress/post	设备OTA升级进度
OTA 模块版本号上报	/${productKey}/${deviceName}/ota/version/post	设备OTA模块版本号变更
OTA 升级批次状态通知	/${productKey}/${packageId}/${jobId}/ota/job/status	OTA升级批次状态发生变更

设备上下线状态

Topic：/as/mqtt/status/${productKey}/${deviceName}

通过该Topic获取设备的上下线状态。

设备上线的数据格式：

{
    "status":"online",
    "iotId":"ca460d9993c9d1eae0adba****",
    "productKey":"k1nhvyl****",
    "deviceName":"deviceName1",
    "time":"2024-11-11 11:11:11.000",
    "utcTime":"2024-11-11T11:11:11.000Z"
}

设备下线的数据格式：

{
    "status":"offline",
    "iotId":"ca460d9993c9d1eae0adba****",
    "productKey":"k1nhvyl****",
    "deviceName":"deviceName1",
    "time":"2024-11-11 11:11:11.000",
    "utcTime":"2024-11-11T11:11:11.000Z"
}

参数说明：

参数	类型	说明
status	String	设备状态。 `online`：上线。 `offline`：离线。
iotId	String	设备在平台内的唯一标识。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
time	String	设备上、下线的时间。
utcTime	String	设备上、下线的UTC时间。

设备属性上报

Topic：/${productKey}/${deviceName}/thing/event/property/post

通过该Topic获取设备上报的属性信息。

数据格式：

{
    "iotId":"ca460d9993c9d1eae0adba****",
    "requestId":"1725523079827",
    "productKey":"k1nhvyl****",
    "deviceName":"deviceName1",
    "gmtCreate":1725523079827,
    "items":{
        "Power":{
            "value":"on",
            "time":1725523079827
        },
        "Position":{
            "time":1725523079827,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    }
}

参数说明：

参数	类型	说明
iotId	String	设备在平台内的唯一标识。
requestId	String	设备上报消息的原始数据中的Id，String类型的数字，取值范围为0~4294967295，且每个消息ID在当前设备中具有唯一性。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
gmtCreate	Long	数据流转消息产生时间。
items	Object	设备数据。

设备事件上报

Topic：/${productKey}/${deviceName}/thing/event/${identifier}/post

通过该Topic获取设备上报的事件信息。

数据格式：

{
    "identifier":"alarmType",
    "iotId":"ca460d9993c9d1eae0adba****",
    "productKey":"k1nhvyl****",
    "deviceName":"deviceName1",
    "gmtCreate":1725523079827,
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    },
    "time":1725523079827
}

参数说明：

参数	类型	说明
identifier	String	事件的标识符。
iotId	String	设备在平台内的唯一标识。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
gmtCreate	Long	数据流转消息产生时间。
value	Object	事件的输出参数信息。
time	Long	上报事件的时间，如果设备没有上报数据，默认采用物联网平台生成的时间。

设备属性批量上报

Topic：/${productKey}/${deviceName}/thing/property/batch/post

通过该Topic获取设备批量上报的属性信息。

数据格式：

{
  "deviceType": "ConversionGateway",
  "iotId": "6kQhYdOufZZNw8Amf5qx00****",
  "requestId": "123",
  "checkFailedData": {},
  "productKey": "a1fJ0Uw****",
  "gmtCreate": 1731045305431,
  "deviceName": "6kQhYdOufZZNw8Am****",
  "items": {
    "Power": [
      {
        "time": 1731042861000,
        "value": "on"
      },
      {
        "time": 1731042861001,
        "value": "off"
      }
    ],
    "WF": [
      {
        "time": 1731042861001,
        "value": 3
      },
      {
        "time": 1731042861000,
        "value": 4
      }
    ]
  }
}

参数说明：

参数	类型	说明
deviceType	String	设备所属品类。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
gmtCreate	Long	数据流转消息产生时间。
checkFailedData	Object	未通过物模型数据校验的数据。
requestId	String	设备上报消息的原始数据中的Id，String类型的数字，取值范围为0~4294967295，且每个消息ID在当前设备中具有唯一性。
items	Object	设备数据。

设备事件批量上报

Topic：/${productKey}/${deviceName}/thing/event/batch/post

通过该Topic获取设备批量上报的事件信息。

数据格式：

{
  "deviceType": "ConversionGateway",
  "iotId": "6kQhYdOufZZNw8Amf5qx00****",
  "requestId": "123",
  "checkFailedData": {},
  "productKey": "a1fJ0Uw****",
  "deviceName": "6kQhYdOufZZNw8Am****",
  "items": {
    "alarmEvent": [
      {
        "time": 1731042861004,
        "value": {
          "Power": "on",
          "WF": "2"
        }
      },
      {
        "time": 1731042861003,
        "value": {
          "Power": "on",
          "WF": "2"
        }
      }
    ]
  }
}

参数说明：

参数	类型	说明
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
requestId	String	设备上报消息的原始数据中的Id，String类型的数字，取值范围为0~4294967295，且每个消息ID在当前设备中具有唯一性。
items	Object	设备数据。

设备生命周期变更

Topic：/${productKey}/${deviceName}/thing/lifecycle

通过该Topic获得设备创建、删除等消息。

数据格式：

{
    "action": "create|delete",
    "iotId": "ca460d9993c9d1eae0adba****",
    "productKey": "a1fJ0Uw****",
    "deviceName": "6kQhYdOufZZNw8Am****",
    "deviceSecret": "6ece9900582e7cd3b6c223ef39fe****", 
    "messageCreateTime": 1722417817066 
}

参数说明：

参数	类型	说明
action	String	`create`：创建设备。 `delete`：删除设备。
iotId	String	设备在平台内的唯一标识。
productKey	String	产品的唯一标识。
deviceName	String	设备名称。
deviceSecret	String	设备密钥，仅在action为`create`时包含。
messageCreateTime	Integer	消息产生时间戳，单位为毫秒。

设备拓扑关系变更

Topic：/${productKey}/${deviceName}/thing/topo/lifecycle

通过该Topic获得子设备和网关之间拓扑关系建立和解除信息。

数据格式：

{
    "action" : "create|delete",
    "gwIotId": "ca460d9993c9d1eae0adba****",
    "gwProductKey": "k1nhvyl****",
    "gwDeviceName": "deviceName1",
    "devices": [
        {
            "iotId": "ca460d999273ca35aea2ectonv****",
            "productKey": "a1ufOYo****",
            "deviceName": "deviceName2"
        }
    ],
    "messageCreateTime": 1510292739881
}

参数说明：

参数	类型	说明
action	String	`create`：新增拓扑关系。 `delete`：移除拓扑关系。
gwIotId	String	网关设备在平台内的唯一标识。
gwProductKey	String	网关产品的唯一标识。
gwDeviceName	String	网关设备名称。
devices	Object	变更的子设备列表。
iotId	String	子设备在平台内的唯一标识。
productKey	String	子设备产品的唯一标识。
deviceName	String	子设备名称。
messageCreateTime	Integer	消息产生时间戳，单位毫秒。

网关发现子设备

Topic：/${productKey}/${deviceName}/thing/list/found

在一些场景中网关能够检测到子设备，并将检测到的子设备信息上报。此时可以通过该Topic获取到上报的信息。

数据格式：

{
    "gwIotId":"ca460d9993c9d1eae0adba****",
    "gwProductKey":"k1nhvyl****",
    "gwDeviceName":"deviceName1",
    "devices":[
        {
            "iotId":"ca460d999273ca35aea2ectonv****",
            "productKey":"a1ufOYo****",
            "deviceName":"deviceName2"
        }
    ]
}

参数说明：

参数	类型	说明
gwIotId	String	网关设备在平台内的唯一标识。
gwProductKey	String	网关产品的唯一标识。
gwDeviceName	String	网关设备名称。
devices	Object	发现的子设备列表。
iotId	String	子设备在平台内的唯一标识。
productKey	String	子设备所属产品的唯一标识。
deviceName	String	子设备名称。

历史属性上报

Topic：/${productKey}/${deviceName}/thing/event/property/history/post

通过该Topic获取设备上报的物模型历史属性数据。

数据格式：

{
  "deviceType": "ConversionGateway",
  "iotId": "6kQhYdOufZZNw8Amf5qx00****",
  "requestId": "123",
  "productKey": "a1fJ0Uw****",
  "gmtCreate": 1731068522099,
  "deviceName": "6kQhYdOufZZNw8Am****",
  "items": {
    "Power": {
      "time": 1731065948000,
      "value": "on"
    },
    "WF": {
      "time": 1731065948000,
      "value": 6
    }
  }
}

参数说明：

参数	类型	说明
iotId	String	设备在平台内的唯一标识。
requestId	String	设备上报消息的原始数据中的Id，String类型的数字，取值范围为0~4294967295，且每个消息ID在当前设备中具有唯一性。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
gmtCreate	Long	数据流转消息产生时间。
deviceType	String	设备所属品类。
items	Object	设备数据。

历史事件上报

Topic：/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/history/post

通过该Topic获取设备上报的历史事件数据。

数据格式：

{
  "deviceType": "ConversionGateway",
  "identifier": "alertEvent2",
  "iotId": "6kQhYdOufZZNw8Amf5qx00****",
  "requestId": "123",
  "name": "alertEvent2",
  "time": 1731065948004,
  "type": "info",
  "productKey": "a1fJ0Uw****",
  "deviceName": "6kQhYdOufZZNw8Am****",
  "value": {
    "param1": "off0ff",
    "param2": "33"
  }
}

参数说明：

参数	类型	说明
identifier	String	事件的标识符。
name	String	事件的名称。
type	String	事件类型
iotId	String	设备在平台内的唯一标识。
requestId	String	设备上报消息的原始数据中的Id，String类型的数字，取值范围为0~4294967295，且每个消息ID在当前设备中具有唯一性。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
gmtCreate	Long	数据流转消息产生时间。
value	Object	事件的输出参数信息。
time	Long	上报事件的时间，如果设备没有上报数据，默认采用物联网平台生成的时间。

OTA升级状态通知

Topic：/${productKey}/${deviceName}/ota/upgrade

通过该Topic获得OTA升级状态消息，即设备OTA升级成功或失败的消息。

说明

如果设备有未完成的升级任务，又对该设备发起批量升级任务，后发起的升级任务将升级失败。这种情况下，物联网平台不流转升级失败消息。

数据格式：

{
    "iotId": "9eaa10e9691875416b****",
    "productKey": "k1h9drZ****",
    "deviceName": "device_actived",
    "moduleName": "ble",
    "status": "SUCCEEDED|FAILED|CANCELED",
    "messageCreateTime": 1725525306479,
    "srcVersion": "1.0",
    "destVersion": "2.8",
    "jobId": "183161168857137****",
    "taskId": "183161168895724****"
}

参数说明：

参数	类型	说明
iotId	String	设备ID，设备的唯一标识符。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
moduleName	String	OTA模块名称。
status	String	升级状态。 `SUCCEEDED`：升级成功。 `FAILED`：升级失败。 `CANCELED`：升级已取消。
messageCreateTime	Long	消息产生时间戳，单位毫秒。
srcVersion	String	升级前的版本。
destVersion	String	升级目标版本。
desc	String	升级状态描述信息。
jobId	String	升级批次ID，升级批次的唯一标识符。
taskId	String	设备升级记录的唯一标识符。

OTA升级进度通知

Topic：/${productKey}/${deviceName}/ota/progress/post

通过该Topic获得OTA升级中进度消息。

数据格式：

{
    "deviceName": "otaTestDev****",
    "iotId": "9e870c6e9e59367232****",
    "jobId": "181858248689804****",
    "messageCreateTime": 1722418842125,
    "moduleName": "ble",
    "productKey": "KbOFk5oLgvpb****",
    "srcVersion": "1.0",
    "step": 50,
    "taskId": "181858248704904****"
}

参数说明：

参数	类型	说明
iotId	String	设备ID，设备的唯一标识符。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
moduleName	String	OTA模块名称。
status	String	升级状态。此处取固定值：`IN_PROGRESS`（升级中）。
step	Integer	设备上报的升级进度。
messageCreateTime	Long	消息产生时间戳，单位毫秒。
srcVersion	String	升级前的版本。
destVersion	String	升级目标版本。
desc	String	升级状态描述信息。
jobId	String	升级批次ID，升级批次的唯一标识符。
taskId	String	设备升级记录的唯一标识符。

OTA模块版本号变更通知

Topic：/${productKey}/${deviceName}/ota/version/post

通过该Topic获得设备上报的OTA模块版本号。当设备上报OTA模块版本号，且版本号有变更时进行转发。

数据格式：

{
    "iotId": "9eaa10e9691875416b****",
    "productKey": "k1h9drZ****",
    "deviceName": "device_actived",
    "moduleName": "ble",
    "moduleVersion": "1.1",
    "messageCreateTime": 1725524474082
}

参数说明：

参数	类型	说明
iotId	String	设备ID，设备的唯一标识符。
productKey	String	设备所属产品的唯一标识。
deviceName	String	设备名称。
moduleName	String	模块名称。
moduleVersion	String	模块版本号。
messageCreateTime	Long	消息产生时间戳，单位毫秒。

OTA升级批次状态通知

Topic：/${productKey}/${packageId}/${jobId}/ota/job/status

通过该Topic获得OTA升级批次状态变更消息。

数据格式：

{
    "productKey": "k1h9drZ****",
    "moduleName": "ble",
    "packageId": "126",
    "jobId": "183161558370477****",
    "state": "COMPLETED",
    "messageCreateTime": 1725526274603
}

参数说明：

参数	类型	说明
productKey	String	设备所属产品的唯一标识。
moduleName	String	模块名称。
packageId	String	升级包ID。是使用CreateOTAFirmware创建升级包时，返回的FirmwareId参数。
jobId	String	升级批次ID，升级批次的唯一标识符。
state	String	升级批次状态，取值： `PLANNED`：未开始升级。 `IN_PROGRESS`：升级中。 `COMPLETED`：升级完毕。 `CANCELED`：已取消。 `UNFINISH`：未完成。
messageCreateTime	Long	消息产生时间戳，单位毫秒。