什么是Topic

什么是Topic

在发布/订阅消息的MQTT协议中，Topic用于定义消息传输的通道和路径，设备通过Topic将消息发布到物联网平台，物联网平台将消息发送给订阅Topic的设备。为方便海量设备基于Topic进行通信，简化授权操作，物联网平台定义了产品Topic类和设备Topic。本文介绍MQTT协议的原理、Topic的概念及分类。

工作原理

在上图中分为设备、物联网平台和业务服务器三端，其中设备和物联网平台的通信基于MQTT协议。设备、业务服务器、物联网平台的通信过程请参见使用Topic通信。

• MQTT（Message Queuing Telemetry Transport）是一种基于发布/订阅模型的消息传输协议，具有低开销、高拓展、协议简单、双向通信等优点，可以利用较少的设备资源和网络资源实现可靠、高效的长连接，被广泛应用于物联网领域。目前物联网平台支持5.0、3.1.1和3.1版本MQTT协议，协议规范请参见MQTT协议规范。
• MQTT客户端（Client）和MQTT代理者（Broker）。
  • MQTT客户端（Client）：本文的客户端（Client）指接入物联网平台的设备。设备和用户的服务器不直接建立连接，而是通过代理者（Broker）进行通信。
  • MQTT代理者（Broker）：本文的MQTT代理者（Broker）指阿里云物联网平台。代理者（Broker）是设备和业务服务器消息通信的中介，解耦了设备和业务服务器，实现了设备和业务服务器之间的异步通信。
• MQTT协议消息的组成部分
  • 主题（Topic）：使用正斜杠（/）作为分隔符构造字符串，例如/${productKey}/${deviceName}/user/update，订阅该Topic的所有设备都会收到消息。
  • 消息内容（Payload）：消息的具体内容。
• MQTT协议消息的传输过程，以业务服务器向设备下发消息为例
  1. 设备订阅相应的主题（Topic）。
  2. 服务器发送消息给物联网平台。
  3. 物联网平台接收消息，根据消息的主题（Topic）确定设备并发送消息。
  4. 业务服务器收到物联网平台的消息，确认消息已成功发送。
• MQTT协议的重要参数，更多参数请参见MQTT协议规范。
  • 消息服务质量（QoS）：QoS=0代表物联网平台只推送一次消息给订阅者，QoS=1代表订阅者收到消息后必须返回puback给发布者，否则会一直推送消息。更多信息，请参见订阅选项。
  • 保活时间：当设备发起连接时会向物联网平台发送CONNECT消息，物联网平台使用CONNACK消息进行响应并保持连接，设备在保活时间间隔内至少需要发送一次报文，否则物联网平台会断开与设备的连接。更多信息，请参见MQTT保活和使用示例。
  • 清除会话：设备和物联网的会话状态是临时或持久。更多信息，请参见会话过期。

使用限制

Topic相关、设备接入、连接通信等使用限制，请参见使用限制。

Topic类型

详细的Topic说明，请参见本文末尾的Topic分类和通信说明。

• 基础通信Topic：设备使用物联网平台的物模型通信、OTA升级、任务管理等功能，必须使用的Topic。
• 物模型Topic：物模型是对设备实际功能的抽象，从属性、服务和事件三个维度，分别描述了该实体是什么、能做什么、能提供什么信息。例如智能风扇的开关状态是属性，开关的操作是服务，报警是事件。物模型的概念和使用，请参见什么是物模型。
• 自定义Topic：如果物模型不能满足您的业务需求，可以使用自定义Topic，自定义Topic的前三个类目/ProductKey/${deviceName}/user已固定。管理和使用自定义Topic的操作，请参见使用自定义Topic通信。

产品Topic类和设备Topic的概念

• 基础通信Topic和物模型Topic由物联网平台定义，以/sys、/ota或/shadow开头。使用物模型Topic通信，需要先在产品下创建物模型。请参见单个添加物模型或批量添加物模型。

• 自定义Topic需要用户自行创建。产品的自定义Topic类、设备Topic的关系如下图：

  

  1. 每个产品只有一个ProductKey，每个ProductKey下有多个Topic类，每个Topic类对ProductKey下所有设备通用。

  2. 产品Topic类是同一产品下所有设备的相同功能Topic的集合，以/${productKey}/${deviceName}开头。

     1. Topic类的功能。

        Topic类以正斜线（/）开头并分隔每个类目，例如：/${productKey}/${deviceName}/user/update，${productKey}和${deviceName}为固定类目，前缀、后缀类目用于区分不同功能的消息。

        • ${productKey}表示产品的标识符ProductKey。在指定产品的Topic类中，需替换为具体产品的ProductKey值例如a19mzP****。
        • ${deviceName}表示设备名称。在产品Topic类中，${deviceName}代表该产品下所有设备，不需要替换为实际设备名称。

     2. Topic类的操作权限。权限的主体是设备，发布权限代表设备向该Topic类下的设备Topic发布消息，订阅权限代表设备接收物联网平台的数据。

        • 服务器接收设备数据，需要设置Topic类的权限为发布。

        • 服务器向设备下发数据，需要设置Topic类的权限为订阅。

          说明

          定义产品Topic类后，需要设备主动订阅具有订阅权限的Topic，相应Topic才会出现在设备详情页的Topic列表页签。设备订阅Topic的操作，请参见使用Topic通信。

  3. 设备Topic。添加设备后，产品的所有自定义Topic类会自动映射到设备上，生成具体的设备Topic。产品Topic类定义的操作权限，会映射到具体的设备Topic。在产品Topic类基础上，使用具体的设备名称例如device1替换产品Topic类中的${deviceName}，得到设备Topic例如：/a19mzP****/device1/user/update。

  4. 设备Topic归属于对应的设备，可用于消息通信。基于Topic的通信过程请参见使用Topic通信。

定义设备Topic的流程

1. 在物联网平台控制台，创建产品。具体操作，请参见创建产品。

   创建产品后，物联网平台为该产品预定义了Topic类，包含基础通信Topic、物模型通信Topic和自定义Topic。在产品详情页面，单击Topic类列表页签，查看各功能及其Topic类。

2. 为产品添加设备。具体操作，请参见创建设备。

3. 创建产品的自定义Topic类。具体操作，请参见使用自定义Topic通信。

Topic分类和通信说明

物联网平台预定义的产品Topic类对应的设备Topic包含基础通信Topic、物模型通信Topic和自定义Topic三种类型，详细说明见下表。

类型	Topic类及数据格式	说明
基础通信Topic	OTA升级	设备OTA升级消息的Topic，包括设备上报OTA模块版本、物联网平台推送升级包信息、设备上报升级进度和设备请求获取最新升级包信息。
设备标签	上报设备标签的Topic，上报设备的部分信息，如厂商、设备型号等。
时钟同步	NTP服务同步请求和响应的Topic，解决嵌入式设备资源受限，系统不包含NTP服务，端上没有精确时间戳的问题。
设备影子	设备影子数据通过Topic进行流转，包括设备影子发布和设备接收影子变更。
配置更新	设备主动请求配置信息和物联网平台推送配置信息的Topic。开发人员可在不用重启设备或中断设备运行的情况下，在线远程更新设备的系统参数、网络参数等配置信息。
广播	广播Topic。调用云端API PubBroadcast向订阅了该Topic的所有设备发送广播消息，实现批量控制设备。
物模型通信Topic	属性上报	各物模型功能的Topic。说明在物联网平台，不可以调用Pub接口向物模型通信Topic发送消息。在物联网平台的云端，通过物模型功能远程控制设备，请调用SetDeviceProperty或SetDevicesProperty设置设备属性值；调用InvokeThingService或InvokeThingsService调用设备服务。
属性设置
事件上报
服务调用
自定义Topic	自定义Topic类及格式	系统默认提供了3个自定义Topic类。您可根据业务需求，自定义Topic类。Topic类是一个Topic模板配置，编辑更新某个Topic类后，可能对产品下所有设备使用该类Topic通信产生影响。建议在设备研发阶段设计好，设备上线后不再变更Topic类。

相关文档

• 定义Topic后，设备、物联网平台、服务端、其他云产品间的通信方式请参见使用Topic通信。更多通信方式，请参见物联网平台通信方式概述。
• 设备接入、物模型使用的入门视频，请参见设备接入。
• 不同协议、不同类型设备接入物联网平台的流程，请参见设备接入概述。设备端Link SDK的下载方式，请参见设备接入Link SDK。
• 物模型Topic数据自动写入时序数据存储空间，管理物模型数据存储的操作请参见关闭或开启物模型数据存储。
• 如果需要存储自定义Topic数据用于查询，必须先创建时序数据存储规则。操作步骤，请参见配置自定义Topic数据存储。

常见问题

• 物模型相关问题
• 消息通信相关问题
• Link SDK运行相关问题