你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

MQTT 的 REST API 规范

本文档阐明了 MQTT 上下文中 Web PubSub 数据平面 REST API 的含义。 现有的 Web PubSub REST API 文档侧重于 Web PubSub 自己的协议，这可能会使其应用程序对 MQTT 不清楚。

术语映射

首先，请熟悉 Web PubSub 和 MQTT 之间的术语映射。 如果已熟悉这些术语，可以跳过本部分。

MQTT 术语	相应的 Web PubSub 术语	关系
服务器/MQTT 代理	Web PubSub 服务	Web PubSub 服务作为 MQTT 代理来提供 MQTT 连接服务。 请注意，在文档中，我们通常使用术语“服务器”而不是 MQTT 代理来指代上游服务器。
会话	连接	Web PubSub 中的“连接”是一个逻辑概念，表示客户端与服务之间的有状态关系。一个“连接”对应一个“会话”。 通常情况下，这两个单词可互换。
订阅主题	加入组	这两个操作效果相同：客户端会收到来自该主题或组的消息。 主题名称是组名称。
将消息发布到主题	将消息发送到组	这两个操作的效果相同：订阅该主题或属于该组的客户端会收到消息
客户端 ID	连接 ID	“连接 ID”标识到 Web PubSub 的“连接”。 我们使用“客户端 ID”作为 Web PubSub 中的 MQTT 连接的“连接 ID”。

操作映射

有关可用操作的综合列表，请参阅 REST API 参考。

REST API 操作分为以下组：

• 消息发送操作
• 订阅管理操作
• 权限管理操作
• 存在管理操作
• 客户端令牌生成操作

下面定义了其中每个类别。

消息发送操作

REST API 操作	对 MQTT 的影响
发送到组	订阅了使用组名称命名的主题的 MQTT 连接将收到消息。
发送到“全部” 发送给用户 发送到连接	相应的 MQTT 连接将收到包含主题 $webpubsub/server/messages的消息。

消息以 1 的 QoS 发布。 根据标准 MQTT 降级规则，根据客户端的订阅选项，可能会降级收到的消息的 QoS。

订阅管理操作

REST API 操作	对 MQTT 的影响
向组添加连接 将连接添加到组	为指定的连接添加订阅。
将用户添加到组	为指定用户的所有连接添加订阅。
从所有组中删除连接 从组中删除连接 从组中删除连接 从所有组中删除用户 从组中删除用户	删除指定连接或用户的一个或多个订阅。

组名称对应于 MQTT 主题筛选器。 将连接或用户添加到组时，将使用默认 MQTT 订阅选项。

权限管理操作

这些操作在 MQTT 的上下文中非常简单，因此忽略定义。

• 检查权限
• 授予权限
• 撤销权限

存在管理操作

REST API 操作	对 MQTT 的影响
连接存在 组存在 用户存在	检查指定的连接、用户或组是否存在会话。 请注意，这不同于检查连接当前是否处于联机状态。
关闭所有连接 关闭组连接 关闭用户连接	结束指定的会话并终止相应的物理连接。

客户端令牌生成操作

REST API 操作	对 MQTT 的影响
生成客户端令牌	生成要连接的 MQTT 客户端的连接令牌和 URL。

请注意，从 REST API 版本 2024-01-01开始，MQTT 支持可用。 必须为 MQTT 客户端指定查询参数 clientType=MQTT 。