使用統一的 Azure IoT SDK for .NET 或 C 來配置裝置,將其連接至 Azure IoT 中樞,並使用 MQTT v5 連線設定檔傳送遙測資料。 先從一個小型 JSON 訊息開始,並在新增自訂主題或較複雜負載前,先在下游目的地驗證它。
內嵌範例使用 Device Provisioning Service (DPS) 為裝置配置現有的 X.509 憑證,並取得其分配的 IoT 中樞 連線詳細資訊。 裝置接著連接到該集線器,並透過 MQTT v5 發佈遙測資料;遙測資料不會經過 DPS。
關於 SDK 選擇與共享連線模型,請參閱統一 Azure IoT SDK。 請使用來自 Available SDK 的 MQTT v5 相容預覽版本。 以下範例會釘選特定版本,使其 API 和指令可重現。
Prerequisites
- 完成 集線器設定 與 路由設定,包括已啟用的全訊息路由。 請參閱目的地的路由端點需求。
- 在 DPS 中啟用的 X.509 註冊,將裝置指派至指定的中樞。
- DPS ID 範圍以及帶有對應私鑰的裝置憑證。
- 適用於 TLS 的裝置時鐘與憑證信任設定。
- 一個準備尋找測試訊息的目標讀取器。
以下範例使用現有裝置憑證進行 DPS 佈建及後續集線器連線。 在佈建期間的憑證發放是獨立的設定路徑。 這些範例不會為裝置建立註冊或取得憑證。
X.509 裝置驗證
具備 MQTT v5 連線設定檔的物聯網集線器需要 X.509 憑證才能進行裝置連線。 憑證可由 Microsoft 或第三方憑證授權機構簽發。 這些中樞連線不支援直接使用 SAS 驗證。
不要停用伺服器憑證或主機名稱驗證。 有關端點選擇及共用 TLS 需求,請參閱 IoT 中樞 端點。
避免私鑰和憑證密碼進入原始碼控制範圍。 基於檔案的憑證對於本地評估非常有用。 使用您的裝置平台支援的金鑰保護來進行生產設計。
裝置佈建服務(DPS)佈建與憑證
DPS 佈建與中樞驗證是分開的。 對稱金鑰啟動憑證無法啟用對 MQTT v5 集線器的 SAS 認證;裝置必須透過支援的 DPS 發行路徑取得運作中的 X.509 憑證。 這裡的範例改為為兩個連線使用現有的 X.509 憑證。 關於語言與版本特定的支援,請參閱 「佈建與驗證」。
CLI 建立設定 --disable-local-auth false 允許服務端 SAS 驗證。 它不會啟用 SAS 裝置連線,也不會改變 X.509 的需求。
設定導覽會將這些服務與裝置憑證選項分開。
透過DPS核發與續期營運證書
對於 MQTT v5,營運憑證的簽發與續期皆透過 DPS,而非直接透過樞紐。 ADR 提供簽發 CA 與憑證政策。 續約需要提供註冊憑證及新的憑證簽署申請。 SDK 支援會依語言、版本及 API 介面而異;不要假設會自動續約。 請參閱 SDK 憑證管理支援 及 透過 DPS 設定憑證發行。 本文中的內嵌範例並未實作憑證發放或續期。
證書簽發範例
有關在 DPS 配置期間請求操作憑證的範例程式碼,請參閱 C 與 .NET 範例。 每個裝置使用個別註冊對稱金鑰驗證 DPS,產生私鑰與 CSR,並請求作業憑證。 後續的 MQTT v5 集線器連線使用 X.509;對稱金鑰僅為入門憑證。
在執行 標準遙測、直接方法及雙胞胎場景前,請依照儲存庫的設定說明操作。 共用驗證器會在獨立的 Event Hubs 目的地檢查直接方法回應、所需屬性到已回報屬性的更新,以及遙測接收情況。 請參閱 .NET 範例以及 C 語言建置與執行指令。 這些範例顯示的是首次簽發,而非自動續期。
樣本通過了本地建置和離線測試。 Live Azure 情境與乾淨機器設定仍需驗證。 在執行這些項目之前,請先檢視儲存庫的先決條件與驗證限制。
憑證信任與滾轉
請依照共用 伺服器憑證 及 憑證釘選指引 ,維護裝置信任儲存區。
確認雲端設定
使用 集線器設定中的預覽擴充功能。 在執行裝置應用程式之前,請查看 DPS ID 範圍和註冊項目:
az iot dps show --name "<DPS_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --query properties.idScope --output tsv
az iot dps enrollment show --dps-name "<DPS_NAME>" --resource-group "<RESOURCE_GROUP_NAME>" --enrollment-id "<REGISTRATION_ID>" --query "{registrationId:registrationId,status:provisioningStatus}" --output json
將回傳的 ID 範圍用作裝置設定中的 DPS_ID_SCOPE。
註冊必須已啟用,且與憑證的佈建身分識別相符。
ID 範圍不是 DPS 資源 ID 或集線器主機名稱。
使用 驗證準備度 來確認連結的資源。 僅靠雲端配置並不能證明佈建或訊息傳遞;裝置 SDK 和目的地讀取器提供這些檢查點。
為第一次測試選擇一個酬載資料
使用 UTF-8 JSON 搭配明確的內容類型。 請包含唯一的測試識別碼,以便您能區分目前的訊息與舊的目的地資料。
有關共用有效載荷與內容中繼資料的指引,請參閱《建立並讀取 IoT 中樞 訊息》。 路由端點的 訊息格式 為獨立設定;請參閱 「驗證結果」。
最初的 .NET 與 C 範例使用標準遙測用戶端。 自訂主題發佈器是一個獨立的 SDK 操作;請參閱「使用 .NET 發佈自訂主題測試訊息」,該範例同時設定了 MQTT v5 使用者屬性。
.NET
此範例針對 Microsoft.Azure.Iot.Device2.0.0-preview4 及 .NET 10。
它會透過統一遙測客戶端傳送一個 JSON 訊息。
建立應用程式
在 PowerShell 中執行以下指令:
dotnet new console --name HubTelemetry --framework net10.0
Set-Location HubTelemetry
dotnet add package Microsoft.Azure.Iot.Device --version 2.0.0-preview4
替換 Program.cs 為:
using System.Security.Cryptography.X509Certificates;
using System.Text.Json;
using Microsoft.Azure.Iot.Device;
using Microsoft.Azure.Iot.Device.Authentication;
using Microsoft.Azure.Iot.Device.Models;
using Microsoft.Azure.Iot.Device.Models.Telemetry;
using Microsoft.Azure.Iot.Device.Unified.Connection;
using Microsoft.Azure.Iot.Device.Unified.Telemetry;
static string RequiredEnvironment(string name)
{
string? value = Environment.GetEnvironmentVariable(name);
return !string.IsNullOrWhiteSpace(value)
? value
: throw new InvalidOperationException($"Set {name} before running.");
}
using var certificate = X509CertificateLoader.LoadPkcs12FromFile(
RequiredEnvironment("DPS_DEVICE_PFX"),
RequiredEnvironment("DPS_DEVICE_PFX_PASSWORD"));
if (!certificate.HasPrivateKey)
{
throw new InvalidOperationException("The device certificate must include its private key.");
}
using var timeout = new CancellationTokenSource(TimeSpan.FromMinutes(2));
using var connection = new ConnectionClient();
var telemetry = new TelemetryClient(connection);
var authentication = new X509AuthenticationProvider(certificate, secondaryClientCertificate: null);
var provisioning = new ProvisioningSettings(RequiredEnvironment("DPS_ID_SCOPE"));
await connection.ProvisionAndConnectAsync(
provisioning, authentication, cancellationToken: timeout.Token);
string testId = Guid.NewGuid().ToString();
var message = new DeviceToCloudTelemetry
{
Payload = JsonSerializer.SerializeToUtf8Bytes(new
{
testId,
temperature = 21.5,
observedAt = DateTimeOffset.UtcNow
}),
ContentType = "application/json",
ContentEncoding = "utf-8",
MessageId = testId
};
await telemetry.SendTelemetryAsync(message, timeout.Token);
Console.WriteLine($"Publish completed for testId={testId}. Verify this ID at the destination.");
await connection.DisconnectAsync();
SDK 會從憑證中推導出佈建註冊識別碼。 確保它與註冊資訊相符。 讓平台驗證伺服器憑證;不要停用驗證以進行測試連線。
設定並執行
在目前的 PowerShell 工作階段中設定 DPS_ID_SCOPE 和 DPS_DEVICE_PFX:
$env:DPS_ID_SCOPE = "<id-scope>"
$env:DPS_DEVICE_PFX = "<absolute-path-to-device.pfx>"
透過本機的秘密管理機制提供 DPS_DEVICE_PFX_PASSWORD,且不將其記錄在腳本或指令歷史中。 然後執行:
dotnet run
檢查應用程式回報的失敗,而非將逾時視為成功發佈。 測試結束後,當不再需要時,請從工作階段中移除憑證環境變數。
C
C SDK 是從原始碼建置而成。 以下指令使用 release 2.0.0-preview.2,並釘選於 c/2.0.0-preview.2 標籤上。
安裝 C 範例指南所需的工具鏈、CMake 及 OpenSSL 先決條件。 在 Windows 上,請使用 Visual Studio 2022 的開發人員 PowerShell。
取得範例
git clone --branch c/2.0.0-preview.2 --depth 1 https://github.com/Azure/azure-iot-sdk.git
Set-Location azure-iot-sdk
git submodule update --init --recursive
Set-Location c
設定裝置
$env:AZ_IOT_DPS_ID_SCOPE = "<id-scope>"
$env:AZ_IOT_DPS_REGISTRATION_ID = "<registration-id>"
$env:AZ_IOT_CLIENT_CERT = "<absolute-path-to-device-certificate-chain.pem>"
$env:AZ_IOT_CLIENT_KEY = "<absolute-path-to-device-private-key.pem>"
$env:AZ_IOT_TRUSTED_CA = "<absolute-path-to-trusted-server-ca-bundle.pem>"
範例需要與裝置憑證通用名稱相符的註冊 ID。 憑證鏈檔案為葉憑證在前的順序。 受信任的 CA 憑證套件用來驗證 DPS 與 IoT 中樞 伺服器。 它不是裝置的私鑰,也不是客戶端憑證鏈的替代品。
建置並執行
cmake --preset windows-msvc-debug
cmake --build --preset windows-msvc-debug --target az_iot_sample_unified_telemetry
.\build\windows-msvc-debug\samples\unified\Debug\az_iot_sample_telemetry.exe
統一遙測範例會定期傳送 JSON 約一分鐘。 確認 DPS 指派使用的是 MQTT v5。 當指定的設定檔與初始假設不同時,範例可以重建其遙測用戶端。
C 遙測訊息接受位元組及明確長度。 它的 MQTT v5 遙測助手預設內容類型為 application/json;請勿重複使用該預設值用於任意二進位檔。 內容類型會透過 AZ_IOT_MSG_PROP_CONTENT_TYPE ($.ct) 來覆寫。
使用 .NET 發佈自訂主題測試訊息
標準遙測測試成功後,請繼續執行「以 .NET 發佈自訂主題測試訊息」。 該範例重複使用此應用程式的憑證載入與連線設定。
確認結果
無論哪個 SDK:
- 確認指派至預定的中樞。
- 檢查連結並發布結果。
- 在測試期間讀取已設定的目的地。
- 以 .NET 範例為例,請找出列印出的
testId。 對於 C 範例,請識別該區間內的測試裝置與 JSON 有效載荷。 - 將接收的資料與已傳送的有效載荷進行比較,並檢查所需的元資料。
這些 SDK payload API 不需要 base64 轉換。 根據目的地及其設定的 訊息格式來解讀接收的有效載荷。 MQTT v5 集線器沒有內建遙測端點或備援路徑。
確認實際送達目的地
成功的發佈確認並不是目的地已收到的證明。 請追蹤 監控測試執行 並 驗證接收應用程式的準備狀況,以將訊息與路由及目的地證據進行關聯。
確認選擇性路由
關於自訂主題範例及其正負路由檢查,請參閱 「驗證選擇性路由」。
排除佈建與交付問題
在測試前,請先設定診斷收集。 記錄 UTC 間隔、指派的裝置 ID 與訊息識別碼,但不記錄憑證。 若要將配置、連線、進入、路由及目的地接收進行關聯,請遵循 監控測試執行 的操作。
請使用這份用於 MQTT v5 特定需求的檢查清單:
| 徵兆 | MQTT v5 專屬檢查 |
|---|---|
| 配置或驗證失敗 | 集線器連接需要 X.509,而非 SAS。 Symmetric-Key Onboarding 需要已設定 DPS 憑證核發及裝置憑證簽署請求;現有的 X.509 佈建不需要重新核發。 請參閱 「集線器設定疑難排解」 及 「疑難排解安全連線」。 |
| 自訂主題發佈被拒絕 | 檢查已設定的範本、具體發佈主題、指派的集線器裝置 ID 以及 SDK 確認。 請參閱「 針對自訂主題發佈疑難排解」。 |
| 發佈成功但資料未到達 | MQTT v5 集線器沒有內建遙測端點或備援路徑。 設定並啟用明確路由至支援的目的地,然後確認已收到該處的訊息。 |
對於跨連線設定檔共享的檢查,請使用:
- 針對佈建、連線、輸入、路由及取用檢查點監控測試執行。
- 針對訊息路由的路由計量、資源記錄及端點健康狀況進行故障排除。 內建端點與備援路由指令僅適用於經典設定檔。 關於自訂主題範例的正向與負面檢查,請參閱 驗證選擇性路由。
- 與接收應用程式確認準備就緒情況,以確認有效載荷格式、結構解讀及消費者欄位映射。
- 針對豐富化金鑰、值與目標端點的訊息豐富化,以及使用 Fabric 目的地時的 Fabric 豐富化限制。
排除安全連線問題
請使用已指派 的裝置端點,而非服務端點。 檢查裝置時鐘、憑證與私鑰、伺服器信任度及網路存取是否符合共享 TLS 需求。
如果 TLS 成功但 MQTT 連線失敗,請檢查 MQTT v5 CONNACK 的理由代碼及裝置註冊。 成功的 TLS 握手並不代表 MQTT 會話建立或應用程式運作成功。