快速入門:開始使用 Azure IoT 操作 SDK 開發

立即開始使用 Azure IoT 操作 SDK 進行開發。 請遵循下列步驟來設定開發環境,以建置和執行範例,以及建立和測試您自己的高可用性邊緣應用程式。

GitHub repository | .NET SDK | Go SDK | Rust SDK

先決條件

開始之前,請符合下列必要條件:

  • 一個 Azure 訂閱。 如果您沒有 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 提供最流暢的體驗,能在幾分鐘內啟動開發環境。

  1. 在 GitHub Codespaces 中,從 Azure IoT 操作 SDKs 倉庫建立一個 codespace:

    在GitHub碼空間中開啟

  2. 程式碼空間建立後,你會有一個容器,裡面有開發工具,並預裝一個本地 K3s 叢集在 K3d 裡運行。

部署 Azure 物聯網操作

您將對前一步驟建立的開發叢集啟用 Arc,並使用測試設定部署 Azure IoT 操作。

開啟一個新的 Bash 終端機並完成以下步驟:

  1. 前往儲存庫的根目錄:

    cd <REPOSITORY ROOT>
    
  2. 執行 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>
    

    此腳本執行以下指令:

    1. 登入 Azure CLI
    2. 建立資源群組
    3. 註冊所需的 Azure 服務提供者
    4. 將 Kubernetes 叢集連接至 Azure Arc
    5. 啟用 Azure Arc 功能
    6. 建立 Azure 儲存體帳戶
    7. 建立 Azure IoT 操作 架構註冊表
    8. 建立 Azure 裝置登錄命名空間
    9. 初始化 Azure 物聯網操作
    10. 建立 Azure IoT 運營實例
  3. 部署結束後,使用 az IoT Ops check 評估Azure IoT 操作服務部署的健康狀況、設定與可用性。 檢查命令可協助您在部署和設定中找到問題。

    az iot ops check
    

設定 Azure IoT 作業用於開發

部署 Azure IoT 操作 後,先設定它進行開發。 設定 MQTT 經紀人和認證方法。 務必為你的開發環境設定必要的環境變數:

  1. 前往儲存庫的根目錄:

    cd <REPOSITORY ROOT>
    
  2. 執行 configure-aio.sh 腳本以設置 Azure IoT 操作 以進行開發:

    ./tools/deployment/configure-aio.sh
    

    此腳本執行以下指令:

    1. 如果缺少,則設定憑證服務
    2. 建立用於 x509 認證的根 CA 及中間 CA
    3. 建立 Broker 用來驗證 x509 用戶端的信任套件 ConfigMap
    4. 配置 BrokerListener 和 BrokerAuthentication 資源以進行 SAT 和 x509 驗證

測試安裝

測試設定時,請使用mosquitto_pub連接到 MQTT 代理並驗證 x509 憑證、SAT 和信任包。

  1. 匯出 .session 目錄:

    export SESSION=$(git rev-parse --show-toplevel)/.session
    
  2. 測試無 TLS,沒有任何驗證:

    mosquitto_pub -L mqtt://localhost:1883/hello -m world --debug
    
  3. 使用 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
    
  4. 使用 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
    

執行範例

此範例展示了用戶端與伺服器之間使用 Telemetry 與 remote 程序呼叫(RPC) 進行的簡單通訊。 伺服器會追蹤計數器的值,並接受來自用戶端的 RPC 要求,以讀取或遞增該計數器。

範例使用 v2 協定編譯器搭配 WoT Thing 模型檔案,詳見 TestThing 資料夾。

  1. 安裝 .NET 9.0 SDK。

  2. Azure IoT 操作 SDKs GitHub repository 中的樣本 從環境變數讀取設定。 儲存庫根節點提供一個 .env 檔案,匯出樣本用來連接 MQTT 代理的變數。 編輯 .env 檔案以設定您環境的值,或使用檔案中所提供的預設值。

  3. 瀏覽至 CounterServer 範例目錄:

    cd <REPOSITORY ROOT>/dotnet/samples/Protocol/RPC/CounterServer/
    
  4. 建置範例:

    dotnet build
    
  5. 執行範例:

    source `git rev-parse --show-toplevel`/.env; export AIO_MQTT_CLIENT_ID=counter-server; dotnet run
    
  6. 開啟新的殼層並瀏覽至 CounterClient 範例目錄:

    cd <REPOSITORY ROOT>/dotnet/samples/Protocol/RPC/CounterClient/
    
  7. 建置範例:

    dotnet build
    
  8. 執行範例:

    source `git rev-parse --show-toplevel`/.env; export AIO_MQTT_CLIENT_ID=counter-client; export COUNTER_SERVER_ID=counter-server; dotnet run
    
  9. 你會看到用戶端和伺服器在通訊,用戶端會發送讀取並增加計數器值的請求,伺服器則傳送遙測資料。 詳情請參見 「檢視用戶端與伺服器輸出」。

  10. 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 進行開發,請參閱下列資源: