如何将 MQTT 客户端连接到 Azure Web PubSub

MQTT 是一种轻量级发布/订阅消息传递协议，专为资源受约束的设备而设计。

本文介绍如何将 MQTT 客户端连接到服务，以便客户端可以发布和订阅消息。

连接参数

WebSocket 连接 URI：wss://{serviceName}.webpubsub.azure.com/clients/mqtt/hubs/{hub}?access_token={token}。

• {hub} 是必需的参数，为不同的应用程序提供隔离。
• {token} 默认是必需的。 或者，可以用格式 Bearer {token} 将令牌包含在 Authorization 标头中。 可以通过启用对中心的匿名访问来绕过令牌要求。

如果客户端库不接受 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> 组发布消息。

身份验证和授权

Web PubSub 支持使用两种工作流对 MQTT 客户端进行身份验证和授权，以便其具有适当的权限。

这些工作流可以单独使用，也可以一起使用。 如果将它们一起使用，则后一工作流中的身份验证结果会被服务接受。

1.JWT 工作流

这是默认工作流，如下所示：

1. 客户端与身份验证服务器协商。 身份验证服务器包含的授权中间件可处理客户端请求，并对 JWT 进行签名，以使客户端连接到服务。
2. 身份验证服务器将 JWT 返回到客户端。
3. 客户端尝试使用从身份验证服务器返回的 JWT 连接到 Web PubSub 服务。 可以将令牌以 /clients/mqtt/hubs/{hub}?access_token={token} 形式置于查询字符串中，或以 Authorization: Bearer {token} 形式置于 Authorization 标头中。

支持的声明

还可以通过在 JWT 中指定特殊声明，在生成访问令牌时为客户端连接配置属性：

说明	声明类型	声明值	说明
客户端连接最初具有的权限	role	权限中定义的角色值	如果客户端具有多个权限，请指定多个 role 声明。
令牌的生存期	exp	过期时间	exp（过期时间）声明指定只能在哪个时间（含）之前接受令牌的处理。
客户端连接连接到 Azure Web PubSub 后加入的初始组	group	要加入的组	如果客户端加入多个组，请指定多个 group 声明。
客户端连接的 userId	sub	userId	只允许一个 sub 声明。

还可以将自定义声明添加到访问令牌中，这些值将保留为连接上游请求正文中的 claims 属性。

服务器 SDK 提供用于为 MQTT 客户端生成访问令牌的 API。 请注意，必须将客户端协议指定为 Mqtt.

JavaScript

1. 按照服务器 SDK 入门创建 WebPubSubServiceClient 对象 service

注意

自版本 1.1.3 起，支持生成 MQTT 客户端访问 URL。

2. 通过调用 WebPubSubServiceClient.getClientAccessToken 来生成客户端访问 URL：

   let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });
   

C#

1. 按照服务器 SDK 入门创建 WebPubSubServiceClient 对象 service

注意

自版本 1.4.0 起，支持生成 MQTT 客户端访问 URL。

2. 通过调用 WebPubSubServiceClient.GetClientAccessUri 来生成客户端访问 URL：

   var url = service.GetClientAccessUri(clientProtocol: WebPubSubClientProtocol.Mqtt);
   

Python

1. 按照服务器 SDK 入门创建 WebPubSubServiceClient 对象 service

注意

自版本 1.2.0 起，支持生成 MQTT 客户端访问 URL。

2. 通过调用 WebPubSubServiceClient.get_client_access_token 来生成客户端访问 URL：

   token = service.get_client_access_token(client_protocol="MQTT")
   

Java

1. 按照服务器 SDK 入门创建 WebPubSubServiceClient 对象 service

注意

自版本 1.3.0 起，支持生成 MQTT 客户端访问 URL。

2. 通过调用 WebPubSubServiceClient.getClientAccessToken 来生成客户端访问 URL：

   GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
   option.setWebPubSubClientProtocol(WebPubSubClientProtocol.MQTT);
   WebPubSubClientAccessToken token = service.getClientAccessToken(option);
   

2.上游服务器工作流

MQTT 客户端在与服务建立 WebSocket 连接后发送 MQTT CONNECT 数据包，然后服务调用上游服务器中的 API。 上游服务器可以根据 MQTT 连接请求中的用户名和密码字段以及来自客户端的 TLS 证书对客户端进行身份验证。

此工作流需要显式配置。

• 教程 - 基于客户端证书对 MQTT 客户端进行身份验证和授权
• 若要详细了解如何使用上游服务器对客户端进行身份验证，请参阅如何配置事件处理程序

疑难解答

如果连接失败或无法发布或订阅消息，请检查服务的原因代码/返回代码，或参阅如何使用资源日志进行故障排除。