閱讀英文

共用方式為

如何將 MQTT 用戶端連線至 Azure Web PubSub

  • 發行項
  • 2024/08/16

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。
  • 用戶端識別碼格式
    • 允許的字元：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>。

驗證與授權

Web PubSub 支援兩個工作流程來驗證和授權 MQTT 用戶端，使其具有適當的許可權。

這些工作流程可以個別或組合使用。 如果它們一起使用，則服務會接受後者工作流程中的驗證結果。

1. JWT 工作流程

這是預設工作流程，如下所示：

使用 JWT 進行 MQTT 驗證工作流程的圖表。

  1. 用戶端會與您的驗證伺服器交涉。 驗證伺服器包含授權中間件，此中間件會處理用戶端要求，並簽署 JWT，讓用戶端連線至服務。
  2. 驗證伺服器會將 JWT 傳回給用戶端。
  3. 用戶端會嘗試使用從驗證伺服器傳回的 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 userId 只允許一個 sub 宣告。

您也可以將自定義宣告新增至存取令牌，而且這些值會保留為claims連接上游要求本文中的 屬性。

伺服器 SDK 提供 API 來產生 MQTT 用戶端的存取令牌。 請注意，您必須將用戶端通訊協定指定為 Mqtt。

  1. 請遵循開始使用伺服器 SDK，以建立 WebPubSubServiceClient 物件 service

注意

自 1.1.3 版起，支持產生 MQTT 用戶端存取 URL。

  1. 呼叫 WebPubSubServiceClient.getClientAccessToken 以產生用戶端存取 URL：

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

2.上游伺服器工作流程

MQTT 用戶端會在與服務建立 WebSocket 連線之後，傳送 MQTT CONNECT 封包，然後服務會在上游伺服器中呼叫 API。 上游伺服器可以根據 MQTT 連線要求中的使用者名稱和密碼欄位，以及來自用戶端的 TLS 憑證來驗證用戶端。

使用上游伺服器進行 MQTT 驗證工作流程的圖表

此工作流程需要明確的設定。

疑難排解

如果您遇到連線失敗，或無法發佈或訂閱訊息，請檢查服務的原因碼/傳回碼，或參閱 如何使用資源記錄進行疑難解答。