设备属性、事件、服务

2025/11/9大约 8 分钟

设备属性、事件、服务

物模型属性上报

请求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"
}

参数说明：

参数	类型	说明
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	见下方params说明
time	Long	属性上报时间戳，类型为UTC毫秒级时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。若上传time，物联网平台的云端保存上传的时间作为属性上报时间。若不上传time，物联网平台的云端自动生成属性上报时间并保存。
value	Object	上报的属性值。若不上传time，可不上传value，直接上传参数值即可。

params说明：

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

若仅传入属性值，无需上传字段time和value，params示例如下：

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

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

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

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

设置设备属性

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

Topic和数据格式（下行）：

数据格式（下行）	请求和响应Topic
Xlink 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"
}

参数说明：

请求参数说明

参数	类型	说明
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`。

响应参数说明

参数	类型	说明
id	String	消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
code	Integer	结果状态码，具体参考设备端通用code。
data	Object	请求成功时，返回的数据固定为空。
message	String	返回结果信息。请求成功时，返回success。
version	String	协议版本号，与请求参数中version相同。

设备上报事件

Topic和数据格式（上行）：

数据格式	请求和响应Topic
默认模块 Xlink JSON	请求Topic：`/sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post` 响应Topic：`/sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post_reply`

数据格式	请求和响应Topic
自定义模块 Xlink JSON	请求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`

以默认模块物模型为例，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"
}

若请求失败，返回 {}。

参数说明：

参数	类型	说明
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，物联网平台的云端自动生成事件上报时间并保存。

响应参数说明

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

服务调用（同步调用）

Topic	格式	说明
RRPC订阅	`/ext/rrpc/+/${topic}`	您需订阅物联网平台下发的RRPC请求消息中的自定义Topic。
RRPC请求消息	`/ext/rrpc/${messageId}/${topic}`	物联网平台下发的RRPC请求消息。
RRPC响应消息	`/ext/rrpc/${messageId}/${topic}`	设备上行的RRPC响应消息。

以上Topic格式中：

${topic}：您在物联网平台的完整自定义Topic，即为/${productKey}/{deviceName}/user/{TopicShortName}。其中${TopicShortName}为自定义的Topic类，即自定义Topic的后缀。更多信息，请参见自定义Topic。

${messageId}：服务端调用物联网平台的RRpc接口向设备下发消息时，物联网平台生成的唯一的RRPC消息ID，可用于区分不同的RRPC消息。例如设备device1的自定义Topica18wP***/device1/user/get，发起RRPC消息的Topic为/ext/rrpc/121307410***/a18wP***/device1/user/get。

对于物模型，则rrpc的topic：ext/rrpc/49076627285101****/sys/a18wP***/device1/thing/service/test，其中test:为服务名称

以下举例订阅：

    memset(topic_buff, 0, 120);
    snprintf(topic_buff, 120, "/ext/rrpc/+/sys/%s/%s/thing/service/+", "a18wP***", "device1");
    msg_id = esp_mqtt_client_subscribe(client, topic_buff, 1);

接收数据举例

TOPIC=/ext/rrpc/344342050114296994/sys/xCgOGN/a0b7658ad450/thing/service/test[2025-12-21 04:50:03.741]
DATA={"method":"thing.service.default:test","id":"344342050114296994","params":{"test1":12,"test2":12.7},"timestamp":1766307003582}[2025-12-21 04:50:03.760]

接收到该数据之后需要响应消息

TOPIC=/ext/rrpc/344342050114296994/sys/xCgOGN/a0b7658ad450/thing/service/test
DATA={"id":"344342050114296994","code":200,"data":{}}

服务调用（异步调用）

TOPIC=/sys/xCgOGN/a0b7658ad450/thing/service/gvredgvr:feswfes DATA={"id":"181658324017416411","params":