物联网平台的云产品流转和服务端订阅,是基于Topic中的数据格式来处理和传递数据的。Topic可分为自定义Topic、基础通信Topic和物模型Topic,其中自定义Topic中的数据格式由您定义。本文介绍基础通信Topic和物模型通信Topic中的数据格式。

设备上下线状态

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

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

设备上线的数据格式:

{
    "status":"online",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"al12345****",
    "deviceName":"deviceName1234",
    "time":"2018-08-31 15:32:28.205",
    "utcTime":"2018-08-31T07:32:28.205Z",
    "lastTime":"2018-08-31 15:32:28.195",
    "utcLastTime":"2018-08-31T07:32:28.195Z",
    "clientIp":"192.0.2.1"
}

设备下线的数据格式:

{
    "status":"offline",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "offlineReasonCode":427,
    "productKey":"al12345****",
    "deviceName":"deviceName1234",
    "time":"2018-08-31 15:32:28.205",
    "utcTime":"2018-08-31T07:32:28.205Z",
    "lastTime":"2018-08-31 15:32:28.195",
    "utcLastTime":"2018-08-31T07:32:28.195Z",
    "clientIp":"192.0.2.1"
}

参数说明:

参数 类型 说明
status String 设备状态。
  • online:上线
  • offline:离线
iotId String 设备在平台内的唯一标识。
offlineReasonCode Integer 设备下线时,返回的错误码。详细说明,请参见设备行为错误码
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
time String 发送通知的时间点。
utcTime String 发送通知的UTC时间点。
lastTime String 设备状态变更前最后一次通信的时间。

收到消息的时间不是实际设备上下线时间。设备上下线时间,请按照lastTime判断。

例如,您依次收到3条消息:
  1. 上线:2018-08-31 10:02:28.195
  2. 下线:2018-08-31 10:01:28.195
  3. 下线:2018-08-31 10:03:28.195
这3条消息展示了,设备先下线,再上线,最后下线的过程。
utcLastTime String 状态变更前最后一次通信的UTC时间。
clientIp String 设备公网出口IP。

设备属性上报

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

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

数据格式:

{
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"al12345****",
    "deviceName":"deviceName1234",
    "gmtCreate":1510799670074,
    "deviceType":"Ammeter",
    "items":{
        "Power":{
            "value":"on",
            "time":1510799670074
        },
        "Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    },
    "checkFailedData":{
        "attribute_8":{
            "time": 1510292697470,
            "value": 715665571,
            "code":6304,
            "message":"tsl parse: params not exist -> attribute_8"
        }
    }
}

参数说明:

参数 类型 说明
iotId String 设备在平台内的唯一标识。
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
gmtCreate Long 数据流转消息产生时间。
deviceType String 设备类型。
items Object 设备数据。
Power String 属性标识符。产品所具有的属性名称请参见产品的TSL描述。
如果是自定义模块属性,属性标识符格式为模块标识符:属性标识符(中间为英文冒号)。例如,物模型自定义模块标识符为test,数据格式为:
"items":{
        "test:Power":{
            "value":"on",
            "time":1510799670074
        },
        "test:Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    }
Position
attribute_8
checkFailedData Object 未通过物模型数据校验的数据。
value 根据TSL定义 属性值。
time Long 属性产生时间,如果设备没有上报数据,默认采用在云端生成的时间。
code Integer 数据未通过物模型数据校验时,返回的错误码。详细说明,请参见设备端接收的错误码
message String 数据未通过物模型数据校验时,返回的错误码信息,包含错误原因和具体的错误参数。

设备事件上报

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

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

数据格式:

{
    "identifier":"BrokenInfo",
    "name":"损坏率上报",
    "type":"info",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"X5eCzh6****",
    "deviceName":"5gJtxDVeGAkaEztpisjX",
    "gmtCreate":1510799670074,
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    },
    "checkFailedData":{
        "value": {
            "type": "onMapTrace",
            "content": "{\"tid\":\"1313701472\",\"totalCount\":2267,\"traceStart\":2266,\"pointCount\":1,\"traceValue\":\"XQAABAAFAAAAAB0AE6UAB/oAAA==\"}",
            "timestamp": "15970451390162"
        },
        "code":6304,
        "message":"tsl parse: params not exist -> type"
    },
    "time":1510799670074
}

参数说明:

参数 类型 说明
identifier String 事件的标识符。
如果是自定义模块事件,事件标识符格式为模块标识符:事件标识符(中间为英文冒号)。例如,物模型自定义模块标识符为test,数据格式为:
"test:identifier":"BrokenInfo",
name String 事件的名称。
type String 事件类型,事件类型参见产品的TSL描述。
iotId String 设备在平台内的唯一标识。
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
gmtCreate Long 数据流转消息产生时间。
value Object 事件的参数。
Power String 事件参数名称。
Position String 事件参数名称。
checkFailedData Object 未通过物模型数据校验的数据。
content String 设备上报的未通过物模型数据校验的数据。
timestamp Long 设备上报的时间戳。
code Integer 数据未通过物模型数据校验时,返回的错误码。详细说明,请参见设备端接收的错误码
message String 数据未通过物模型数据校验时,返回的错误码信息,包含错误原因和具体的错误参数。
time Long 事件产生时间,如果设备没有上报数据,默认采用云端生成的时间。

设备属性批量上报

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

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

数据格式:

{
    "productKey": "al12345****",
    "deviceName": "deviceName1234",
    "instanceId": "iot-0***",
    "requestId": "57b144cf-***",
    "payload": {
        "Power": [{
                "value": "on",
                "time": 1524448722000
            },
            {
                "value": "off",
                "time": 1524448722001
            }
        ],
        "WF": [{
                "value": 3,
                "time": 1524448722000
            },
            {
                "value": 4,
                "time": 1524448722009
            }
        ]
    }
}

参数说明:

参数 类型 说明
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
instanceId String 设备所属实例的实例ID。
requestId String 阿里云为该请求生成的唯一标识符。
payload Object 设备数据。
Power String 属性标识符。产品所具有的属性名称请参见产品的TSL描述。
如果是自定义模块属性,属性标识符格式为模块标识符:属性标识符(中间为英文冒号)。例如,物模型自定义模块标识符为test,数据格式为:
"payload":{
        "test:Power":[
            {
            "value":"on",
            "time":1510799670074
            },
            {
              "value": "off", 
              "time": 1524448722001
            }],
        "test:WF":[
            {
              "value": 3, 
              "time": 1524448722000
            },
            {
              "value": 4, 
              "time": 1524448722009
            }]
        }
    }
WF
value 根据TSL定义 属性值。
time Long 属性产生时间,如果设备没有上报数据,默认采用在云端生成的时间。

设备事件批量上报

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

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

数据格式:

{
    "productKey": "al12345****",
    "deviceName": "deviceName1234",
    "instanceId": "iot-0***",
    "requestId": "57b144cf-***",
    "payload": {
        "alarmEvent": [{
                "value": {
                    "Power": "on",
                    "WF": "2"
                },
                "time": 1524448722000
            },
            {
                "value": {
                    "Power": "on",
                    "WF": "2"
                },
                "time": 1524448723000
            }
        ]
    }
}

参数说明:

参数 类型 说明
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
instanceId String 设备所属实例的实例ID。
requestId String 阿里云为该请求生成的唯一标识符。
payload Object 设备数据。
alarmEvent List 事件的标识符。
value Object 事件的参数。

以上示例中,PowerWF是事件的参数名称。

time Long 事件产生时间,如果设备没有上报数据,默认采用云端生成的时间。

设备生命周期变更

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

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

数据格式:

{
    "action" : "create|delete|enable|disable",
    "iotId" : "4z819VQHk6VSLmmBJfrf00107e****",
    "productKey" : "al5eCzh****",
    "deviceName" : "5gJtxDVeGAkaEztpisjX",
    "deviceSecret" : "", 
    "messageCreateTime": 1510292739881 
}

参数说明:

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

设备拓扑关系变更

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

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

数据格式:

{
    "action" : "create|delete|enable|disable",
    "gwIotId": "dfaejVQHk6VSLmmBJfrf00107e****",
    "gwProductKey": "al5eCzh****",
    "gwDeviceName": "deviceName1234",
    "devices": [ 
        {
          "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
          "productKey": "ala4Czh****",
          "deviceName": "deviceName1234"
       }
    ],

    "messageCreateTime": 1510292739881 
}

参数说明:

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

网关发现子设备

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

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

数据格式:

{
    "gwIotId":"dfaew9VQHk6VSLmmBJfrf00107e****",
    "gwProductKey":"al12345****",
    "gwDeviceName":"deviceName1234",
    "devices":[
        {
            "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
            "productKey":"alr56g9****",
            "deviceName":"deviceName1234"
        }
    ]
}

参数说明:

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

设备下行指令结果

Topic:/${productKey}/${deviceName}/thing/downlink/reply/message

通过该Topic可以获取,通过异步方式下发属性设置和服务调用指令给设备,设备进行处理后返回的结果信息。如果下发指令过程中出现错误,也可以通过该Topic得到指令下发的错误信息。

数据格式:

{
    "gmtCreate":1510292739881,
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"al12355****",
    "deviceName":"deviceName1234",
    "requestId":1234,
    "code":200,
    "message":"success",
    "topic":"/sys/al12355****/deviceName1234/thing/service/property/set",
    "data":{

    },
    "checkFailedData":{
        "value": {
            "PicID": "15194139"
        },
        "code":6304,
        "message":"tsl parse: params not exist -> PicID"
    }
}

参数说明:

参数 类型 说明
gmtCreate Long UTC时间戳。
iotId String 设备在平台内的唯一标识。
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
requestId Long 阿里云为该下行指令生成的唯一标识符。
code Integer 设备回复的结果状态码,说明参见下表表 1
message String 设备回复的结果状态码信息。
topic String 下发指令给设备的Topic信息。
data Object 设备返回的结果。Alink格式数据直接返回设备处理结果,透传格式数据则需要经过脚本转换。
checkFailedData Object 未通过物模型数据校验的数据。
value 根据TSL定义 未通过物模型数据校验的属性值、服务参数值。

以上示例中,PicID是未通过检验的参数名称。

code Integer 数据未通过物模型数据校验时,返回的错误码。详细说明,请参见设备端接收的错误码
message String 数据未通过物模型数据校验时,返回的错误码信息,包含错误原因和具体的错误参数。
表 1. 结果状态码
code message 说明
200 success 请求成功。
400 request error 内部服务错误,处理时发生内部错误。
460 request parameter error 请求参数错误,设备入参校验失败。
429 too many requests 请求过于频繁。
9200 device not actived 设备没有激活。
9201 device offline 设备不在线。
403 request forbidden 由于欠费导致请求被禁止。

错误码相应解决办法,请参见设备端接收的错误码

历史属性上报

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

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

数据格式:

{
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"12345****",
    "deviceName":"deviceName1234",
    "gmtCreate":1510799670074,
    "deviceType":"Ammeter",
    "items":{
        "Power":{
            "value":"on",
            "time":1510799670074
        },
        "Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    },
    "checkFailedData":{
        "attribute_8":{
            "time": 1510292697470,
            "value": 715665571,
            "code":6304,
            "message":"tsl parse: params not exist -> attribute_8"
        }
    }
}

参数说明:

参数 类型 说明
iotId String 设备在平台内的唯一标识。
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
gmtCreate Long 数据流转消息产生时间。
deviceType String 物模型类型,详情参见产品的TSL描述。
items Object 设备数据。
Power String 属性标识符。产品所具有的属性标识符请参见产品的TSL描述。
如果是自定义模块属性,属性标识符格式为模块标识符:属性标识符(中间为英文冒号)。例如,物模型自定义模块标识符为test,数据格式为:
"items":{
        "test:Power":{
            "value":"on",
            "time":1510799670074
        },
        "test:Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    }
Position
attribute_8
value 根据TSL定义 属性值。
time Long 属性产生时间,如果设备没有上报数据,默认采用云端生成的时间。
checkFailedData Object 未通过物模型数据校验的数据。
code Integer 数据未通过物模型数据校验时,返回的错误码。详细说明,请参见设备端接收的错误码
message String 数据未通过物模型数据校验时,返回的错误码信息,包含错误原因和具体的错误参数。

历史事件上报

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

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

数据格式:

{
    "identifier":"BrokenInfo",
    "name":"损坏率上报",
    "type":"info",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"X5eCzh6****",
    "deviceName":"5gJtxDVeGAkaEztpisjX",
    "gmtCreate":1510799670074,
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    },
    "checkFailedData":{
        "value": {
            "type": "onMapTrace",
            "content": "{\"tid\":\"1313701472\",\"totalCount\":2267,\"traceStart\":2266,\"pointCount\":1,\"traceValue\":\"XQAABAAFAAAAAB0AE6UAB/oAAA==\"}",
            "timestamp": "15970451390162"
        },
        "code":6304,
        "message":"tsl parse: params not exist -> type"
    },
    "time":1510799670074
}

参数说明:

参数 类型 说明
identifier String 事件的标识符。
如果是自定义模块事件,事件标识符格式为模块标识符:事件标识符(中间为英文冒号)。例如,物模型自定义模块标识符为test,数据格式为:
"test:identifier":"BrokenInfo",
name String 事件的名称。
type String 事件类型,事件类型参见产品的TSL描述。
iotId String 设备在平台内的唯一标识。
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
gmtCreate Long 数据流转消息产生时间。
value Object 事件的参数。
Power String 事件参数名称。
Position String 事件参数名称。
time Long 事件产生时间,如果设备没有上报数据,默认采用云端生成的时间。
checkFailedData Object 未通过物模型数据校验的数据。
content String 设备上报的未通过物模型数据校验的数据。
timestamp Long 设备上报的时间戳。
code Integer 数据未通过物模型数据校验时,返回的错误码。详细说明,请参见设备端接收的错误码
message String 数据未通过物模型数据校验时,返回的错误码信息,包含错误原因和具体的错误参数。

OTA升级状态通知

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

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

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

数据格式:

{
    "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
    "productKey": "X5eCzh6****",
    "deviceName": "deviceName1234",
    "status": "SUCCEEDED|FAILED|CANCELED",
    "messageCreateTime": 1571323748000,
    "srcVersion": "1.0.1",
    "destVersion": "1.0.2",
    "desc": "success",
    "jobId": "wahVIzGkCMuAUE2gDERM02****",
    "taskId": "y3tOmCDNgpR8F9jnVEzC01****"
}

参数说明:

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

OTA模块版本号上报

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

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

数据格式:

{
    "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
    "deviceName": "deviceName1234",
    "productKey": "X5eCzh6****",
    "moduleName": "BarcodeScanner",
    "moduleVersion": "1.0.3",
    "messageCreateTime": 1571323748000
}

参数说明:

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

OTA升级批次状态通知

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

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

数据格式:

{
    "productKey": "X5eCzh6****",
    "moduleName": "BarcodeScanner",
    "packageId": "wahVIzGkCMuAUE2***",
    "jobId": "wahVIzGkCMuAUE2gDERM02****",
    "status": "IN_PROGRESS",
    "messageCreateTime": 1571323748000
}

参数说明:

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

设备标签变更

Topic:/${productKey}/${deviceName}/thing/deviceinfo/update

通过该Topic获得设备的标签变更信息。

数据格式:

{
  "action": "UPDATE|DELETE|DELETEALL"
  "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
  "productKey": "X5eCzh6****",
  "deviceName": "deviceName1234",
  "deletedAttrKeyList": ["abc", "def", "rng"],
  "value": [
    {
      "attrKey": "tagKey",
      "attrValue": "tagValue"
    }
  ],
  "messageCreateTime": 1510799670074
}

参数说明:

参数 类型 说明
action String 标签变更的类型。可取值:
  • UPDATE:更新或新增标签。
  • DELETE:删除指定标签。
  • DELETEALL:清空所有标签。
iotId String 设备ID,设备的唯一标识符。
productKey String 设备所属产品的唯一标识。
deviceName String 设备名称。
deletedAttrKeyList List 删除标签key的列表。

仅当actionDELETE时,显示该参数。

value List 标签数据。
attrKey String 标签Key。
attrValue String 标签Value。
messageCreateTime Long 消息产生时间戳,单位毫秒。

设备任务的状态通知

Topic:/sys/uid/${uid}/job/${jobId}/lifecycle

通过该Topic获得设备任务(设备批量属性设置任务、设备批量服务调用任务、自定义任务)状态变更消息。

其中,${uid}为阿里云账号ID,可登录物联网平台控制台,单击账号头像,跳转至安全设置页面查看。

数据格式:

{
    "jobId": "4z819VQHk6VSLmm***ee200",
    "jobType": "CUSTOM_JOB",
    "status": "INITIALIZING",
    "messageCreateTime": 1510292739881
}

参数说明:

参数 类型 说明
jobId String 任务ID,任务的全局唯一标识符。
jobType String 任务类型。
  • SET_PROPERTY:设备批量属性设置任务。
  • INVOKE_SERVICE:设备批量服务调用任务。
  • CUSTOM_JOB:自定义任务。
status String 任务状态,取值:
  • INITIALIZING:初始化
  • WAITING:待调度
  • IN_PROGRESS:执行中
  • COMPLETED:已完成
  • CANCELLING:取消中
  • CANCELLED:已取消
  • REMOVING:删除中
messageCreateTime Long 消息产生时间戳,单位毫秒。