MQTT 是一种轻量级发布/订阅消息传递协议，专为资源受约束的设备而设计。
本文介绍如何将 MQTT 客户端连接到服务，以便客户端可以发布和订阅消息。
连接参数
WebSocket 连接 URI：wss://{serviceName}.webpubsub.azure.com/clients/mqtt/hubs/{hub}?access_token={token}。
- {hub} 是必需的参数，为不同的应用程序提供隔离。
- {token} 默认是必需的。 或者，可以用格式
Authorization将令牌包含在Bearer {token}标头中。 可以通过启用对中心的匿名访问来绕过令牌要求。
如果客户端库不接受 URI，则可能需要将 URI 中的信息拆分为多个参数：
- 主机：
{serviceName}.webpubsub.azure.com - 路径：
/clients/mqtt/hubs/{hub}?access_token={token} - 端口： 443
- 传输：使用 TLS 加密的 WebSocket。
在 MQTT 客户端中，存在一些你应遵循的限制，否则将会拒绝连接。 这些 MQTT 协议参数包括：
- 协议版本：3.1.1 或 5.0。
- 客户端 ID 格式
- 允许使用的字符：0-9、a-Z、A-Z
- 长度介于 1 和 128 之间
- MQTT 3.1.1 的保活动隔：1 - 180 秒
- 遗嘱主题格式：不为空，并且至少包含一个非空白字符。 最大长度为 1024。
- 遗嘱消息大小：最多 2,000 个字节
默认情况下，MQTT 客户端没有任何权限发布或订阅任何主题。 需要向 MQTT 客户端授予权限。
权限
一个客户端只有在授权这样做时才可发布到其他客户端。 可以在客户端连接时或在连接的持续期间授予其权限。
| 角色 | 许可 |
|---|---|
| 未指定 | 客户端可以发送事件请求。 |
webpubsub.joinLeaveGroup |
客户端可以加入或退出任何组。 |
webpubsub.sendToGroup |
客户端可以向任何组发布消息。 |
webpubsub.joinLeaveGroup.<group> |
客户端可以加入或退出 <group> 组。 |
webpubsub.sendToGroup.<group> |
客户端可以向 <group> 组发布消息。 |
webpubsub.joinLeaveGroups.<pattern> |
用户可以加入/离开名称匹配 <pattern> 的任何组（请参阅 通配符组角色模式）。 |
webpubsub.sendToGroups.<pattern> |
客户端可将消息发布至名称匹配 <pattern> 的任意群组（详见 通配符群组角色模式）。 |
身份验证和授权
Web PubSub 支持使用两种工作流对 MQTT 客户端进行身份验证和授权，以便其具有适当的权限。
这些工作流可以单独使用，也可以一起使用。 如果将它们一起使用，则后一工作流中的身份验证结果会被服务接受。
1.JWT 工作流
这是默认工作流，如下所示：
- 客户端与身份验证服务器协商。 身份验证服务器包含的授权中间件可处理客户端请求，并对 JWT 进行签名，以使客户端连接到服务。
- 身份验证服务器将 JWT 返回到客户端。
- 客户端尝试使用从身份验证服务器返回的 JWT 连接到 Web PubSub 服务。 可以将令牌以
/clients/mqtt/hubs/{hub}?access_token={token}形式置于查询字符串中，或以Authorization形式置于Authorization: Bearer {token}标头中。
支持的声明
还可以通过在 JWT 中指定特殊声明，在生成访问令牌时配置客户端连接的属性：
| 说明 | 声明类型 | 声明值 | 备注 |
|---|---|---|---|
| 客户端连接最初具有的权限 | role |
权限中定义的角色值 | 如果客户端具有多个权限，请指定多个 role 声明。 |
| 令牌的生存期 | exp |
过期时间 |
exp（过期时间）声明标识了一个时间，在该时间或之后，令牌不应被接受处理。 |
| 客户端连接到 Azure Web PubSub 后加入的初始组 | group |
要加入的群组 | 如果客户端加入多个组，请指定多个 group 声明。 |
用于客户端连接的 userId |
sub |
用户ID (userId) | 只允许一个 sub 声明。 |
服务器 SDK 提供用于为 MQTT 客户端生成访问令牌的 API。 请注意，必须将客户端协议指定为 Mqtt.
- 请按照服务器 SDK 入门指南来创建
WebPubSubServiceClient对象service
注释
自版本 1.1.3 起，支持生成 MQTT 客户端访问 URL。
通过调用
WebPubSubServiceClient.getClientAccessToken来生成客户端访问 URL：let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });
2.上游服务器工作流
MQTT 客户端在与服务建立 WebSocket 连接后发送 MQTT CONNECT 数据包，然后服务调用上游服务器中的 API。 上游服务器可以根据 MQTT 连接请求中的用户名和密码字段以及来自客户端的 TLS 证书对客户端进行身份验证。
此工作流需要显式配置。
- 若要详细了解如何使用上游服务器对客户端进行身份验证，请参阅如何配置事件处理程序
故障排除
如果连接失败或无法发布或订阅消息，请检查服务的原因代码/返回代码，或参阅如何使用资源日志进行故障排除。