如果产品定义了物模型,设备可以按照属性、事件、服务协议分别上报数据。物模型(属性、事件、服务)数据格式请参考物模型数据格式文档。本文仅讲解如何上报数据。

设备的数据上报方式有两种:ICA标准数据格式 (Alink JSON)和透传/自定义。两者二选一,推荐您使用Alink JSON方式。
  • ICA 标准数据格式 (Alink JSON):设备按照物联网平台定义的标准数据格式生成数据,然后上报数据。具体格式,请参见本文示例。
  • 透传/自定义:设备上报原始数据如二进制数据流,阿里云物联网平台会运行您在控制台提交的数据解析脚本,将原始数据转成标准数据格式后,再进行业务处理。而云端返回的是标准Alink JSON格式,返回结果经数据解析后,再推送给设备。

设备上报属性

上行(透传)

  • 请求Topic:/sys/{productKey}/{deviceName}/thing/model/up_raw
  • 响应Topic:/sys/{productKey}/{deviceName}/thing/model/up_raw_reply

请求数据为设备上报的原始报文,示例如下。

说明 上报数据中需包含请求方法method参数。
0x020000007b00

云端返回数据格式如下:

{
    "id":"123",
    "code":200,
    "data":{}
}

上行(Alink JSON)

  • 请求Topic: /sys/{productKey}/{deviceName}/thing/event/property/post
  • 响应Topic: /sys/{productKey}/{deviceName}/thing/event/property/post_reply

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "Power": {
      "value": "on",
      "time": 1524448722000
    },
    "WF": {
      "value": 23.6,
      "time": 1524448722000
    }
  },
  "method": "thing.event.property.post"
}
表 1. 请求参数说明
参数 类型 说明
id String 消息ID号。需定义为String类型的数字,且设备维度唯一。
version String 协议版本号,目前协议版本号为1.0
method String 请求方法。取值:thing.event.property.post
params Object 请求参数。如以上示例中,设备上报了的两个属性Power和WF。具体属性信息,包含属性上报时间(time)和上报的属性值(value)。
time Long 属性上报时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。
value object 上报的属性值。

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": {}
}
表 2. 响应参数说明
参数 类型 说明
id String 消息ID号,String类型的数字。
code Integer 结果状态码。 具体参考设备端通用code
data String 请求成功时,返回的数据。
表 3. 错误码
错误码 消息 描述
460 request parameter error 请求参数错误。
6106 map size must less than 200 一次最多只能上报200条属性。
6313 tsl service not available

物模型校验服务不可用。

物联网平台根据您定义的TSL中属性格式,校验上报的属性信息。

校验后,将过滤掉不合格的属性,仅保留合格属性。即使全部属性都被过滤,也代表着校验成功。

若校验服务不可用,报6313错误码。

设备上报至平台的属性信息,可以使用规则引擎数据流转功能,转发至其他云产品。具体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

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "temperature": "30.5"
  },
  "method": "thing.service.property.set"
}
表 4. 请求参数说明
参数 类型 说明
id String

消息ID号,由物联网平台生成。

version String 协议版本号,目前协议版本号为1.0
params Object 属性设置参数。如以上示例中,设置属性:{ "temperature": "30.5" }
method String 请求方法,取值thing.service.property.set

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": {}
}
表 5. 响应参数说明
参数 类型 说明
id String 消息ID号,String类型的数字。
code Integer 结果状态码, 具体参考设备端通用code
data String 请求成功时,返回的数据。

您可以使用规则引擎数据流转功能,将属性设置返回的结果,转发至其它云产品。具体Topic和数据格式请参考设备下行指令结果数据流转

设备事件上报

上行(透传)

  • 请求Topic:/sys/{productKey}/{deviceName}/thing/model/up_raw
  • 响应Topic:/sys/{productKey}/{deviceName}/thing/model/up_raw_reply

请求数据为设备上报的原始报文,示例如下。

0xff0000007b00

云端返回数据格式如下:

{
    "id":"123",
    "code":200,
    "data":{}
}

上行(Alink JSON)

  • 请求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",
  "params": {
    "value": {
      "Power": "on",
      "WF": "2"
    },
    "time": 1524448722000
  },
  "method": "thing.event.{tsl.event.identifier}.post"
}
表 6. 请求参数说明
参数 类型 说明
id String 消息ID号。需定义为String类型的数字,且设备维度唯一。
version String 协议版本号,目前协议版本号为1.0
method String 请求参数。取值:thing.event.{tsl.event.identifier}.post
params List 上报事件的参数。
value Object 具体的事件信息。如以上示例中
{
      "Power": "on",
      "WF": "2"
    }
time Long 事件生成的时间戳,类型为UTC毫秒级时间。

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

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": {}
}
表 7. 响应参数说明
参数 类型 说明
id String 消息ID号,String类型的数字。
code Integer 结果状态码,具体参考设备端通用code
说明 物联网平台会对设备上报的事件做校验。通过产品的TSL描述判断上报的事件是否符合定义的事件格式。不合格的事件会直接被过滤掉,并返回失败的错误码。
data String 请求成功时,返回的数据。

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和数据格式,请参考设备上报事件

设备服务调用

下行(透传)

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

服务调用方式

支持同步调用和异步调用。物模型定义服务时,需设置此项。
  • 同步方式:物联网平台直接使用RRPC同步方式下行推送请求。设备RRPC的集成方式,请参见什么是RRPC
  • 异步方式:物联网平台则采用异步方式下行推送请求,设备也采用异步方式返回结果。

    只有当前服务选择为异步调用方式,物联网平台才会订阅该异步响应Topic。异步调用的结果,可以使用规则引擎数据流转功能获取。对应Topic和数据格式,请参考设备下行指令结果

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "Power": "on",
    "WF": "2"
  },
  "method": "thing.service.{tsl.service.identifier}"
}
表 8. 请求参数说明
参数 类型 说明
id String

消息ID号,由物联网平台生成。

version String 协议版本号,目前协议版本号为1.0
params Map 服务调用参数。包含服务标识符和服务的值。如以上示例中:
{
      "Power": "on",
      "WF": "2"
    }
method String 请求方法:thing.service.{tsl.service.identifier}
说明 {tsl.service.identifier}为物模型中定义的服务标识符(Identifier)。请参见新增物模型

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": {}
}
表 9. 返回参数说明
参数 类型 说明
id String 消息ID号,String类型的数字。
code Integer 结果状态码,具体参考设备端通用code
data String 返回的结果信息。

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.0"
}

Alink响应数据格式:

{
  "id": "105917531",
  "code": 200,
  "data": {
    "CollectTime": "1536228947682",
    "OldWeight": 100.101
  }
}

网关批量上报数据

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

说明
  • 一次最多可上报200个属性,20个事件。
  • 子设备数据条数限制为20。

上行(透传)

  • 请求Topic:/sys/{productKey}/{deviceName}/thing/model/up_raw
  • 响应Topic:/sys/{productKey}/{deviceName}/thing/model/up_raw_reply

请求数据为设备上报的原始报文,示例如下。

0xff0000007b00

云端返回数据格式如下:

{
  "id": "123",
  "code": 200,
  "data": {}
}

上行(Alink JSON)

  • 请求Topic:/sys/{productKey}/{deviceName}/thing/event/property/pack/post
  • 响应Topic:/sys/{productKey}/{deviceName}/thing/event/property/pack/post_reply

Alink 请求数据格式:

{
  "id": "123",
  "version": "1.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"
}
表 10. 请求参数说明
参数 类型 说明
id String 消息ID号。需定义为String类型的数字,且设备维度唯一。
version String 协议版本号,目前协议版本号为1.0
params Object 请求参数。
properties Object 属性,包含属性标识符、属性值(value) 和属性生成的时间(time)。

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

events Object 事件,包含事件标识符、事件值(value) 和事件生成的时间(time)。

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

subDevices Object 子设备信息。
productKey String 子设备产品key。
deviceName String 子设备名称。
method String 请求参数。取值:thing.event.property.pack.post

Alink 响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": {}
}
表 11. 响应参数说明
参数 类型 说明
id String 消息ID,String类型的数字。
code Integer 返回结果,200代表成功。
说明 系统会校验设备、拓扑关系、及上报的属性和事件都否符合产品物模型(TSL)中的定义。如果其中任何一项校验不通过,则上报数据失败。
data Object 请求成功时的返回结果。