当您为产品定义物模型后,设备需要按照Alink JSON格式上报属性或事件,如果使用其他格式需要通过消息解析功能转化,服务端设置属性或调用服务同样要满足Alink JSON格式。本文为您介绍物模型数据的Alink JSON格式和Topic。
设备的数据上报方式有两种:ICA标准数据格式(Alink JSON)和透传/自定义。两者二选一,推荐您使用Alink JSON方式。
ICA标准数据格式(Alink JSON):设备按照物联网平台定义的标准数据格式生成数据,然后上报数据。具体格式,请参见本文示例。
物模型功能定义数据类型为float或double时,对应参数值(即使值为整数)至少携带一位小数位。例如10.0、11.1。
设备上报物模型属性和事件数据时,仅支持上报未来24小时内的数据。若上报的time超过该时间范围,上报会失败。
设备上、下行通信中的消息ID(id)在当前设备中具有唯一性,且在每天内的消息中保证唯一即可。
物联网平台云端下行消息中id用于异步下行消息匹配设备端的返回响应,由物联网平台系统保证每天的唯一性。设备端上行消息中id需由设备端自行保证每天的唯一性。
Topic和数据格式(上行):
透传/自定义
Topic
数据格式
请求Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw
请求数据是设备上报的原始报文。
通过MQTT协议透传的数据为16进制格式。
示例如下:
响应Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw_reply
云端返回数据格式如下:
成功返回示例
失败返回示例
Alink JSON
Topic
数据格式
请求Topic:/sys/${productKey}/${deviceName}/thing/event/property/post
请求数据格式:
响应Topic:/sys/${productKey}/${deviceName}/thing/event/property/post_reply
云端返回数据格式如下:
成功返回示例
失败返回示例
参数说明:
参数
类型
说明
id
String
消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version
String
协议版本号,目前协议版本号唯一取值为1.0。
sys
Object
扩展功能的参数,其下包含各功能字段。
使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ack
Integer
sys下的扩展功能字段,表示是否返回响应数据。
1:云端返回响应数据。
0:云端不返回响应数据。
如果未配置该功能,则无此参数,云端默认返回响应数据。
method
String
params
Object
请求参数。如以上示例中,设备上报了的两个属性Power(电源)和WF(工作电流)的信息。具体属性信息,包含属性上报时间(time)和上报的属性值(value)。
若仅传入属性值,无需上传字段time和value,params示例如下:
如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:
time
Long
属性上报时间戳,类型为UTC毫秒级时间。
该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。
若上传time,物联网平台的云端保存上传的时间作为属性上报时间。
若不上传time,物联网平台的云端自动生成属性上报时间并保存。
value
Object
上报的属性值。
若不上传time,可不上传value,直接上传参数值即可。
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code
Integer
物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉,并返回失败的错误码。
data
Object
请求成功时,返回的数据固定为空。
message
String
返回结果信息。请求成功时,返回success。
method
String
响应数据对应的请求方法,与请求参数中method相同。
version
String
协议版本号,与请求参数中version相同。
设置设备属性成功,只表示物联网平台云端下发属性设置请求成功,不保证设备端执行了该请求。所以设备端SDK成功响应云端设置设备属性值的请求后,需上报对应属性值,设备属性值才能真正设置成功。设备上报属性说明,请参见本文“设备上报属性”。
Topic和数据格式(下行):
数据格式(下行)
请求和响应Topic
透传/自定义
请求Topic:/sys/${productKey}/${deviceName}/thing/model/down_raw
响应Topic:/sys/${productKey}/${deviceName}/thing/model/down_raw_reply
Alink JSON
请求Topic:/sys/${productKey}/${deviceName}/thing/service/property/set
响应Topic:/sys/${productKey}/${deviceName}/thing/service/property/set_reply
请求数据格式:
响应数据格式:
成功返回示例
失败返回示例
参数说明:
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version
String
协议版本号,目前协议版本号唯一取值为1.0。
params
Object
属性设置参数。如以上示例中,设置属性:{ "temperature": "30.5" }。
如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号),例如{ "test:temperature": "30.5" }。
method
String
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code
Integer
data
Object
请求成功时,返回的数据固定为空。
message
String
返回结果信息。请求成功时,返回success。
version
String
协议版本号,与请求参数中version相同。
Topic和数据格式(上行):
透传/自定义
Topic
数据格式
请求Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw
请求数据是设备上报的原始报文。
示例如下:
响应Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw_reply
云端返回数据格式如下:
成功返回示例
失败返回示例
Alink JSON
物模型模块
Topic
数据格式
默认模块
以默认模块物模型为例,Alink请求数据格式:
Alink响应数据格式:
若请求失败,返回{}。
自定义模块
参数说明:
参数
类型
说明
id
String
消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version
String
协议版本号,目前协议版本号唯一取值为1.0。
sys
Object
扩展功能的参数,其下包含各功能字段。
使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ack
Integer
sys下的扩展功能字段,表示是否返回响应数据。
1:云端返回响应数据。
0:云端不返回响应数据。
如果未配置该功能,则无此参数,云端默认返回响应数据。
method
String
请求方法。
默认模块
自定义模块
params
Object
上报事件的输出参数。
value
Object
事件的输出参数信息。如以上示例中的两个参数Power(电源)和WF(工作电流)的信息。
time
Long
事件上报的时间戳,类型为UTC毫秒级时间。
该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。
若上传time,物联网平台的云端保存上传的时间作为事件上报时间。
若不上传time,物联网平台的云端自动生成事件上报时间并保存。
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code
Integer
物联网平台会对设备上报的事件做校验。通过产品的TSL描述判断上报的事件是否符合定义的事件格式。不合格的事件会直接被过滤掉,并返回失败的错误码。
data
Object
请求成功时,返回的数据固定为空。
message
String
返回结果信息。请求成功时,返回success。
method
String
响应数据对应的请求方法,与请求参数中method相同。
version
String
协议版本号,与请求参数中version相同。
当设备上报事件时,Alink请求数据格式:
Topic和数据格式(下行):
数据格式(下行)
请求和响应Topic
透传/自定义
请求Topic:/sys/${productKey}/${deviceName}/thing/model/down_raw
响应Topic:/sys/${productKey}/${deviceName}/thing/model/down_raw_reply
Alink JSON
默认模块
自定义模块
Alink请求数据格式:
响应数据格式:
成功返回示例:
失败返回示例:
参数说明:
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version
String
协议版本号,目前协议版本号唯一取值为1.0。
params
Object
服务调用参数。包含服务标识符和服务的值。如以上示例中的两个参数Power(电源)和WF(工作电流)。
method
String
请求方法。
默认模块
自定义模块
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code
Integer
data
Object
返回的结果信息。
data参数的值和物模型定义相关。如果服务没有返回结果,则data的值为空。如果服务有返回结果,则返回的数据会严格遵循服务的定义。
message
String
返回结果信息。请求成功时,返回success。
version
String
协议版本号,与请求参数中version相同。
Alink格式示例:例如产品中定义了服务SetWeight,它的TSL描述如下:
当调用服务时,Alink请求数据格式:
Alink响应数据格式:
网关类型的设备可以批量上报属性和事件,也可以代其子设备批量上报属性和事件。
一次最多可上报200个属性,20个事件。
一次最多可为20个子设备上报数据。
Topic和数据格式(上行):
透传/自定义
Topic
数据格式
请求Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw
请求数据是设备上报的原始报文。
示例如下:
响应Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw_reply
云端返回数据格式如下:
成功返回示例
失败返回示例
Alink JSON
请求和响应Topic
请求和响应数据
请求Topic:/sys/${productKey}/${deviceName}/thing/event/property/pack/post
Alink请求数据格式:
响应Topic:/sys/${productKey}/${deviceName}/thing/event/property/pack/post_reply
Alink响应数据格式:
若请求失败,返回{}。
参数说明:
参数
类型
说明
id
String
消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version
String
协议版本号,目前协议版本号唯一取值为1.0。
sys
Object
扩展功能的参数,其下包含各功能字段。
使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ack
Integer
sys下的扩展功能字段,表示是否返回响应数据。
1:云端返回响应数据。
0:云端不返回响应数据。
如果未配置该功能,则无此参数,云端默认返回响应数据。
params
Object
请求参数。
properties
Object
属性,包含属性标识符、属性值value和属性生成的时间time。
其中,time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。
如以上示例中,设备上报了的两个属性Power(电源)和WF(工作电流)的信息。
如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:
events
Object
事件,包含事件标识符、事件输出参数value和事件生成的时间time。
其中,time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。
如以上示例中,上报了两个事件alarmEvent1(告警事件1)和alarmEvent2(告警事件2),及对应事件参数param1和param2的信息。
如果是自定义模块事件,事件标识符格式为${模块标识符}:${事件标识符}(中间为英文冒号)。例如:
subDevices
Object
子设备信息。
productKey
String
子设备产品的Productkey。
deviceName
String
子设备名称。
method
String
参数
类型
说明
id
String
消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code
Integer
返回结果,200代表成功。
系统会校验设备、拓扑关系、及上报的属性和事件都否符合产品物模型(TSL)中的定义。如果其中任何一项校验不通过,则上报数据失败。
data
Object
请求成功时,返回的数据固定为空。
message
String
返回结果信息。请求成功时,返回success。
method
String
响应数据对应的请求方法,与请求参数中method相同。
version
String
协议版本号,与请求参数中version相同。
Topic和数据格式(上行):
请求Topic:/sys/${productKey}/${deviceName}/thing/event/property/history/post
响应Topic:/sys/${productKey}/${deviceName}/thing/event/property/history/post_reply
Alink请求数据格式:
Alink响应数据格式:
成功返回示例
失败返回示例
参数说明:
参数
类型
说明
id
String
消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version
String
协议版本号,目前协议版本号唯一取值为1.0。
sys
Object
扩展功能的参数,其下包含各功能字段。
使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ack
Integer
sys下的扩展功能字段,表示是否返回响应数据。
1:云端返回响应数据。
0:云端不返回响应数据。
如果未配置该功能,则无此参数,云端默认返回响应数据。
method
String
params
Object
请求参数。
identity
String
数据所属设备的身份证书信息,包含参数productKey和deviceName。
直连设备仅能上报自己的物模型历史数据。网关设备可以上报其子设备的物模型历史数据。网关上报子设备历史数据时,identity为子设备的信息。
properties
Object
属性,包含属性标识符、属性值value和属性生成的时间time。
如以上示例中,设备上报了的两个属性Power(电源)和WF(工作电流)的历史信息。
如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:
events
Object
事件,包含事件标识符、事件输出参数value和事件生成的时间time。
如以上示例中,上报了事件alarmEvent(告警事件)及对应事件参数Power(电源)和WF(工作电流)的历史信息。
如果是自定义模块事件,事件标识符格式为${模块标识符}:${事件标识符}(中间为英文冒号)。例如:
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code
Integer
data
Object
请求成功时,返回的数据固定为空。
message
String
返回结果信息。请求成功时,返回success。
method
String
响应数据对应的请求方法,与请求参数中method相同。
version
String
协议版本号,与请求参数中version相同。
转发设备上报的物模型历史数据时,会根据上报的properties、events下属性、事件个数构建对应数量消息,分别转发每个属性或事件的历史数据。
Topic和数据格式(上行):
请求Topic:/sys/${productKey}/${deviceName}/thing/event/property/batch/post
响应Topic:/sys/${productKey}/${deviceName}/thing/event/property/batch/post_reply
Alink请求数据格式:
Alink响应数据格式:
成功返回示例:
失败返回示例:
参数说明:
参数
类型
说明
id
String
消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version
String
协议版本号,目前协议版本号唯一取值为1.0。
sys
Object
扩展功能的参数,其下包含各功能字段。
使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ack
Integer
sys下的扩展功能字段,表示是否返回响应数据。
1:云端返回响应数据。
0:云端不返回响应数据。
如果未配置该功能,则无此参数,云端默认返回响应数据。
method
String
params
Object
请求参数。
properties
Object
属性,包含属性标识符、属性值value和属性生成的时间time。
如以上示例中,设备上报了的两个属性Power(电源)和WF(工作电流)的批量信息。
如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:
events
Object
事件,包含事件标识符、事件输出参数value和事件生成的时间time。
如以上示例中,上报了事件alarmEvent(告警事件)及对应事件参数Power(电源)和WF(工作电流)的批量信息。
如果是自定义模块事件,事件标识符格式为${模块标识符}:${事件标识符}(中间为英文冒号)。例如:
参数
类型
说明
id
String
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
code
Integer
data
Object
请求成功时,返回的数据固定为空。
message
String
返回结果信息。请求成功时,返回success。
method
String
响应数据对应的请求方法,与请求参数中method相同。
version
String
协议版本号,与请求参数中version相同。
关注阿里云公众号或下载阿里云APP,关注云资讯,随时随地运维管控云服务