设备属性、事件、服务

当您为产品定义物模型后,设备需要按照Alink JSON格式上报属性事件,如果使用其他格式需要通过消息解析功能转化,服务端设置属性调用服务同样要满足Alink JSON格式。本文为您介绍物模型数据的Alink JSON格式和Topic。

背景信息

物模型(属性、事件、服务)数据格式,请参见什么是物模型

设备的数据上报方式有两种:ICA标准数据格式(Alink JSON)和透传/自定义。两者二选一,推荐您使用Alink JSON方式。

  • ICA标准数据格式(Alink JSON):设备按照物联网平台定义的标准数据格式生成数据,然后上报数据。具体格式,请参见本文示例。

  • 透传/自定义:设备上报原始数据如二进制数据流,阿里云物联网平台会运行您在控制台提交的消息解析脚本,将原始数据转成标准数据格式后,再进行业务处理。而云端返回的是标准Alink JSON格式,返回结果经数据解析后,再推送给设备。物模型数据透传

重要
  • 物模型功能定义数据类型为float或double时,对应参数值(即使值为整数)至少携带一位小数位。例如10.0、11.1。

  • 设备上报物模型属性和事件数据时,仅支持上报未来24小时内的数据。若上报的time超过该时间范围,上报会失败。

  • 设备上、下行通信中的消息ID(id)在当前设备中具有唯一性,且在每天内的消息中保证唯一即可。

    物联网平台云端下行消息中id用于异步下行消息匹配设备端的返回响应,由物联网平台系统保证每天的唯一性。设备端上行消息中id需由设备端自行保证每天的唯一性。

设备上报属性

实现设备上报属性的原理,请参见Alink协议中设备上报属性原理图

Topic和数据格式(上行):

  • 透传/自定义

    Topic

    数据格式

    请求Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw

    请求数据是设备上报的原始报文。

    说明
    • 通过MQTT协议透传的数据为16进制格式。

    • 透传的上报数据中,必须包含请求方法method参数,取值需与数据解析脚本中定义的对应请求方法一致。例如JavaScript脚本示例中设备上传属性数据到云端的ALINK_PROP_REPORT_METHODthing.event.property.post

    示例如下:

    0x00002233441232013fa00000

    响应Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw_reply

    云端返回数据格式如下:

    • 成功返回示例

      {
          "code": 200,
          "data": {},
          "id": "123",
          "message": "success",
          "version": "1.0"
      }
    • 失败返回示例

      {
          "code": 6813,
          "data": {},
          "id": "123",
          "message": "topic illegal",
          "version": "1.0"
      }
  • Alink JSON

    Topic

    数据格式

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

    请求数据格式:

    {
        "id": "123",
        "version": "1.0",
        "sys":{
            "ack":0
        },
        "params": {
            "Power": {
                "value": "on",
                "time": 1524448722000
            },
            "WF": {
                "value": 23.6,
                "time": 1524448722000
            }
        },
        "method": "thing.event.property.post"
    }

    响应Topic:/sys/${productKey}/${deviceName}/thing/event/property/post_reply

    云端返回数据格式如下:

    • 成功返回示例

      {
          "code": 200,
          "data": {},
          "id": "123",
          "message": "success",
          "method": "thing.event.property.post",
          "version": "1.0"
      }
    • 失败返回示例

      {
          "code": 6813,
          "data": {},
          "id": "123",
          "message": "The format of result is error!",
          "method": "thing.event.property.post",
          "version": "1.0"
      }

参数说明:

表 1. 请求参数说明

参数

类型

说明

id

String

消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

version

String

协议版本号,目前协议版本号唯一取值为1.0。

sys

Object

扩展功能的参数,其下包含各功能字段。

说明

使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。

ack

Integer

sys下的扩展功能字段,表示是否返回响应数据。

  • 1:云端返回响应数据。

  • 0:云端不返回响应数据。

重要

该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

method

String

请求方法。例如:thing.event.property.post

params

Object

请求参数。如以上示例中,设备上报了的两个属性Power(电源)和WF(工作电流)的信息。具体属性信息,包含属性上报时间(time)和上报的属性值(value)。

若仅传入属性值,无需上传字段timevalueparams示例如下:

"params": {
    "Power": "on",
    "WF": 23.6
}

如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:

"test:Power": {
    "value": "on",
    "time": 1524448722000
}

time

Long

属性上报时间戳,类型为UTC毫秒级时间。

该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。

  • 若上传time,物联网平台的云端保存上传的时间作为属性上报时间。

  • 若不上传time,物联网平台的云端自动生成属性上报时间并保存。

value

Object

上报的属性值。

若不上传time,可不上传value,直接上传参数值即可。

表 2. 响应参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

code

Integer

结果状态码。 具体参考设备端通用code

说明

物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉,并返回失败的错误码。

data

Object

请求成功时,返回的数据固定为空。

message

String

返回结果信息。请求成功时,返回success。

method

String

响应数据对应的请求方法,与请求参数中method相同。

version

String

协议版本号,与请求参数中version相同。

错误码说明:物联网平台可能返回给设备端的错误码及说明,请参见设备端接收的错误码

消息转发说明:设备上报至平台的属性信息,可以通过服务端订阅云产品流转转发到您的服务器或其他云产品。具体Topic和数据格式,请参见设备属性上报

设置设备属性

通过调用SetDevicePropertySetDevicesProperty下发设置属性指令到设备。实现设置设备属性的原理,请参见Alink协议中设置属性原理图

重要

设置设备属性成功,只表示物联网平台云端下发属性设置请求成功,不保证设备端执行了该请求。所以设备端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": "123",
    "version": "1.0",
    "params": {
        "temperature": "30.5"
    },
    "method": "thing.service.property.set"
}

响应数据格式:

  • 成功返回示例

    {
        "code": 200,
        "data": {},
        "id": "123",
        "message": "success",
        "version": "1.0"
    }
  • 失败返回示例

    {
        "code": 9201,
        "data": {},
        "id": "123",
        "message": "device offLine",
        "version": "1.0"
    }

参数说明:

表 3. 请求参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

version

String

协议版本号,目前协议版本号唯一取值为1.0。

params

Object

属性设置参数。如以上示例中,设置属性:{ "temperature": "30.5" }

如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号),例如{ "test:temperature": "30.5" }

method

String

请求方法。例如:thing.service.property.set

表 4. 响应参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

code

Integer

结果状态码,具体参考设备端通用code

data

Object

请求成功时,返回的数据固定为空。

message

String

返回结果信息。请求成功时,返回success。

version

String

协议版本号,与请求参数中version相同。

错误码说明:物联网平台可能返回给设备端的错误码及说明,请参见设备端接收的错误码

消息转发说明:属性设置的结果,可以通过服务端订阅云产品流转转发到您的服务器或其他云产品。具体Topic和数据格式,请参见设备下行指令结果

设备上报事件

实现设备上报事件的原理,请参见Alink协议中设备上报事件原理图

Topic和数据格式(上行):

  • 透传/自定义

    Topic

    数据格式

    请求Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw

    请求数据是设备上报的原始报文。

    说明

    透传的上报数据中,必须包含请求方法method参数,取值需与数据解析脚本中定义的对应请求方法一致。例如,取值为thing.event.${tsl.event.identifier}.post

    示例如下:

    0xff0000007b00

    响应Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw_reply

    云端返回数据格式如下:

    • 成功返回示例

      {
          "code": 200,
          "data": {},
          "id": "123",
          "message": "success",
          "version": "1.0"
      }
    • 失败返回示例

      {
          "code": 6813,
          "data": {},
          "id": "123",
          "message": "topic illegal",
          "version": "1.0"
      }
  • Alink JSON

    物模型模块

    Topic

    数据格式

    默认模块

    • 请求Topic:/sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post

    • 响应Topic:/sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post_reply

    以默认模块物模型为例,Alink请求数据格式:

    {
        "id": "123",
        "version": "1.0",
        "sys":{
            "ack":0
        },
        "params": {
            "value": {
                "Power": "on",
                "WF": "2"
            },
            "time": 1524448722000
        },
        "method": "thing.event.${tsl.event.identifier}.post"
    }

    Alink响应数据格式:

    {
        "code": 200,
        "data": {},
        "id": "123",
        "message": "success",
        "method": "thing.event.${tsl.event.identifier}.post",
        "version": "1.0"
    }

    若请求失败,返回{}

    自定义模块

    • 请求Topic:/sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:${tsl.event.identifier}/post

    • 响应Topic:/sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:${tsl.event.identifier}/post_reply

参数说明:

表 5. 请求参数说明

参数

类型

说明

id

String

消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

version

String

协议版本号,目前协议版本号唯一取值为1.0。

sys

Object

扩展功能的参数,其下包含各功能字段。

说明

使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。

ack

Integer

sys下的扩展功能字段,表示是否返回响应数据。

  • 1:云端返回响应数据。

  • 0:云端不返回响应数据。

重要

该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

method

String

请求方法。

  • 默认模块

    取值为thing.event.${tsl.event.identifier}.post

  • 自定义模块

    取值为thing.event.${tsl.functionBlockId}:${tsl.event.identifier}.post

说明

${tsl.event.identifier}为物模型中定义的事件标识符,${tsl.functionBlockId}为自定义模块的标识符。更多信息,请参见单个添加物模型

params

Object

上报事件的输出参数。

value

Object

事件的输出参数信息。如以上示例中的两个参数Power(电源)和WF(工作电流)的信息。

{
    "Power": "on",
    "WF": "2"
}

time

Long

事件上报的时间戳,类型为UTC毫秒级时间。

该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。

  • 若上传time,物联网平台的云端保存上传的时间作为事件上报时间。

  • 若不上传time,物联网平台的云端自动生成事件上报时间并保存。

表 6. 响应参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

code

Integer

结果状态码,具体参考设备端通用code

说明

物联网平台会对设备上报的事件做校验。通过产品的TSL描述判断上报的事件是否符合定义的事件格式。不合格的事件会直接被过滤掉,并返回失败的错误码。

data

Object

请求成功时,返回的数据固定为空。

message

String

返回结果信息。请求成功时,返回success。

method

String

响应数据对应的请求方法,与请求参数中method相同。

version

String

协议版本号,与请求参数中version相同。

Alink格式示例:假设产品中定义了一个alarm事件,它的TSL描述如下。参数说明,请参见什么是物模型

{
    "schema": "https://iot-tsl.oss-cn-shanghai.aliyuncs.com/schema.json",
    "link": "/sys/${productKey}/airCondition/thing/",
    "profile": {
        "productKey": "${productKey}",
        "deviceName": "airCondition"
    },
    "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和数据格式,请参见设备上报事件

设备服务调用(异步调用)

物联网平台支持同步调用和异步调用。物模型定义服务时,需设置此项。实现设备服务调用的原理,请参见Alink协议中服务调用原理图

  • 同步方式:通过InvokeThingServiceInvokeThingsService接口调用服务,物联网平台直接使用RRPC同步方式下行推送请求。此时,服务选择为同步调用方式,物联网平台订阅RRPC对应Topic。设备RRPC的集成方式,请参见什么是RRPC

  • 异步方式:通过InvokeThingServiceInvokeThingsService接口调用服务,物联网平台采用异步方式下行推送请求,设备也采用异步方式返回结果。此时,服务选择为异步调用方式,物联网平台订阅此处的异步响应Topic。

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/${tsl.service.identifier}

    • 响应Topic:/sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}_reply

  • 自定义模块

    • 请求Topic:/sys/${productKey}/${deviceName}/thing/service/${tsl.functionBlockId}:${tsl.service.identifier}

    • 响应Topic:/sys/${productKey}/${deviceName}/thing/service/${tsl.functionBlockId}:${tsl.service.identifier}_reply

Alink请求数据格式:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "Power": "on",
        "WF": "2"
    },
    "method": "thing.service.${tsl.service.identifier}"
}

响应数据格式:

  • 成功返回示例:

    {
        "code": 200,
        "data": {},
        "id": "123",
        "message": "success",
        "version": "1.0"
    }
  • 失败返回示例:

    {
        "code": 9201,
        "data": {},
        "id": "123",
        "message": "device offLine",
        "version": "1.0"
    }

参数说明:

表 7. 请求参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

version

String

协议版本号,目前协议版本号唯一取值为1.0。

params

Object

服务调用参数。包含服务标识符和服务的值。如以上示例中的两个参数Power(电源)和WF(工作电流)。

{
    "Power": "on",
    "WF": "2"
}

method

String

请求方法。

  • 默认模块

    取值为thing.service.${tsl.service.identifier}

  • 自定义模块

    取值为thing.service.${tsl.functionBlockId}:${tsl.service.identifier}

说明

${tsl.service.identifier}为物模型中定义的服务标识符,${tsl.functionBlockId}为自定义模块的标识符。更多信息,请参见单个添加物模型

表 8. 返回参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

code

Integer

结果状态码,具体参考设备端通用code

data

Object

返回的结果信息。

data参数的值和物模型定义相关。如果服务没有返回结果,则data的值为空。如果服务有返回结果,则返回的数据会严格遵循服务的定义。

message

String

返回结果信息。请求成功时,返回success。

version

String

协议版本号,与请求参数中version相同。

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
    }
    "message": "success",
    "version": "1.0"
}

错误码说明:物联网平台可能返回给设备端的错误码及说明,请参见设备端接收的错误码

消息转发说明:异步调用的结果,可以通过服务端订阅云产品流转转发到您的服务器或其他云产品。对应Topic和数据格式,请参见设备下行指令结果

网关批量上报数据

网关类型的设备可以批量上报属性和事件,也可以代其子设备批量上报属性和事件。

说明
  • 一次最多可上报200个属性,20个事件。

  • 一次最多可为20个子设备上报数据。

Topic和数据格式(上行):

  • 透传/自定义

    Topic

    数据格式

    请求Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw

    请求数据是设备上报的原始报文。

    说明

    透传的上报数据中,必须包含请求方法method参数,取值需与数据解析脚本中定义的对应请求方法一致。例如,取值为thing.event.property.pack.post

    示例如下:

    0xff0000007b00

    响应Topic:/sys/${productKey}/${deviceName}/thing/model/up_raw_reply

    云端返回数据格式如下:

    • 成功返回示例

      {
          "code": 200,
          "data": {},
          "id": "123",
          "message": "success",
          "version": "1.0"
      }
    • 失败返回示例

      {
          "code": 6813,
          "data": {},
          "id": "123",
          "message": "topic illegal",
          "version": "1.0"
      }
  • Alink JSON

    请求和响应Topic

    请求和响应数据

    请求Topic:/sys/${productKey}/${deviceName}/thing/event/property/pack/post

    Alink请求数据格式:

    {
        "id": "123",
        "version": "1.0",
        "sys":{
            "ack":0
        },
        "params": {
            "properties": {
                "Power": {
                    "value": "on",
                    "time": 1524448722000
                },
                "WF": {
                    "value": { },
                    "time": 1524448722000
                }
            },
            "events": {
                "alarmEvent1": {
                    "value": {
                        "param1": "on",
                        "param2": "2"
                    },
                    "time": 1524448722000
                },
                "alertEvent2": {
                    "value": {
                        "param1": "on",
                        "param2": "2"
                    },
                    "time": 1524448722000
                }
            },
            "subDevices": [
                {
                    "identity": {
                        "productKey": "",
                        "deviceName": ""
                    },
                    "properties": {
                        "Power": {
                            "value": "on",
                            "time": 1524448722000
                        },
                        "WF": {
                            "value": { },
                            "time": 1524448722000
                        }
                    },
                    "events": {
                        "alarmEvent1": {
                            "value": {
                                "param1": "on",
                                "param2": "2"
                            },
                            "time": 1524448722000
                        },
                        "alertEvent2": {
                            "value": {
                                "param1": "on",
                                "param2": "2"
                            },
                            "time": 1524448722000
                        }
                    }
                }
            ]
        },
        "method": "thing.event.property.pack.post"
    }

    响应Topic:/sys/${productKey}/${deviceName}/thing/event/property/pack/post_reply

    Alink响应数据格式:

    {
        "code": 200,
        "data": {},
        "id": "123",
        "message": "success",
        "method": "thing.event.property.pack.post",
        "version": "1.0"
    }

    若请求失败,返回{}

参数说明:

表 9. 请求参数说明

参数

类型

说明

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(工作电流)的信息。

如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:

"test:Power": {
    "value": "on",
    "time": 1524448722000
}

events

Object

事件,包含事件标识符、事件输出参数value和事件生成的时间time

其中,time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。

如以上示例中,上报了两个事件alarmEvent1(告警事件1)和alarmEvent2(告警事件2),及对应事件参数param1和param2的信息。

如果是自定义模块事件,事件标识符格式为${模块标识符}:${事件标识符}(中间为英文冒号)。例如:

"test:alarmEvent1": {
    "value": {
        "param1": "on",
        "param2": "2"
    },
    "time": 1524448722000
}

subDevices

Object

子设备信息。

productKey

String

子设备产品的Productkey。

deviceName

String

子设备名称。

method

String

请求参数。取值:thing.event.property.pack.post

表 10. 响应参数说明

参数

类型

说明

id

String

消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

code

Integer

返回结果,200代表成功。

说明

系统会校验设备、拓扑关系、及上报的属性和事件都否符合产品物模型(TSL)中的定义。如果其中任何一项校验不通过,则上报数据失败。

data

Object

请求成功时,返回的数据固定为空。

message

String

返回结果信息。请求成功时,返回success。

method

String

响应数据对应的请求方法,与请求参数中method相同。

version

String

协议版本号,与请求参数中version相同。

错误码说明:物联网平台可能返回给设备端的错误码及说明,请参见设备端接收的错误码

消息转发说明:网关批量上报至平台的物模型数据,可以通过服务端订阅云产品流转转发到您的服务器或其他云产品。网关批量上报数据的消息转发会将子设备和网关设备的消息分别分为单个属性或事件消息进行转发,具体Topic和数据格式,请参见设备属性上报设备事件上报

物模型历史数据上报

Topic和数据格式(上行):

  • 请求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
                    }
                }
            ]
        }
    ]
}

Alink响应数据格式:

  • 成功返回示例

    {
        "code": 200,
        "data": {},
        "id": "123",
        "message": "success",
        "method": "thing.event.property.history.post",
        "version": "1.0"
    }
  • 失败返回示例

    {
        "code": 5092,
        "data": {},
        "id": "123",
        "message": "property not found",
        "method": "thing.event.property.history.post",
        "version": "1.0"
    }

参数说明:

表 11. 请求参数说明

参数

类型

说明

id

String

消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

version

String

协议版本号,目前协议版本号唯一取值为1.0。

sys

Object

扩展功能的参数,其下包含各功能字段。

说明

使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。

ack

Integer

sys下的扩展功能字段,表示是否返回响应数据。

  • 1:云端返回响应数据。

  • 0:云端不返回响应数据。

重要

该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

method

String

请求方法。取固定值:thing.event.property.history.post

params

Object

请求参数。

identity

String

数据所属设备的身份证书信息,包含参数productKeydeviceName

说明

直连设备仅能上报自己的物模型历史数据。网关设备可以上报其子设备的物模型历史数据。网关上报子设备历史数据时,identity为子设备的信息。

properties

Object

属性,包含属性标识符、属性值value和属性生成的时间time

如以上示例中,设备上报了的两个属性Power(电源)和WF(工作电流)的历史信息。

如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:

"test:Power": {
    "value": "on",
    "time": 1524448722000
}

events

Object

事件,包含事件标识符、事件输出参数value和事件生成的时间time

如以上示例中,上报了事件alarmEvent(告警事件)及对应事件参数Power(电源)和WF(工作电流)的历史信息。

如果是自定义模块事件,事件标识符格式为${模块标识符}:${事件标识符}(中间为英文冒号)。例如:

"test:alarmEvent": {
    "value": {
        "Power": "on", 
        "WF": "2"
    }, 
    "time": 1524448722000
}
表 12. 响应参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

code

Integer

结果状态码,具体参考设备端通用code

data

Object

请求成功时,返回的数据固定为空。

message

String

返回结果信息。请求成功时,返回success。

method

String

响应数据对应的请求方法,与请求参数中method相同。

version

String

协议版本号,与请求参数中version相同。

错误码说明:物联网平台可能返回给设备端的错误码及说明,请参见设备端接收的错误码

消息转发说明:设备上报至平台的物模型历史数据,可以通过服务端订阅云产品流转转发到您的服务器或其他云产品。具体Topic和数据格式,请参见历史属性上报历史事件上报

重要

转发设备上报的物模型历史数据时,会根据上报的propertiesevents下属性、事件个数构建对应数量消息,分别转发每个属性或事件的历史数据。

设备批量上报属性、事件

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
                }
            ]
        }
    }
}

Alink响应数据格式:

  • 成功返回示例:

    {
        "code": 200,
        "data": {},
        "id": "123",
        "message": "success",
        "method": "thing.event.property.batch.post",
        "version": "1.0"
    }
  • 失败返回示例:

    {
        "code": 9201,
        "data": {},
        "id": "123",
        "message": "device offLine",
        "method": "thing.event.property.batch.post",
        "version": "1.0"
    }

参数说明:

表 13. 请求参数说明

参数

类型

说明

id

String

消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

version

String

协议版本号,目前协议版本号唯一取值为1.0。

sys

Object

扩展功能的参数,其下包含各功能字段。

说明

使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。

ack

Integer

sys下的扩展功能字段,表示是否返回响应数据。

  • 1:云端返回响应数据。

  • 0:云端不返回响应数据。

重要

该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

method

String

请求方法。取固定值:thing.event.property.batch.post

params

Object

请求参数。

properties

Object

属性,包含属性标识符、属性值value和属性生成的时间time

如以上示例中,设备上报了的两个属性Power(电源)和WF(工作电流)的批量信息。

如果是自定义模块属性,属性标识符格式为${模块标识符}:${属性标识符}(中间为英文冒号)。例如:

"test:Power": {
    "value": "on",
    "time": 1524448722000
}

events

Object

事件,包含事件标识符、事件输出参数value和事件生成的时间time

如以上示例中,上报了事件alarmEvent(告警事件)及对应事件参数Power(电源)和WF(工作电流)的批量信息。

如果是自定义模块事件,事件标识符格式为${模块标识符}:${事件标识符}(中间为英文冒号)。例如:

"test:alarmEvent": {
    "value": {
        "Power": "on", 
        "WF": "2"
    }, 
    "time": 1524448722000
}
表 14. 响应参数说明

参数

类型

说明

id

String

消息ID号,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

code

Integer

结果状态码,具体参考设备端通用code

data

Object

请求成功时,返回的数据固定为空。

message

String

返回结果信息。请求成功时,返回success。

method

String

响应数据对应的请求方法,与请求参数中method相同。

version

String

协议版本号,与请求参数中version相同。

错误码说明:物联网平台可能返回给设备端的错误码及说明,请参见设备端接收的错误码

消息转发说明:设备批量上报至平台的物模型数据,可以通过服务端订阅转发到您的服务器。属性和事件数据分为两条消息进行转发,具体Topic和数据格式,请参见设备属性批量上报设备事件批量上报

相关文档

物模型的属性上报、历史数据上报、批量属性上报有什么区别