如果产品定义了物模型,设备可以上报属性和事件信息,服务端可以下发设置属性和调用服务指令。
物模型(属性、事件、服务)数据格式,请参见物模型TSL格式。
设备的数据上报方式有两种:ICA标准数据格式(Alink JSON)和透传/自定义。两者二选一,推荐您使用Alink JSON方式。
- ICA标准数据格式(Alink JSON):设备按照物联网平台定义的标准数据格式生成数据,然后上报数据。具体格式,请参见本文示例。
- 透传/自定义:设备上报原始数据如二进制数据流,阿里云物联网平台会运行您在控制台提交的数据解析脚本,将原始数据转成标准数据格式后,再进行业务处理。而云端返回的是标准Alink JSON格式,返回结果经数据解析后,再推送给设备。
设备上报属性
数据格式(上行) | 请求和响应Topic | 请求和响应数据 |
---|---|---|
透传/自定义 |
|
请求数据是设备上报的原始报文。
说明
示例如下:
云端返回数据格式如下:
|
Alink JSON |
|
Alink请求数据格式:
Alink响应数据格式:
|
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
version | String | 协议版本号,目前协议版本号唯一取值为1.0。 |
sys | Object | 扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
|
ack | Integer | sys下的扩展功能字段,表示是否返回响应数据。
说明 该功能配置说明,请参见物模型编程。
如果未配置该功能,则无此参数,云端默认返回响应数据。 |
method | String | 请求方法。取值:thing.event.property.post 。
|
params | Object | 请求参数。如以上示例中,设备上报了的两个属性Power和WF。具体属性信息,包含属性上报时间(time)和上报的属性值(value)。
如果是自定义模块属性,属性标识符格式为 |
time | Long | 属性上报时间,类型为UTC毫秒级时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。 |
value | Object | 上报的属性值。 |
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 结果状态码。 具体参考设备端通用code。
说明 物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉,并返回失败的错误码。
|
data | Object | 请求成功时,返回的数据。固定为空。 |
错误码 | 消息 | 描述 |
---|---|---|
460 | request parameter error | 请求参数错误。 |
6106 | map size must less than 200 | 一次最多只能上报200条属性。 |
6313 | tsl service not available |
物模型校验服务不可用。 物联网平台根据您定义的TSL中属性格式,校验上报的属性信息。 校验后,将过滤掉不合格的属性,仅保留合格属性。即使全部属性都被过滤,也代表着校验成功。 若校验服务不可用,报6313错误码。 |
设备上报至平台的属性信息,可以通过服务端订阅、云产品流转转发到您的服务器或其他云产品。具体Topic和数据格式,请参见设备属性上报。
设置设备属性
通过调用SetDeviceProperty或SetDevicesProperty下发设置属性指令到设备。
数据格式(下行) | 请求和响应Topic |
---|---|
透传/自定义 |
|
Alink JSON |
|
Alink请求数据格式:
{
"id": "123",
"version": "1.0",
"params": {
"temperature": "30.5"
},
"method": "thing.service.property.set"
}
参数 | 类型 | 说明 |
---|---|---|
id | String |
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
version | String | 协议版本号,目前协议版本号唯一取值为1.0。 |
params | Object | 属性设置参数。如以上示例中,设置属性:{ "temperature": "30.5" } 。
如果是自定义模块属性,属性标识符格式为 |
method | String | 请求方法。取值:thing.service.property.set 。
|
Alink响应数据格式:
{
"id": "123",
"code": 200,
"data": {}
}
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 结果状态码,具体参考设备端通用code。 |
data | Object | 请求成功时,返回的数据。固定为空。 |
属性设置的结果,可以通过服务端订阅、云产品流转转发到您的服务器或其他云产品。具体Topic和数据格式,请参见设备下行指令结果。
设备上报事件
数据格式(上行) | 请求和响应Topic | 请求和响应数据 |
---|---|---|
透传/自定义 |
|
请求数据是设备上报的原始报文。
说明 透传的上报数据中,必须包含请求方法method参数,详细信息请参见下表说明。
示例如下:
云端返回数据格式如下:
|
Alink JSON |
|
Alink请求数据格式:
Alink响应数据格式:
|
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
version | String | 协议版本号,目前协议版本号唯一取值为1.0。 |
sys | Object | 扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
|
ack | Integer | sys下的扩展功能字段,表示是否返回响应数据。
说明 该功能配置说明,请参见物模型编程。
如果未配置该功能,则无此参数,云端默认返回响应数据。 |
method | String | 请求方法。
|
params | Object | 上报事件的参数。 |
value | Object | 具体的事件信息。如以上示例中
|
time | Long | 事件生成的时间戳,类型为UTC毫秒级时间。
该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。 |
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 结果状态码,具体参考设备端通用code。
说明 物联网平台会对设备上报的事件做校验。通过产品的TSL描述判断上报的事件是否符合定义的事件格式。不合格的事件会直接被过滤掉,并返回失败的错误码。
|
data | Object | 请求成功时,返回的数据。固定为空。 |
Alink格式示例:
假设产品中定义了一个alarm事件,它的TSL描述如下:
{
"schema": "https://iot-tsl.oss-cn-shanghai.aliyuncs.com/schema.json",
"link": "/sys/${productKey}/airCondition/thing/",
"profile": {
"productKey": "${productKey},请替换为您的ProductKey",
"deviceName": "airCondition,请替换为您的Devicename"
},
"events": [
{
"identifier": "alarm",
"name": "alarm",
"desc": "风扇警报",
"type": "alert",
"required": true,
"outputData": [
{
"identifier": "errorCode",
"name": "错误码",
"dataType": {
"type": "text",
"specs": {
"length": "255"
}
}
}
],
"method": "thing.event.alarm.post"
}
]
}
当设备上报事件时,Alink请求数据格式:
{
"id": "123",
"version": "1.0",
"params": {
"value": {
"errorCode": "error"
},
"time": 1524448722000
},
"method": "thing.event.alarm.post"
}
设备上报至平台的事件信息,可以通过服务端订阅、云产品流转转发到您的服务器或其他云产品。具体Topic和数据格式,请参见设备上报事件。
设备服务调用(异步调用)
- 同步方式:通过InvokeThingService或InvokeThingsService接口调用服务,物联网平台直接使用RRPC同步方式下行推送请求。此时,服务选择为同步调用方式,物联网平台订阅RRPC对应Topic。设备RRPC的集成方式,请参见什么是RRPC。
- 异步方式:通过InvokeThingService或InvokeThingsService接口调用服务,物联网平台采用异步方式下行推送请求,设备也采用异步方式返回结果。此时,服务选择为异步调用方式,物联网平台订阅此处的异步响应Topic。
异步调用的结果,可以通过服务端订阅、云产品流转转发到您的服务器或其他云产品。对应Topic和数据格式,请参见设备下行指令结果。
数据格式(下行) | 请求和响应Topic |
---|---|
透传/自定义 |
|
Alink JSON |
|
Alink请求数据格式:
{
"id": "123",
"version": "1.0",
"params": {
"Power": "on",
"WF": "2"
},
"method": "thing.service.{tsl.service.identifier}"
}
参数 | 类型 | 说明 |
---|---|---|
id | String |
消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
version | String | 协议版本号,目前协议版本号唯一取值为1.0。 |
params | Object | 服务调用参数。包含服务标识符和服务的值。如以上示例中:
|
method | String | 请求方法。
|
Alink响应数据格式:
{
"id": "123",
"code": 200,
"data": {}
}
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 结果状态码,具体参考设备端通用code。 |
data | Object | 返回的结果信息。
data参数的值和物模型定义相关。如果服务没有返回结果,则data的值为空。如果服务有返回结果,则返回的数据会严格遵循服务的定义。 |
Alink格式示例:
例如产品中定义了服务SetWeight,它的TSL描述如下:
{
"schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
"profile": {
"productKey": "testProduct01"
},
"services": [
{
"outputData": [
{
"identifier": "OldWeight",
"dataType": {
"specs": {
"unit": "kg",
"min": "0",
"max": "200",
"step": "1"
},
"type": "double"
},
"name": "OldWeight"
},
{
"identifier": "CollectTime",
"dataType": {
"specs": {
"length": "2048"
},
"type": "text"
},
"name": "CollectTime"
}
],
"identifier": "SetWeight",
"inputData": [
{
"identifier": "NewWeight",
"dataType": {
"specs": {
"unit": "kg",
"min": "0",
"max": "200",
"step": "1"
},
"type": "double"
},
"name": "NewWeight"
}
],
"method": "thing.service.SetWeight",
"name": "设置重量",
"required": false,
"callType": "async"
}
]
}
当调用服务时,Alink请求数据格式:
{
"method": "thing.service.SetWeight",
"id": "105917531",
"params": {
"NewWeight": 100.8
},
"version": "1.0"
}
Alink响应数据格式:
{
"id": "105917531",
"code": 200,
"data": {
"CollectTime": "1536228947682",
"OldWeight": 100.101
}
}
网关批量上报数据
网关类型的设备可以批量上报属性和事件,也可以代其子设备批量上报属性和事件。
- 一次最多可上报200个属性,20个事件。
- 一次最多可为20个子设备上报数据。
数据格式(上行) | 请求和响应Topic | 请求和响应数据 |
---|---|---|
透传/自定义 |
|
请求数据是设备上报的原始报文。
说明 透传的上报数据中,必须包含请求方法method参数,取值为
thing.event.property.pack.post 。
示例如下:
云端返回数据格式如下:
|
Alink JSON |
|
Alink请求数据格式:
Alink响应数据格式:
|
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
version | String | 协议版本号,目前协议版本号唯一取值为1.0。 |
sys | Object | 扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
|
ack | Integer | sys下的扩展功能字段,表示是否返回响应数据。
说明 该功能配置说明,请参见物模型编程。
如果未配置该功能,则无此参数,云端默认返回响应数据。 |
params | Object | 请求参数。 |
properties | Object | 属性,包含属性标识符、属性值value和属性生成的时间time。
其中,time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。 如果是自定义模块属性,属性标识符格式为 |
events | Object | 事件,包含事件标识符、事件输出参数value和事件生成的时间time。
其中,time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。 如果是自定义模块事件,事件标识符格式为 |
subDevices | Object | 子设备信息。 |
productKey | String | 子设备产品的Productkey。 |
deviceName | String | 子设备名称。 |
method | String | 请求参数。取值:thing.event.property.pack.post 。
|
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 返回结果,200代表成功。
说明 系统会校验设备、拓扑关系、及上报的属性和事件都否符合产品物模型(TSL)中的定义。如果其中任何一项校验不通过,则上报数据失败。
|
data | Object | 请求成功时,返回的数据。固定为空。 |
物模型历史数据上报
数据上行:
- 请求Topic:
/sys/{productKey}/{deviceName}/thing/event/property/history/post
- 响应Topic:
/sys/{productKey}/{deviceName}/thing/event/property/history/post_reply
Alink请求数据格式:
{
"id": 123,
"version": "1.0",
"sys":{
"ack":0
},
"method": "thing.event.property.history.post",
"params": [
{
"identity": {
"productKey": "",
"deviceName": ""
},
"properties": [
{
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": "3",
"time": 1524448722000
}
},
{
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": "3",
"time": 1524448722000
}
}
],
"events": [
{
"alarmEvent": {
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
"alertEvent": {
"value": {
"Power": "off",
"WF": "3"
},
"time": 1524448722000
}
}
]
},
{
"identity": {
"productKey": "",
"deviceName": ""
},
"properties": [
{
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": "3",
"time": 1524448722000
}
}
],
"events": [
{
"alarmEvent": {
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
"alertEvent": {
"value": {
"Power": "off",
"WF": "3"
},
"time": 1524448722000
}
}
]
}
]
}
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
version | String | 协议版本号,目前协议版本号唯一取值为1.0。 |
sys | Object | 扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
|
ack | Integer | sys下的扩展功能字段,表示是否返回响应数据。
说明 该功能配置说明,请参见物模型编程。
如果未配置该功能,则无此参数,云端默认返回响应数据。 |
method | String | 请求方法。取值:thing.event.property.history.post 。
|
params | Object | 请求参数。 |
identity | String | 数据所属设备的身份证书信息,包含参数productKey和deviceName。
说明 直连设备仅能上报自己的物模型历史数据。网关设备可以上报其子设备的物模型历史数据。网关上报子设备历史数据时,identity为子设备的信息。
|
properties | Object | 属性,包含属性标识符、属性值value和属性生成的时间time。
如果是自定义模块属性,属性标识符格式为 |
events | Object | 事件,包含事件标识符、事件输出参数value和事件生成的时间time。
如果是自定义模块事件,事件标识符格式为 |
Alink响应数据格式:
{
"id":"123",
"code":200,
"data":{}
}
设备上报至平台的物模型历史数据,可以通过服务端订阅、云产品流转转发到您的服务器或其他云产品。具体Topic和数据格式,请参见物模型历史数据格式。
设备批量上报属性、事件
数据上行:
- 请求Topic:
/sys/{productKey}/{deviceName}/thing/event/property/batch/post
- 响应Topic:
/sys/{productKey}/{deviceName}/thing/event/property/batch/post_reply
Alink请求数据格式:
{
"id": 123,
"version": "1.0",
"sys":{
"ack":0
},
"method": "thing.event.property.batch.post",
"params": {
"properties": {
"Power": [{
"value": "on",
"time": 1524448722000
},
{
"value": "off",
"time": 1524448722001
}
],
"WF": [{
"value": 3,
"time": 1524448722000
},
{
"value": 4,
"time": 1524448722009
}
]
},
"events": {
"alarmEvent": [{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
}
]
}
}
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
version | String | 协议版本号,目前协议版本号唯一取值为1.0。 |
sys | Object | 扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
|
ack | Integer | sys下的扩展功能字段,表示是否返回响应数据。
说明 该功能配置说明,请参见物模型编程。
如果未配置该功能,则无此参数,云端默认返回响应数据。 |
method | String | 请求方法。取值:thing.event.property.batch.post 。
|
params | Object | 请求参数。 |
properties | Object | 属性,包含属性标识符、属性值value和属性生成的时间time。
如果是自定义模块属性,属性标识符格式为 |
events | Object | 事件,包含事件标识符、事件输出参数value和事件生成的时间time。
如果是自定义模块事件,事件标识符格式为 |
Alink响应数据格式:
{
"id":"123",
"code":200,
"data":{}
}
设备批量上报至平台的物模型数据,可以通过服务端订阅、云产品流转转发到您的服务器或其他云产品。属性和事件数据分为两条消息进行转发,具体Topic和数据格式,请参见设备属性批量上报、设备事件批量上报。
在文档使用中是否遇到以下问题
更多建议
匿名提交