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
- 傳輸：WebSocket 使用 TLS。
您應該在 MQTT 用戶端中遵循一些限制，否則將會拒絕連線。 這些 MQTT 通訊協定參數包括：
- 通訊協定版本：3.1.1 或 5.0。
- 用戶端識別碼格式
- 允許的字元：0-9、a-z、A-Z
- 長度介於 1 到 128 之間
- MQTT 3.1.1 的保持運作間隔：1 - 180 秒
- Last-will Topic 格式：非空白，且至少包含一個非空白字元。 最大長度為 1024。
- Last-will 訊息大小：最多 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 | 只允許一個 sub 宣告。 |
您也可以將自訂宣告新增至存取權杖，且這些值會保留為連接上游要求本文中的claims屬性。
伺服器 SDK 提供 API 來產生 MQTT 用戶端的存取令牌。 請注意，您必須將用戶端通訊協定指定為 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 憑證來驗證用戶端。
此工作流程需要明確的設定。
- 教學課程 - 根據用戶端憑證來驗證和授權 MQTT 用戶端
- 如需如何使用上游伺服器來驗證客戶端的詳細資訊，請參閱 如何設定事件處理程式
疑難排解
如果您遇到連線失敗，或無法發佈或訂閱訊息，請檢查服務的原因碼/傳回碼，或參閱 如何使用資源記錄進行疑難解答。