開始您的解決方案,先建立並設定 Azure IoT 集線器,並將其連結至 Azure 裝置登錄檔(ADR)命名空間及裝置配置服務(DPS)實例。 這些資源會確定裝置的連接位置、它們如何被表示,以及它們如何接收集線器指派。 在裝置開始發佈之前,先設定訊息目的地。
本文涵蓋集線器設定階段。 如需完整了解路由、裝置連線與傳送驗證,請參閱「 MQTT v5 入門指南」。
Important
Azure IoT 中樞 搭配 MQTT v5 連線設定檔目前處於預覽階段。 在建立資源前,請先檢視 支援的功能 。 建立樞紐時,您選擇設定檔。 變更端點主機名稱不會改變現有集線器的設定檔。
Prerequisites
- Azure 訂用帳戶。
- 「 支援區域 」中列出的區域,以及預覽版支援的資源配置。
- 需要具備 Contributor 角色,才能建立及設定 IoT 中樞、ADR 命名空間和 DPS 資源,另外還需要具備 User Access Administrator 或 Role Based 存取控制 Administrator,才能建立所需的角色指派。 這些指派必須涵蓋本導覽中使用的資源群組或資源。 適用範圍內的擁有者包含兩組權限。 僅有參與者本身並不允許角色指派。 角色指派條件與組織原則可能會限制您可建立的指派。
- 若您建立新的資源群組,則需具備在訂閱中建立資源群組的權限。
- 佈建計畫:使用現有的 X.509 憑證及匹配的私鑰,或以對稱金鑰或 X.509 佈建認證設定 DPS 憑證發行。 裝置在兩種情況下都是使用 X.509 憑證連接到集線器。
這些權限是針對執行設定的人。 分配給服務管理身份的角色列於 「設定連結資源」下。
使用專門的資源群組進行評估。 如果您使用現有環境,請在變更權限或政策前先識別任何共用資源。
範例設定腳本
此 PowerShell 範例腳本建立新的 MQTT v5 集線器、連結的 ADR 與 DPS 資源、憑證發行設定、對稱金鑰註冊、自訂主題,以及獨立的 Azure 事件中樞 目的地與路由。 有關在 Windows 上執行腳本的說明,請參閱「設定範例環境」。
請將腳本用於新的評估環境,而非用於調整現有部署或重新執行部分完成的手動設定。 在建立可計費資源之前,請先閱讀儲存庫的先決條件、故障行為及清理說明。 範例通過了本地建置和離線檢查。 Live Azure 情境與乾淨機器設定仍需驗證。
支援的區域
MQTT v5 連線設定檔在預覽期間可在以下地區使用。 在同一支援區域內建立 IoT Hub、ADR 命名空間及 DPS 實例。
| Region | CLI 與 ARM 位置值 |
|---|---|
| Australia East | australiaeast |
| Central US | centralus |
| 日本東部 | japaneast |
| 英國南部 | uksouth |
| 美國西部 | westus |
在 CLI 和 ARM 範例需要 <SUPPORTED_REGION>的地方,請使用對應的位置值。
了解資源關係
| 資源或能力 | 在解決方案中的角色 | 與其他資源的關係 |
|---|---|---|
| IoT 中心 | 接受 MQTT v5 裝置連線並路由傳入的遙測資料。 | 與 ADR 命名空間相關聯,並連結至 DPS 實例。 |
| ADR 命名空間 | 提供整合式裝置識別與管理基礎。 | 連接 IoT 中樞 與 DPS 資源,用於裝置識別與管理。 |
| DPS 實例 | 驗證配置請求並將裝置指派至已設定的集線器。 | 連結至 IoT 中樞,並與 ADR 命名空間相關聯。 註冊設定決定裝置如何被佈建。 |
| 受管理身份與角色分配 | 受管理身份是 Azure 的一種服務對服務驗證功能,無需應用程式管理的認證。 角色指派會授予受支援的操作權限。 | 身份會被指派給需要存取其他服務的資源。 角色指派會在所需的範圍內授予存取權限。 |
不要只用資源名稱來檢查關聯。 名稱相似的資源可能存在於不同的訂閱或資源群組中。
佈建認證用來向 DPS 驗證裝置。 請選擇下列憑證路徑之一:
- 請使用現有的 X.509 憑證。 設定 X.509 註冊,並使用憑證進行佈建及後續集線連線。 此路徑不需要簽發憑證,且主要逐步解說採用此路徑。
- 透過 DPS 申請作業憑證。 設定 ADR 簽發憑證授權機構和憑證原則,並在 DPS 註冊中參照這些設定。 裝置使用其對稱金鑰或 X.509 佈建憑證進行驗證,並提交憑證簽署要求(CSR)。 DPS 會傳回 ADR 核發的作業 X.509 憑證,以連線到中樞。
此預覽版不支援透過 MQTT v5 集線器直接更新作業用憑證。 裝置會透過 DPS 更新 DPS 簽發的憑證。
建立並設定 IoT Hub 及連結資源
透過以下任一路徑設定 Azure IoT 中樞 並使用 MQTT v5 連線設定檔:
- 從 IoT 中樞 的設定程序開始。 建立並設定集線器,然後將其連結到 ADR 命名空間和 DPS 實例,作為集線器設定的一部分。
- 使用 ADR 簡化的入門流程。 從 ADR 命名空間開始,並透過簡化的入門流程設定連線服務。 關於此替代路徑,請參閱「開始使用適用於 Azure IoT 中樞 的 Azure 裝置登錄」。
本文著重於第一條路徑:直接將資源設定納入 IoT 中樞 設定的一部分。 建立集線器時選擇 MQTT v5 連線設定檔,並在進行裝置設定前確認每項任務的結果。
使用 MQTT v5 連線設定檔建立 Azure IoT 中樞
Important
建立一個帶有 MQTT v5 連線設定檔的 IoT Hub,並不代表它已經準備好支援裝置連線。 您還必須將樞紐連結到Azure裝置登錄(ADR)命名空間,並建立或使用連結至該命名空間的DPS實例。 在配置裝置並將其連接至集線器之前,先完成所需的權限與連結設定。
請選擇以下其中一種方法來建立樞紐。 選擇預覽版支援的區域,並在建立資源前檢視 IoT 中樞 的定價。
本節從建立樞紐開始。 ARM 範本標籤也包含一個可選的範本,用於建立支援的 ADR 與 DPS 資源。 資源建立並未完成解決方案:先在接下來的六項工作中設定身份、關聯與註冊,然後在傳送遙測資料前先設定路由。
CLI 與 ARM 範例會啟用中樞的系統指派受控識別。 它們也允許使用服務憑證的評估工具使用服務端共用存取簽章(SAS)驗證。 此設定不會啟用 SAS 裝置連線:裝置仍會使用 X.509 憑證連線。 在正式環境中使用該設定前,請先另外審查服務驗證。
Important
使用一個全新且全球獨一無二的樞紐名稱。 這些範例是用來建立一個樞紐,而不是更新現有樞紐。 針對現有資源的 ARM 部署或 REST PUT 可以變更其設定。 不要重複使用現有集線器的名稱來嘗試更改其連線設定。
- 登入 Azure 入口網站。
- 選擇 「建立資源」,搜尋 IoT 中樞,然後選擇 「建立」。
- 選擇您的訂閱和現有的資源群組,或為此評估建立資源群組。
- 輸入一個全新且全球唯一的樞紐名稱,並選擇預覽所支援的區域。
- 本文所使用的配置,請選擇 標準 層級、 S1 尺寸及 1 個單位。
- 在「網路」索引標籤的「連線設定檔」下,選擇 MQTT 5(預覽)。 本攻略請勿選擇 Classic。
- 選擇 「檢閱 + 建立」,檢視設定與預估成本,然後選擇 「建立」。
- 等待部署完成,然後選擇「前往資源」。
- 在將樞紐連結至 ADR 之前,請啟用其系統指派的管理身份:開啟 安全性設定 > 管理身份,選擇 「系統指派」,將 狀態 設為 開啟,然後選擇 儲存。 確認變更。 如需詳細資訊,請參閱 系統指派的受控識別。
如果您使用 ADR 引導的入門方式選取此中樞,請使用位於相同支援區域中的命名空間。 現有資源選擇器會列出啟用公開網路存取的集線器。 僅限私人網路存取的樞紐不會出現在該選擇器中;在未檢視您組織的需求前,請勿更改其網路存取權限。 啟用受控識別是連結的先決條件,但不保證該樞紐會出現在挑選器中。
此處的入口網站步驟會建立樞紐並啟用其身分識別。 連結資源任務使用 CLI。 若要使用入口網站式連結流程,請依照 ADR 引導式上線流程。
在設定連結資源之前,請繼續進行驗證已建立的集線器。
驗證已建立的集線器
對於任何建立方法,請確認該資源存在於預期訂閱與資源群組中,其狀態為 Active,其配置狀態為 Succeeded,且 connectionProfile 其為 MqttV5。 僅憑建立要求成功,並不能證明該中樞具有預期的設定檔。
在 Azure 入口網站中檢查樞紐的資源 JSON,或在完成 Azure CLI 設定後使用預覽 CLI 擴充功能:
az iot hub show --subscription "<SUBSCRIPTION_ID>" --resource-group "<RESOURCE_GROUP_NAME>" --name "<HUB_NAME>" --query "{id:id,location:location,state:properties.state,connectionProfile:properties.connectionProfile,provisioningState:properties.provisioningState,principalId:identity.principalId}" --output json
在繼續之前,請先檢查回傳的數值。 如果佈建未成功或設定檔不是 MqttV5,請先解決此問題,再設定連結資源。 為下列任務儲存集線資源 ID。
設定連結的資源
建立並驗證樞紐後,請完成以下六項任務。 CLI 指令使用 Azure CLI 設定中設定的預覽擴充功能與有效訂閱。 在本逐步解說中使用相同的資源群組。
準備 ADR 命名空間與 DPS 實例。 使用系統指派的受控識別建立兩個資源。 選取尚未被使用的名稱。 如果您使用 了支援資源 ARM 範本,請跳過兩個建立指令,改為驗證現有資源。
az iot adr ns create --name "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --location "<SUPPORTED_REGION>" --outbound-system-assigned-mi --query "{id:id,state:properties.provisioningState,principalId:identity.principalId}" --output jsonaz iot dps create --name "<DPS_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --location "<SUPPORTED_REGION>" --system-assigned-mi --query "{id:id,state:properties.state,principalId:identity.principalId}" --output json儲存回應中的資源 ID。 對於現有資源,請在使用前檢查其身份與現有連結;不要重執行建立指令以替換其設定。
預期結果: 命名空間配置狀態為
Succeeded,DPS 狀態為Active,且資源 ID 與身份主體 ID 皆可用。檢視服務識別碼及所需權限。 下一個任務中的合併的 link 命令會為此系統指派的身分流程設定以下服務對服務角色指派。
Identity Role Scope ADR 命名空間 Azure Device Registry Administrator ADR 命名空間 ADR 命名空間 Contributor IoT 中樞 ADR 命名空間 IoT 中樞 Data Contributor IoT 中樞 ADR 命名空間 Contributor DPS 實例 IoT 中樞 Contributor ADR 命名空間 DPS 實例 Contributor ADR 命名空間 您必須擁有在所列範圍指派這些角色的權限。 此指令是賦予服務身份角色,而非已登入使用者。 裝置的 X.509 憑證與服務的管理身份功能不同。
預期結果: 在連結前,已確認身份、角色、範圍及您建立指派的權限。
透過 ADR 命名空間連結已建立的集線器與 DPS 實例。 連結目標請使用已儲存的資源 ID,而非資源名稱。
Important
將集線器與 ADR 連結是永久性的。 建立此連結時,將樞紐可用性設定為
Available,並設定分配權重為 ,1以便 DPS 能選擇樞紐。 此設定檔不使用az iot dps linked-hub create;支援的關聯是透過 ADR 命名空間。az iot adr ns link add --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --hub-endpoint-name primary-hub --hub-id "<HUB_RESOURCE_ID>" --hub-system-assigned-mi --hub-availability Available --hub-allocation-weight 1 --dps-endpoint-name primary-dps --dps-id "<DPS_RESOURCE_ID>" --dps-system-assigned-mi此指令會先連結 DPS,再連結樞紐,並配置所需的角色指派。 如果只完成部分,請先檢查連結再重試。 當 DPS 連結已經存在時,不要重跑合併的
link add。 請參閱 連結疑難排解。預期結果: 命名空間的 DPS 與樞紐連結兩者都會連到
Succeeded,且樞紐端點為Available。驗證關聯並記錄 DPS ID 範圍。 檢查命名空間連結及兩個已連結的資源上的參考資料:
az iot adr ns link hub show --name primary-hub --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --query "{state:linkingState,availability:provisioning.availability}" --output jsonaz iot adr ns link dps list --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --query "[].linkingState" --output jsonaz iot hub show --name "<HUB_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --query properties.deviceRegistry.linkingProperties.state --output tsvaz iot dps show --name "<DPS_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --query "{links:properties.deviceRegistryNamespaces[].linkingState,idScope:properties.idScope}" --output json預期結果: 所有四個連結狀態檢查報告
Succeeded,集線器可用性為Available,且 DPS ID 範圍已儲存用於裝置設定。設定註冊。 對於現有的 X.509 裝置範例,請使用裝置的公用葉憑證以 PEM 格式建立個人註冊。 使用該憑證主體通用名稱中的註冊 ID。 把對應的私鑰留在裝置上;不要上傳它。
az iot dps enrollment create --dps-name "<DPS_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --enrollment-id "<REGISTRATION_ID>" --attestation-type x509 --certificate-path "<DEVICE_CERTIFICATE_PEM_PATH>" --provisioning-status enabledaz iot dps enrollment show --dps-name "<DPS_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --enrollment-id "<REGISTRATION_ID>" --query "{registrationId:registrationId,status:provisioningStatus}" --output json此範例使用現有憑證;它不設定簽發。 對於替代的簽發路徑,請依照 「透過 DPS 設定憑證發行 」而非建立此既有憑證註冊。
預期結果: 個別註冊為
enabled,其註冊 ID 與裝置的 X.509 入門身分相符。檢視診斷資料。 在測試執行前設定所需的日誌,使用 「收集與路由監控資料」功能。
預期結果: 診斷收集會在裝置嘗試佈建或傳送訊息之前完成設定。
裝置僅使用 X.509 憑證驗證至集線器。 請將 SAS 作為已設定發行路徑的佈建憑證,而非直接的中樞連線憑證。 請參閱 X.509 裝置驗證。 有關主機名稱與 TLS 需求,請參閱 IoT 中樞 端點。
透過 DPS 設定憑證簽發
對於提交 CSR 以取得 ADR 核發運作憑證的裝置,請使用此選用路徑。 如果你使用現有的 X.509 範例,請跳過它。 首先,完成資源連結與權限設定。
Note
MQTT v5 集線器啟動精靈中沒有憑證管理選項。 您可以在連結的 ADR 命名空間中分別設定憑證發行,並在 DPS 註冊中選擇簽發的 CA 與政策。
建立或選擇簽發 CA 與政策
- 在 Azure 入口網站中開啟連結的 ADR 命名空間。
- 在 安全性下,選擇 憑證授權機構。
- 如果命名空間沒有根憑證授權機構,請選擇 「建立>根憑證授權機構」,輸入名稱,然後選擇 「建立」。 等待配置完成。 如果已有根 CA,請重複使用。
- 選擇 建立>中介憑證授權中心,選擇 使用此命名空間的根憑證授權機構,輸入名稱,然後選擇 建立。 等待中介 CA 變成 啟用狀態。 或者,選擇一個現有的作用中簽發憑證授權機構,專供這些裝置使用。
- 打開中繼 CA。 如果尚未有政策,請選擇 「建立政策」,輸入政策名稱與憑證有效期限,然後選擇 「儲存」。 每個中介憑證授權機構支援一個憑證政策。
- 確認該原則是否顯示在 「憑證原則」 下。 選擇其名稱以檢查其狀態及已設定的有效期間。
如需詳細的 CA 與政策指引,請參閱 〈設定受管理根與中介 CA 〉以及 〈建立或編輯憑證原則〉。
設定 DPS 註冊以進行簽發
- 開啟連結到命名空間的 DPS 實例。
- 在 「設定」中,選擇 「管理登錄項目」,然後選擇 「個別登錄項目」>「新增個別登錄項目」。
- 選擇 Symmetric key 或 X.509 作為認證機制,並提供所需的佈建資訊。 對於 X.509,只上傳公開憑證,不要上傳私鑰。
- 輸入裝置的註冊 ID,並啟用註冊程序。
- 檢視配置設定,以便將裝置指派至預期的 MQTT v5 集線器。 如果多個樞紐符合資格,請限制此評估的目標選擇。
- 在 「憑證政策(預覽)」 下,選擇簽發 CA 及其原則。
- 選擇 檢視 + 建立,檢視設定,最後選擇 建立。
- 重新開啟註冊並確認其已啟用,且引用預期的 CA 和原則。 記錄裝置的 DPS ID 範圍與註冊 ID。
妥善保管佈建金鑰與私密金鑰。 裝置應用程式必須使用其佈建憑證向 DPS 進行認證,並提交 CSR 以申請作業憑證。 選擇政策後,裝置未申請前不會發出憑證。
預期結果: 簽發 CA 與政策已準備就緒,且已啟用的 DPS 註冊也參考了它們。 入口網站負責設定簽發路徑;裝置啟動憑證簽發。
了解 ARM 部署範圍
ARM 範例會建立新的 IoT 中樞,並可選擇性地建立支援的 ADR 命名空間與 DPS 實例。 光是建立本身並不能建立資源之間的關聯。 請依照「 設定連結資源」中的六項工作完成權限、連結與註冊設定。
請使用一個支援連線設定檔以及部署所設定的所有資源與屬性的 API 版本。 成功部署通用 IoT 中樞 範本並不代表它選擇了 MQTT v5 連線設定檔。
有關資源結構,請參閱 IoT 中樞 ARM 參考。 架構參考描述屬性;它並非此旅程的完整部署程序。
確認準備狀況
在繼續之前,請檢查每一項:
- 集線器採用 MQTT v5 連線設定檔。
- 集線器會參考預期的 ADR 命名空間。
- DPS 會連結到預期的樞紐與命名空間。
- 裝置的註冊已啟用,並採用預定的入門方式。
- 若使用該方法,則會設定憑證簽發的先決條件。
- 服務身份在預期範圍內擁有所需的權限。
- 您擁有 DPS ID 範圍以及裝置設定步驟所需的憑證。
資源部署成功是此階段的檢查點。 裝置配置成功及下游交付會在稍後進行驗證。
CLI設定疑難排解
在變更 Azure 資源之前,請檢查 CLI 版本及目前的擴充功能:
az version
az extension show --name azure-iot --query version --output tsv
| 徵兆 | Action |
|---|---|
--connection-profile、adr 或 topic-group 無法識別 |
在目前終端機中確認預覽擴充功能。 若使用隔離的擴充目錄,請在每個新終端機中再次選取該目錄。 |
操作會回報某個 API 版本的 InvalidResourceType |
請確認擴充功能版本與目標服務環境是否支援相同的 API 版本。 重複建立資源無法解決 API 版本不符的問題。 |
| 連結會回報權限錯誤 | 檢查呼叫者的角色指派權限,以及「 設定連結資源」中的服務身份與範圍。 |
DPS 顯示沒有任何可用的中樞 Available |
檢查命名空間的樞紐端點、連結狀態、可用性及分配權重。 這些屬性必須在建立連結時設定。 不要一開始就刪除資源作為疑難排解的步驟。 |
| 直接 DPS 集線器連結被拒絕 | 使用此 az iot adr ns link add 設定檔而非 az iot dps linked-hub create。 |
檢查部分完成的連結
即使中樞連結失敗,合併連結命令仍可能讓 DPS 保持連結至 Azure 裝置登錄(ADR)命名空間。 檢查實際端點,而非重執行合併命令:
az iot adr ns link dps list --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --output json
az iot adr ns link hub show --name primary-hub --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --output json
如果樞紐端點存在且其連結狀態為待處理,請等待其完成:
az iot adr ns link hub wait --name primary-hub --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>"
如果該端點處於失敗狀態,請先修正所報告的權限或設定問題。 接著在不替換其身份的情況下,重試現有端點:
az iot adr ns link hub update --name primary-hub --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>"
如果 DPS 成功但樞紐端點不存在,請僅新增缺少的樞紐連結:
az iot adr ns link hub add --name primary-hub --ns "<ADR_NAMESPACE_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --hub-id "<HUB_RESOURCE_ID>" --system-assigned-mi --availability Available --allocation-weight 1
恢復後重新檢查兩個資源及命名空間。 不要以為成功 DPS 連結就代表集線器已經準備好了。
透過 ARM REST 檢查資源與連結狀態
這些唯讀檢查透過 Azure Resource Manager az rest進行。 它們不需要預覽版的物聯網擴充功能。 使用 az login 安裝時儲存的完整資源 ID 登入並使用。
az rest --method get --uri "https://management.azure.com<HUB_RESOURCE_ID>?api-version=2026-10-01-preview" --query "{state:properties.state,provisioningState:properties.provisioningState,namespaceLink:properties.deviceRegistry.linkingProperties.state}" --output json
az rest --method get --uri "https://management.azure.com<DPS_RESOURCE_ID>?api-version=2026-11-01" --query "{state:properties.state,namespaceLinks:properties.deviceRegistryNamespaces}" --output json
az rest --method get --uri "https://management.azure.com<ADR_NAMESPACE_RESOURCE_ID>?api-version=2026-11-01" --query "{state:properties.provisioningState,dps:properties.provisioning.endpoints,hubs:properties.messaging.endpoints}" --output json
檢查具名命名空間的端點、其目標資源 ID 及其 linkingState 值。 在沒有端點的情況下成功部署命名空間,並不代表連結成功。 在嘗試裝置配置之前,也請先檢查集線器端點的 provisioning.availability 配置。
對於回傳 HTTP 412的樞紐組態更新,請使用新的 GET 並將預期變更重新套用到最新資源。 不要刪除 If-Match 標頭,也不要只更新舊本文中的 ETag。 請參閱 「透過 ARM REST 更新現有 IoT Hub」。