Xlink协议

2025/10/12大约 3 分钟

Xlink协议

设备影子

设备影子数据通过Topic进行流转，主要包括设备上报状态到设备影子、应用程序更改设备状态、设备离线再上线后主动获取设备影子信息，和设备端请求删除设备影子中的属性信息。

设备影子Topic

物联网平台已为每个设备预定义了两个Topic，用于实现设备影子数据流转。

/shadow/update/${YourProductKey}/${YourDeviceName} 设备和应用程序发布消息到此Topic。物联网平台收到该Topic的消息后，将消息中的状态更新到设备影子中。

/shadow/get/${YourProductKey}/${YourDeviceName} 设备影子更新状态到该Topic，设备订阅此Topic获取最新消息。

设备主动获取影子内容

若应用程序发送指令时，设备离线。设备再次上线后，将主动获取设备影子内容。

主动发送以下消息到Topic /shadow/update/a1PbRCF****/dex*****中，请求获取设备影子中保存的最新状态。

{
    "method": "get"
}

当设备影子收到这条消息后，发送最新状态到Topic /shadow/get/a1PbRCF****/dex*****``。设备通过订阅该Topic获取最新状态。消息内容如下：

{
    "method": "reply", 
    "payload": {
        "status": "success", 
        "state": {
            "reported": {
                "color": "red"
            }, 
            "desired": {
                "color": "green"
            }
        }, 
        "metadata": {
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }, 
            "desired": {
                "color": {
                    "timestamp": 1469564492
                }
            }
        }
    }, 
    "version": 2, 
    "timestamp": 1469564576
}

设备日志上报

物联网平台支持设备将本地日志上报到云端，在控制台进行查询和故障分析。

设备获取日志配置

数据上行。

请求Topic：/sys/${productKey}/${deviceName}/thing/config/log/get。
响应Topic：/sys/${productKey}/${deviceName}/thing/config/log/get_reply。

Xlink请求数据格式：

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
    },
    "params" : {
        "configScope":"device",  
        "getType":"content"
     },
    "method":"thing.config.log.get"
}

Xlink响应数据格式：

{
    "id":"123",
    "version":"1.0",
    "code":200,
    "data" :{ 
        "getType":"content",
        "content":{
            "mode":0 
        }
    }
}

mode	Integer	设备日志上报模式，0表示设备SDK不上报日志， 1表示设备SDK上报日志。

设备接收订阅云端推送日志配置

数据下行。

Topic：/sys/${productKey}/${deviceName}/thing/config/log/push。

Xlink配置推送数据格式：

{
    "id":"123",
    "version":"1.0",
    "params" :{ 
        "getType":"content",
        "content":{
            "mode":0
        }
    }
}

mode	Integer	设备日志上报模式，0表示设备SDK不上报日志，1表示设备SDK上报日志。

设备上报日志内容

数据上行。

请求Topic：/sys/${productKey}/${deviceName}/thing/log/post。
响应Topic：/sys/${productKey}/${deviceName}/thing/log/post_reply。

Xlink请求数据格式

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
    },
    "params" :[{
          "utcTime":  "2020-03-06T15:15:27.464+0800",  
          "logLevel": "ERROR",      
          "module": "ModuleA",     
          "code" :"4103",                   
          "traceContext": "123456",  
          "logContent" : "some log content" 
         }], 
    "method" : "thing.log.post"
}

params参数

utcTime	String	日志的采集时间，为设备本地UTC时间，包含时区信息，以毫秒计，格式为“yyyy-MM-dd'T'HH:mm:ss.SSSZ”。可上报其它字符串格式，但不利于问题排查，不推荐使用。
logLevel	String	日志级别。可以使用默认日志级别，也可以自定义日志级别。默认日志级别从高到低为：* FATAL* ERROR* WARN* INFO* DEBUG
module	String	模块名称：* 当设备端使用Android SDK时，模块名称为ALK-LK。* 当设备端使用C SDK时，需自定义模块名称。* 当设备端使用自行开发的SDK时，需自定义模块名称。
code	String	结果状态码，Sting类型的数字。
traceContext	String	可选参数，上下文跟踪内容，设备端使用Alink协议消息的id，App端使用TraceId（追踪ID）。
logContent	String	日志内容详情。

Xlink响应数据格式：

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