调用MQTT API时,需要根据MQTT Topic格式定义Topic。

MQTT Topic格式

MQTT Topic格式如下所示。每级字段长度上限为128字节。

{srcApp}/{messageType}/{destApp}/{method}

各级字段说明如下所示。

参数 说明
{srcApp} 表示发布消息的应用程序(以下简称APP)身份。如果消息是由Link IoT Edge发布,则对应的{srcApp}linkedge;如果消息是由其它APP发布,则{srcApp}是该APP的关键字名称,例如ibms

Topic中包含消息发布者的身份有以下几点优势:

  • 隔离广播域:避免响应消息被其它模块接收。
  • 溯源:排查问题时可以根据Topic信息,定位到请求发起者的身份。
  • 身份验证:{srcApp}字段可用于填写系统颁发的AppID(用于权限验证)。
{messageType} 表示消息的类型,目前仅支持三种:
  • request: 表示消息为请求消息。
  • response:表示消息为响应消息。
  • notify:表示消息为事件通知消息。此类消息用于广播推送,所有订阅该Topic的APP都可以收到推送信息。
{destApp} 表示消息目标,用于指定请求的目标APP。如果请求linkedge的服务,则对应的{destApp}为linkedge;如果请求其它APP服务,则为该APP的关键字名称。当{messageType}为notify时,不需要{destApp}字段。
{method} 表示方法名,例如,可用getDeviceList表示获取设备信息列表。

基于MQTT的方法调用

基于MQTT的方法调用,通常会定义一对“请求”和“响应”Topic。应用程序需要调用服务的方法时,需要先订阅响应Topic,再向请求Topic发送请求,才能正常获取服务的响应信息。

订阅响应Topic时,对设备的ProductKey、DeviceName和请求方法可以使用通配符

下文以读取设备属性为例,响应Topic配置为thing/response/testApp/+/+/+,只需订阅一次,后续访问任意设备的任何服务,都可以收到响应消息。

/* 1.先订阅响应Topic,用户接收设备响应数据 */
#./mosquitto_sub -u <your_username> -P <your_password> -p 8883 -t thing/response/testApp/+/+/+ -v &
/* 2.发送设备方法调用get请求 */
#./mosquitto_pub -u <your_username> -P <your_password> -p 8883 -t testApp/request/thing/YourProductKey/YourDeviceName/get -m "{\"params\":[\"MeasuredIlluminance\"],\"requestId\":\"ff8db62b-4d75-46c8-bf6a-1600d326****\"}"
/* 3.mosquitto_sub输出设备响应信息 */
thing/response/testApp/<YourProductKey>/<YourDeviceName>/get {"code":0,"message":"success","params":{"MeasuredIlluminance":1000},"requestId":"ff8db62b-4d75-46c8-bf6a-1600d326****"}

其中:

  • <your_username>:替换为云端开启MQTT API中设置的访问边缘Open API的用户名。
  • <your_password>:替换为云端开启MQTT API中设置的访问边缘Open API的密码。
  • <YourProductKey>:替换为设备的ProductKey。
  • <YourDeviceName>:替换为设备的DeviceName。

通用Payload格式如下所示。

Payload:
{
    "requestId":"消息标识",
    "timeout":超时时间,
    "timestamp":发起请求的时间,
    "version": "请求版本号",
    "params":{
        "key1":"value1",
        "key2":"value2"
    }
}
表 1. 参数说明
参数名称 类型 是否必选 描述
requestId String 用作消息标识。相同应用源每次发出的请求消息Token应该各不相同,消息标识可由UUID、随机数或自增长数值等组成。
注意 如果请求消息中没有填写requestId参数,该请求将被丢弃。
timeout Number 用于标识请求的超时时间,单位为秒,取值范围为1~120秒,默认值为4秒。Link IoT Edge处理请求时,若超过该设置时间仍未处理完成请求,那么Link IoT Edge会返回TIMEOUT的错误信息。
timestamp Number 用于标识请求的发起时间,单位为毫秒。
version String 用于标识请求的版本号。
params - - 每个接口中的params参数表示的内容不同,详情请参见具体的接口内容。