立即開始使用 Azure IoT 操作 SDK 進行開發。 請遵循下列步驟來設定開發環境,以建置和執行範例,以及建立和測試您自己的高可用性邊緣應用程式。
GitHub repository | .NET SDK | Go SDK | Rust SDK
先決條件
開始之前,請符合下列必要條件:
- 一個 Azure 訂閱。 如果您沒有 Azure 訂用帳戶,請在開始之前建立免費帳戶。
一個GitHub帳戶。
Azure 存取權限。 欲了解更多資訊,請參閱 部署概覽 > 「必要權限」。
設定
使用 Azure IoT 操作 SDK 開發需要一個部署 Azure IoT 操作 的 Kubernetes 叢集。 進一步設定則允許你直接從開發者環境存取 MQTT 代理。
這很重要
以下開發環境設定選項使用在 K3d 中運行的 K3s,作為輕量級 Kubernetes 叢集。 他們部署Azure IoT 操作時會搭配 test 設定。 若是實際執行環境部署,請選擇安全設定。
若要使用安全設定,請依照準備您的支援 Arc 的 Azure Kubernetes 叢集中的指示,在 Ubuntu 上建立 K3s 叢集,並依照將 Azure IoT 操作部署至生產叢集中的指示,使用安全設定進行部署。 接著進入 配置 Azure IoT 操作以進行開發。
GitHub Codespaces 提供最流暢的體驗,能在幾分鐘內啟動開發環境。
部署 Azure 物聯網操作
您將對前一步驟建立的開發叢集啟用 Arc,並使用測試設定部署 Azure IoT 操作。
開啟一個新的 Bash 終端機並完成以下步驟:
前往儲存庫的根目錄:
cd <REPOSITORY ROOT>執行
install-aio-arc.sh腳本以啟用你叢集的 Arc 功能,並部署 Azure IoT 運營管理。 用你的數值替換佔位符:參數 價值觀 LOCATION你附近的 Azure 區域。 如需目前支援的區域清單,請參閱支援的區域。 RESOURCE_GROUP一個新的 Azure 資源群組名稱,你的叢集將會在那裡建立。 CLUSTER_NAME您的 Kubernetes 叢集的名稱。 STORAGE_ACCOUNT_NAME您的儲存體帳戶名稱。 儲存體帳戶名稱必須介於 3 到 24 個字元的長度,且只能包含數字和小寫字母。 SCHEMA_REGISTRY_NAME您的結構描述登錄名稱。 結構描述登錄名稱只能包含數字、小寫字母和連字號。 SCHEMA_REGISTRY_NAMESPACE您的結構描述登錄命名空間名稱。 命名空間會唯一識別租用戶內的結構描述登錄。 結構描述登錄命名空間名稱只能包含數字、小寫字母和連字號。 DEVICE_REGISTRY_NAMESPACE您的裝置登錄命名空間名稱。 在您的租用戶內必須是唯一值,且長度須為 3 到 24 個字元。 只能包含數字、字母、連字符和底線。 ./tools/deployment/install-aio-arc.sh -l <LOCATION> -g <RESOURCE_GROUP> -c <CLUSTER_NAME> -s <STORAGE_ACCOUNT_NAME> -r <SCHEMA_REGISTRY_NAME> -n <SCHEMA_REGISTRY_NAMESPACE> -d <DEVICE_REGISTRY_NAMESPACE>此腳本執行以下指令:
- 登入 Azure CLI
- 建立資源群組
- 註冊所需的 Azure 服務提供者
- 將 Kubernetes 叢集連接至 Azure Arc
- 啟用 Azure Arc 功能
- 建立 Azure 儲存體帳戶
- 建立 Azure IoT 操作 架構註冊表
- 建立 Azure 裝置登錄命名空間
- 初始化 Azure 物聯網操作
- 建立 Azure IoT 運營實例
部署結束後,使用 az IoT Ops check 評估Azure IoT 操作服務部署的健康狀況、設定與可用性。 檢查命令可協助您在部署和設定中找到問題。
az iot ops check
設定 Azure IoT 作業用於開發
部署 Azure IoT 操作 後,先設定它進行開發。 設定 MQTT 經紀人和認證方法。 務必為你的開發環境設定必要的環境變數:
前往儲存庫的根目錄:
cd <REPOSITORY ROOT>執行
configure-aio.sh腳本以設置 Azure IoT 操作 以進行開發:./tools/deployment/configure-aio.sh此腳本執行以下指令:
- 如果缺少,則設定憑證服務
- 建立用於 x509 認證的根 CA 及中間 CA
- 建立 Broker 用來驗證 x509 用戶端的信任套件 ConfigMap
- 配置
BrokerListener和BrokerAuthentication資源以進行 SAT 和 x509 驗證
測試安裝
測試設定時,請使用mosquitto_pub連接到 MQTT 代理並驗證 x509 憑證、SAT 和信任包。
匯出
.session目錄:export SESSION=$(git rev-parse --show-toplevel)/.session測試無 TLS,沒有任何驗證:
mosquitto_pub -L mqtt://localhost:1883/hello -m world --debug使用 x509 驗證測試 TLS:
mosquitto_pub -L mqtts://localhost:8883/hello -m world --cafile $SESSION/broker-ca.crt --cert $SESSION/client.crt --key $SESSION/client.key --debug使用 SAT 驗證測試 TLS:
mosquitto_pub -L mqtts://localhost:8884/hello -m world --cafile $SESSION/broker-ca.crt -D CONNECT authentication-method K8S-SAT -D CONNECT authentication-data $(cat $SESSION/token.txt) --debug
執行範例
此範例展示了用戶端與伺服器之間使用
範例使用 v2 協定編譯器搭配 WoT Thing 模型檔案,詳見 TestThing 資料夾。
安裝 .NET 9.0 SDK。
Azure IoT 操作 SDKs GitHub repository 中的樣本 從環境變數讀取設定。 儲存庫根節點提供一個
.env檔案,匯出樣本用來連接 MQTT 代理的變數。 編輯.env檔案以設定您環境的值,或使用檔案中所提供的預設值。瀏覽至
CounterServer範例目錄:cd <REPOSITORY ROOT>/dotnet/samples/Protocol/RPC/CounterServer/建置範例:
dotnet build執行範例:
source `git rev-parse --show-toplevel`/.env; export AIO_MQTT_CLIENT_ID=counter-server; dotnet run開啟新的殼層並瀏覽至
CounterClient範例目錄:cd <REPOSITORY ROOT>/dotnet/samples/Protocol/RPC/CounterClient/建置範例:
dotnet build執行範例:
source `git rev-parse --show-toplevel`/.env; export AIO_MQTT_CLIENT_ID=counter-client; export COUNTER_SERVER_ID=counter-server; dotnet run你會看到用戶端和伺服器在通訊,用戶端會發送讀取並增加計數器值的請求,伺服器則傳送遙測資料。 詳情請參見 「檢視用戶端與伺服器輸出」。
CounterClient樣本完成後會自動退出。 您也可以在終端機中按CounterServer來停止Ctrl+C範例。
檢視用戶端與伺服器輸出
本節展示用戶端與伺服器端的輸出範例。 用戶端呼叫讀取並增加計數器值,伺服器則回應。 伺服器也會輸出遙測數據,讓用戶端能追蹤計數器值。 在這些例子中,訊息會被邏輯分組,但在你的輸出中,訊息的順序會根據客戶端和伺服器的時間順序而改變。 這些範例會顯示 MQTT 訊息的輸出,但你可以在用戶端和伺服器的 appsettings.json 檔案中,將 mqttDiag 環境變數設為 false,以抑制這些輸出。
讀取次數計數器
以下範例展示了讀取計數器的輸出訊息。 客戶端與伺服器間的請求與回應會依相關 ID 匹配,在此範例中為 aaaa0000-bb11-2222-33cc-444444dddddd。
客戶輸出:
# Subscribe once on startup.
CounterClient Information: 0 : >> [2026-07-29T17:35:53.4663363Z] [11]: TX (51 bytes) >>> Subscribe: [PacketIdentifier=2] [TopicFilters=clients/+/rpc/command-samples/+/readCounter@AtLeastOnce]
CounterClient Information: 0 : >> [2026-07-29T17:35:53.4689212Z] [6]: RX (6 bytes) <<< SubAck: [PacketIdentifier=2] [ReasonCode=GrantedQoS1]
CounterClient Information: 0 : Subscribed to topic filter 'clients/+/rpc/command-samples/+/readCounter' for command invoker 'readCounter'
# Invoke readCounter once on startup and once at end -- only one shown.
info: CounterClient.RpcCommandRunner[0] Calling ReadCounter with aaaa0000-bb11-2222-33cc-444444dddddd
CounterClient Information: 0 : >> [2026-07-29T17:35:53.4777793Z] [11]: TX (335 bytes) >>> Publish: [Topic=rpc/command-samples/counter-server/readCounter] [PayloadLength=0] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=3]
CounterClient Information: 0 : >> [2026-07-29T17:35:53.4818287Z] [10]: RX (4 bytes) <<< PubAck: [PacketIdentifier=3] [ReasonCode=Success]
CounterClient Information: 0 : Invoked command 'readCounter' with correlation ID aaaa0000-bb11-2222-33cc-444444dddddd to topic 'rpc/command-samples/counter-server/readCounter'
CounterClient Information: 0 : >> [2026-07-29T17:35:53.5861515Z] [10]: RX (260 bytes) <<< Publish: [Topic=clients/counter-client/rpc/command-samples/counter-server/readCounter] [PayloadLength=21] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=1]
info: CounterClient.RpcCommandRunner[0] called read 0 with id aaaa0000-bb11-2222-33cc-444444dddddd
CounterClient Information: 0 : >> [2026-07-29T17:35:53.6572000Z] [10]: TX (4 bytes) >>> PubAck: [PacketIdentifier=1] [ReasonCode=Success]
伺服器輸出:
# Subscribe to readCounter topic on startup.
CounterServer Information: 0 : >> [2026-07-29T17:35:12.3456281Z] [7]: TX (54 bytes) >>> Subscribe: [PacketIdentifier=1] [TopicFilters=rpc/command-samples/counter-server/readCounter@AtLeastOnce]
CounterServer Information: 0 : >> [2026-07-29T17:35:12.3553742Z] [11]: RX (6 bytes) <<< SubAck: [PacketIdentifier=1] [ReasonCode=GrantedQoS1]
CounterServer Information: 0 : Command executor for 'readCounter' started.
# Multiple (2) invocations occur - only one shown.
CounterServer Information: 0 : >> [2026-07-29T17:35:53.4842146Z] [11]: RX (334 bytes) <<< Publish: [Topic=rpc/command-samples/counter-server/readCounter] [PayloadLength=0] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=1]
<6>17:35:53CounterServer.CounterService[0] --> Executing Counter.ReadCounter with id aaaa0000-bb11-2222-33cc-444444dddddd for counter-client
<6>17:35:53CounterServer.CounterService[0] --> Executed Counter.ReadCounter with id aaaa0000-bb11-2222-33cc-444444dddddd for counter-client
CounterServer Information: 0 : >> [2026-07-29T17:35:53.5815820Z] [7]: TX (261 bytes) >>> Publish: [Topic=clients/counter-client/rpc/command-samples/counter-server/readCounter] [PayloadLength=21] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=4]
CounterServer Information: 0 : >> [2026-07-29T17:35:53.5854665Z] [11]: RX (4 bytes) <<< PubAck: [PacketIdentifier=4] [ReasonCode=Success]
CounterServer Information: 0 : >> [2026-07-29T17:35:53.5881430Z] [12]: TX (4 bytes) >>> PubAck: [PacketIdentifier=1] [ReasonCode=Success]
增量計數器
以下範例顯示遞增計數器的輸出訊息。 請求與回應會依相關 ID 在用戶端與伺服器間匹配,在此範例中為 bbbb1111-cc22-3333-44dd-555555eeeeee。
客戶輸出:
# Invoke increment multiple times -- only one shown.
info: CounterClient.RpcCommandRunner[0] calling counter.incr with id bbbb1111-cc22-3333-44dd-555555eeeeee
CounterClient Information: 0 : >> [2026-07-29T17:35:53.6375578Z] [11]: TX (49 bytes) >>> Subscribe: [PacketIdentifier=4] [TopicFilters=clients/+/rpc/command-samples/+/increment@AtLeastOnce]
CounterClient Information: 0 : >> [2026-07-29T17:35:53.6399406Z] [10]: RX (6 bytes) <<< SubAck: [PacketIdentifier=4] [ReasonCode=GrantedQoS1]
CounterClient Information: 0 : Subscribed to topic filter 'clients/+/rpc/command-samples/+/increment' for command invoker 'increment'
CounterClient Information: 0 : >> [2026-07-29T17:35:53.6461370Z] [11]: TX (372 bytes) >>> Publish: [Topic=rpc/command-samples/counter-server/increment] [PayloadLength=20] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=21]
CounterClient Information: 0 : >> [2026-07-29T17:35:53.6552803Z] [10]: RX (4 bytes) <<< PubAck: [PacketIdentifier=21] [ReasonCode=Success]
CounterClient Information: 0 : Invoked command 'increment' with correlation ID bbbb1111-cc22-3333-44dd-555555eeeeee to topic 'rpc/command-samples/counter-server/increment'
CounterClient Information: 0 : >> [2026-07-29T17:35:53.6960747Z] [13]: RX (259 bytes) <<< Publish: [Topic=clients/counter-client/rpc/command-samples/counter-server/increment] [PayloadLength=22] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=12]
info: CounterClient.RpcCommandRunner[0] called counter.incr 10 with id bbbb1111-cc22-3333-44dd-555555eeeeee
CounterClient Information: 0 : >> [2026-07-29T17:35:53.7138884Z] [10]: TX (4 bytes) >>> PubAck: [PacketIdentifier=12] [ReasonCode=Success]
伺服器輸出:
# Subscribe to increment once on startup.
CounterServer Information: 0 : >> [2026-07-29T17:35:12.3548320Z] [7]: TX (52 bytes) >>> Subscribe: [PacketIdentifier=2] [TopicFilters=rpc/command-samples/counter-server/increment@AtLeastOnce]
CounterServer Information: 0 : >> [2026-07-29T17:35:12.3613847Z] [11]: RX (6 bytes) <<< SubAck: [PacketIdentifier=2] [ReasonCode=GrantedQoS1]
CounterServer Information: 0 : Command executor for 'increment' started.
# Multiple invocations are received -- only one shown.
CounterServer Information: 0 : >> [2026-07-29T17:35:53.6502886Z] [13]: RX (371 bytes) <<< Publish: [Topic=rpc/command-samples/counter-server/increment] [PayloadLength=20] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=2]
<6>17:35:53CounterServer.CounterService[0] --> Executing Counter.Increment with id bbbb1111-cc22-3333-44dd-555555eeeeee for counter-client
<6>17:35:53CounterServer.CounterService[0] --> Executed Counter.Increment with id bbbb1111-cc22-3333-44dd-555555eeeeee for counter-client
CounterServer Information: 0 : >> [2026-07-29T17:35:53.6924040Z] [7]: TX (260 bytes) >>> Publish: [Topic=clients/counter-client/rpc/command-samples/counter-server/increment] [PayloadLength=22] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=15]
CounterServer Information: 0 : >> [2026-07-29T17:35:53.6983722Z] [18]: RX (4 bytes) <<< PubAck: [PacketIdentifier=15] [ReasonCode=Success]
CounterServer Information: 0 : >> [2026-07-29T17:35:53.6992783Z] [12]: TX (4 bytes) >>> PubAck: [PacketIdentifier=2] [ReasonCode=Success]
CounterValue 遙測
以下範例展示了 CounterValue 遙測的輸出訊息。 伺服器輸出會先顯示,因為它會傳送遙測資料。
伺服器輸出:
# Telemetry data is published multiple times.
CounterServer Information: 0 : >> [2026-07-29T17:35:53.6805980Z] [7]: TX (203 bytes) >>> Publish: [Topic=telemetry/telemetry-samples/counterValue] [PayloadLength=18] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=5]
CounterServer Information: 0 : >> [2026-07-29T17:35:53.6843445Z] [11]: RX (4 bytes) <<< PubAck: [PacketIdentifier=5] [ReasonCode=Success]
CounterServer Information: 0 : Telemetry sent successfully to the topic 'telemetry/telemetry-samples/counterValue'
客戶輸出:
# Subscribe performed once on startup.
CounterClient Information: 0 : >> [2026-07-29T17:35:53.4283758Z] [11]: TX (48 bytes) >>> Subscribe: [PacketIdentifier=1] [TopicFilters=telemetry/telemetry-samples/counterValue@AtLeastOnce]
CounterClient Information: 0 : >> [2026-07-29T17:35:53.4355484Z] [10]: RX (6 bytes) <<< SubAck: [PacketIdentifier=1] [ReasonCode=GrantedQoS1]
CounterClient Information: 0 : Telemetry receiver subscribed for topic telemetry/telemetry-samples/counterValue.
# Multiple telemetry values received - only one shown.
CounterClient Information: 0 : >> [2026-07-29T17:35:53.6820692Z] [6]: RX (202 bytes) <<< Publish: [Topic=telemetry/telemetry-samples/counterValue] [PayloadLength=18] [QoSLevel=AtLeastOnce] [Dup=False] [Retain=False] [PacketIdentifier=2]
CounterClient Information: 0 : Telemetry received from telemetry/telemetry-samples/counterValue
info: CounterClient.CounterClient[0] Telemetry received from counter-server: CounterValue=4
CounterClient Information: 0 : >> [2026-07-29T17:35:53.7131604Z] [10]: TX (4 bytes) >>> PubAck: [PacketIdentifier=2] [ReasonCode=Success]
設定摘要
MQTT 代理程式設定
安裝軟體後,叢集包含以下 MQTT 代理定義:
| 元件類型 | 名稱 | 說明 |
|---|---|---|
Broker |
預設 | MQTT 代理程式 |
BrokerListener |
預設 | 提供 MQTT 代理 的叢集存取權 |
BrokerListener |
default-external | 提供對叢集外的 MQTT 代理的存取 |
BrokerAuthentication |
預設 | SAT 驗證定義 |
BrokerAuthentication |
default-x509 | x509 驗證定義 |
MQTT 代理程式存取
你可以透過下表描述的連線參數資訊,存取叢集內外的 MQTT 代理伺服器。 關於在設定應用程式時應使用哪些環境變數,請參見 Connection Settings。
備註
存取 MQTT 代理程式叢集外時的主機名稱可能會依設定而與 localhost 不同。
| 主機名稱 | 認證 | TLS | 開啟叢集通訊埠 | 關閉叢集連接埠 |
|---|---|---|---|---|
aio-broker |
SAT | ✅ | 18883 |
- |
localhost |
沒有 | ❌ | 1883 |
1883 |
localhost |
x509 | ✅ | 8883 |
8883 |
localhost |
SAT | ✅ | 8884 |
8884 |
開發成品
作為部署腳本的一部分,本地環境會建立以下檔案,以促進與 MQTT 代理者的連接與認證。 你可以在 .session 儲存庫根目錄中找到這些檔案。
| 檔案 | 說明 |
|---|---|
broker-ca.crt |
在連接埠 8883 和 8884 上驗證 MQTT 代理程式所需的 MQTT 代理程式信任套件組合 |
token.txt |
一個服務認證憑證(SAT),用於與 MQTT 代理進行認證 8884 |
client.crt |
x509 用戶端憑證,用於在埠上使用 MQTT 代理進行認證 8883 |
client.key |
x509 用戶端私鑰用於在埠口與 MQTT 代理進行認證 8883 |
故障排除
請參考 Azure IoT 操作 SDK GitHub repository 的常見問題排解指南。
後續步驟
在這個快速入門中,你設定了 Azure IoT 操作 的 SDK,並執行了一個範例應用程式。 若要深入了解如何使用 SDK 進行開發,請參閱下列資源: