Dante Cloud 微服务平台

外观

设备属性、事件、服务

约 2842 字大约 9 分钟

2026-07-17

背景信息

提示

物模型（属性、事件、服务）数据格式，请参见 什么是物模型。

当您为产品定义物模型后，设备需要按照 Link JSON 格式上报 属性 或 事件。

重要

  • 物模型功能定义数据类型为 float 或 double 时，对应参数值（即使值为整数）至少携带一位小数位。例如 10.0、 11.1。
  • 设备上报物模型属性和事件数据时，仅支持上报未来24小时内的数据。若上报的time超过该时间范围，上报会失败。
  • 设备上、下行通信中的消息ID（id）在当前设备中具有唯一性，且在每天内的消息中保证唯一即可。
  • 物联网平台云端下行消息中id用于异步下行消息匹配设备端的返回响应，由物联网平台系统保证每天的唯一性。设备端上行消息中id需由设备端自行保证每天的唯一性。

设备上报属性(上行)

[1]Topic

用途Topic
请求sys/${productKey}/${deviceName}/thing/event/property/post
响应sys/${productKey}/${deviceName}/thing/event/property/post_reply

[2]数据格式

请求数据格式示例

{
  "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"
}

响应数据格式示例

  • 成功返回示例
{
  "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"
}

[3]参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。
说明
使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。
  • 1：云端返回响应数据。
  • 0：云端不返回响应数据。
如果未配置该功能，则无此参数，云端默认返回响应数据。
methodString请求方法。例如：thing.event.property.post。
paramsObject请求参数。如以上示例中的两个参数Power（电源）和WF（工作电流）的信息。
{
  "Power": {
    "value": "on",
    "time": 1524448722000
  },
  "WF": {
    "value": 23.6,
    "time": 1524448722000
  }
}
valueObject上报的属性值。
timeLong属性上报时间戳，类型为UTC毫秒级时间。
该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。

表：请求参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，与请求参数中version相同。
methodString响应数据对应的请求方法，与请求参数中method相同。
codeInteger结果状态码。 具体参考设备端通用code。说明:物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。
dataObject请求成功时，返回的数据固定为空。

表：响应参数说明

设置设备属性(下行)

重要

设置设备属性成功，只表示物联网平台云端下发属性设置请求成功，不保证设备端执行了该请求。所以设备端SDK成功响应云端设置设备属性值的请求后，需上报对应属性值，设备属性值才能真正设置成功。设备上报属性说明，请参见本文“设备上报属性”。

[1]Topic

用途Topic
请求sys/${productKey}/${deviceName}/thing/service/property/set
响应sys/${productKey}/${deviceName}/thing/service/property/set_reply

[2]数据格式

请求数据格式示例

{
  "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]参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
methodString请求方法。例如：thing.service.property.set。
paramsObject属性设置参数。如以上示例中，设置属性：{ "temperature": "30.5" }。

表：请求参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，与请求参数中version相同。
methodString响应数据对应的请求方法，与请求参数中method相同。
codeInteger结果状态码。 具体参考设备端通用code。说明:物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。
dataObject请求成功时，返回的数据固定为空。

表：响应参数说明

设备上报事件(上行)

[1]Topic

用途Topic
请求sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post
响应sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post_reply

[2]数据格式

请求数据格式示例

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

响应数据格式示例

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

[3]参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。
说明
使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。
  • 1：云端返回响应数据。
  • 0：云端不返回响应数据。
如果未配置该功能，则无此参数，云端默认返回响应数据。
methodString请求方法。例如：thing.event.${tsl.event.identifier}.post.post。
paramsObject上报事件的输出参数。
valueObject事件的输出参数信息。如以上示例中的两个参数Power（电源）和WF（工作电流）的信息。
{
  "Power": {
    "value": "on",
    "time": 1524448722000
  },
  "WF": {
    "value": 23.6,
    "time": 1524448722000
  }
}
timeLong属性上报时间戳，类型为UTC毫秒级时间。
该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。
  • 若上传time，物联网平台的云端保存上传的时间作为属性上报时间。
  • 若不上传time，物联网平台的云端自动生成属性上报时间并保存。

表：请求参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，与请求参数中version相同。
methodString响应数据对应的请求方法，与请求参数中method相同。
codeInteger结果状态码。 具体参考设备端通用code。说明:物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。
dataObject请求成功时，返回的数据固定为空。

表：响应参数说明

[4]格式示例

假设产品中定义了一个alarm事件，它的TSL描述如下：

{
  "schema": "https://192.168.101.10:8847/schema.json",
  "link": "sys/${productKey}/air/thing/",
  "profile": {
    "productKey": "${productKey}",
    "deviceName": "air"
  },
  "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"
    }
  ]
}

当设备上报事件时，Link请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "params": {
    "value": {
      "errorCode": "error"
    },
    "time": 1524448722000
  },
  "method": "thing.event.alarm.post"
}

设备服务调用(下行)

[1]Topic

用途Topic
请求sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}
响应sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}_reply

[2]数据格式

请求数据格式示例

{
  "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"
}

[3]参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
methodString请求方法。例如：thing.service.${tsl.service.identifier}。
paramsObject服务调用参数。包含服务标识符和服务的值。如以上示例中的两个参数Power（电源）和WF（工作电流）的信息。
{
  "Power": {
    "value": "on",
    "time": 1524448722000
  },
  "WF": {
    "value": 23.6,
    "time": 1524448722000
  }
}

表：请求参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，与请求参数中version相同。
methodString响应数据对应的请求方法，与请求参数中method相同。
codeInteger结果状态码。 具体参考设备端通用code。说明:物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。
dataObject请求成功时，返回的数据固定为空。

表：响应参数说明

[4]格式示例

例如产品中定义了服务SetWeight，它的TSL描述如下：

{
  "schema": "https://192.168.101.10:8847/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"
    }
  ]
}

当调用服务时，Link请求数据格式：

{
  "method": "thing.service.SetWeight",
  "id": "105917531",
  "params": {
    "NewWeight": 100.8
  },
  "version": "1.0"
}

Link响应数据格式：

{
    "id": "105917531",
    "code": 200,
    "data": {
        "CollectTime": "1536228947682",
        "OldWeight": 100.101
    }
    "message": "success",
    "version": "1.0"
}

贡献者

码匠君

🎉 公告

  1. Dante Cloud 升级 Spring Boot 4 经验分享
  2. Dante Cloud 核心组件库 Dante Engine 正式回归开源
  3. Dante Cloud 4.1.0.0 发布，Spring Boot 3 已落幕，启航新征程
  4. Dante Cloud v4.1.0.4 发布，欢迎体验。
  5. 关注我，了解更多技术内幕！
码匠君公众号