共用方式為

IoT Central 的裝置實作和最佳做法

  • 發行項

本文提供連線到 IoT Central 應用程式的裝置實作相關資訊。 其中也包含一些最佳做法。 若要深入了解整個連線程序，請參閱連線裝置。

如需裝置實作程式碼範例，請參閱教學課程：建立用戶端應用程式並連線至 Azure IoT Central 應用程式。

實作裝置

連線到 IoT Central 的裝置應遵循 IoT 隨插即用慣例。 其中一個慣例是裝置應傳送連線時所實作之裝置模型的型號識別碼。 模型識別碼可讓 IoT Central 應用程式將裝置指派給正確的裝置範本。

IoT Central 裝置範本包含「模型」，可指定該類型裝置應該實作的行為。 行為包括遙測、屬性和命令。

每個模型都有唯一的「數位對應項模型識別碼」(DTMI)，例如 dtmi:com:example:Thermostat;1。 當裝置連線到 IoT Central 時，會傳送所實作之模型的 DTMI。 接著 IoT Central 可以將正確的裝置範本指派給裝置。

IoT 隨插即用可定義裝置在實作數位分身定義語言 (DTDL) 模型時應遵循的一組慣例。

Azure IoT 裝置 SDK 支援 IoT 隨插即用慣例。

裝置型號

若使用 IoT Central，裝置型號是使用 DTDL V2 模型語言來定義。 此語言可讓您定義：

  • 裝置所傳送的遙測。 定義包括遙測的名稱和資料類型。 例如，裝置會以兩位數傳送溫度遙測。
  • 裝置回報至 IoT Central 的屬性。 屬性定義包括其名稱和資料類型。 例如，裝置會以布林值報告閥門的狀態。
  • 裝置可以從 IoT Central 接收的屬性。 您也可以將屬性標示為可寫入。 例如，IoT Central 會將兩位數的目標溫度傳送至裝置。
  • 裝置會回應的命令。 定義包含命令的名稱，以及任何參數的名稱和資料類型。 例如，裝置會回應重新開機命令，指定重新開機之前要等待的秒數。

注意

IoT Central 定義了 DTDL v2 語言的一些延伸模組。 若要深入了解，請參閱 IoT Central 延伸模組。

DTDL 模型可以是「無元件」或「多元件」模型：

  • 無元件模型: 簡單的模型不會使用內嵌或串聯的元件。 所有遙測、屬性和命令都會定義為單一根元件。 如需範例，請參閱控溫器模型。
  • 多元件模型。 更複雜的模型，包含兩個或更多元件。 這些元件包括單一根元件，以及一或多個巢狀元件。 如需範例，請參閱溫度控制器模型。

提示

您可以從 IoT Central 裝置範本匯入和匯出完整的裝置型號或個別介面，作為 DTDL v2 檔案。

如要深入了解裝置型號，請參閱 IoT 隨插即用模型化指南

慣例

當裝置與 IoT Central 交換資料時，應遵循 IoT 隨插即用慣例。 慣例包括：

  • 在連線到 IoT Central 時傳送 DTMI。
  • 將格式正確的 JSON 承載和中繼資料傳送至 IoT Central。
  • 從 IoT Central 正確回應可寫入的屬性和命令。
  • 遵循元件命令的命名慣例。

注意

目前，IoT Central 不會完全支援 DTDL 陣列和地理空間資料類型。

若要深入了解 IoT 隨插即用慣例用，請參閱 IoT 隨插即用慣例。

若要深入了解裝置與 IoT Central 交換的 JSON 訊息格式，請參閱遙測、屬性和命令承載。

裝置 SDK

若要實作在您的裝置上執行的程式代碼，您應該使用其中 一個 Azure IoT 裝置 SDK。 您的程式代碼應實作的動作包括：

  • 向 DPS 註冊裝置，並使用來自 DPS 的資訊來連線到 IoT Central 應用程式中的內部 IoT 中樞。
  • 宣告裝置所實作的模型 DTMI。
  • 以裝置模型所指定之格式傳送遙測。 若要判斷如何使用遙測進行視覺效果和分析，IoT Central 會使用裝置範本中的模型。
  • 將裝置與 IoT Central 之間的屬性值進行同步。 模型會指定屬性名稱和資料類型，讓 IoT Central 可以顯示資訊。
  • 針對模型中指定的命令實作命令處理常式。 該模型指定裝置應使用的命令名稱和參數。

如需裝置範本角色的詳細資訊，請參閱 什麼是裝置範本？。

下表摘要說明 Azure IoT Central 裝置功能與 IoT 中樞功能的對應方式：

Azure IoT Central Azure IoT 中樞
遙測 裝置到雲端傳訊
離線命令 雲端到裝置傳訊
屬性 裝置對應項的報告屬性
屬性 (可寫入) 裝置對應項所需和所報告的屬性
Command 直接方法

通訊協定

裝置可用來連線到 IoT Central 的通訊協定包括 MQTT、AMQP 和 HTTPS。 IoT Central 會在內部使用 IoT 中樞來啟用裝置連線能力。 如需 IoT 中樞支援裝置連線之通訊協定的詳細資訊，請參閱選擇通訊協定。

如果裝置無法使用任何支援的通訊協定，請使用 Azure IoT Edge 來轉換通訊協定。 IoT Edge 支援其他終端智慧案例，可從 Azure IoT Central 應用程式卸載處理。

遙測時間戳記

IoT Central 預設會在儀表板和圖表上顯示遙測時，使用訊息加入佇列的時間。 當IoT Central 接收來自裝置的訊息時，隨即內部設定訊息加入佇列的時間。

當裝置建立要傳送至 IoT Central 的訊息時，即可設定 iothub-creation-time-utc 訊息。 如果此屬性存在，IoT Central 會在儀表板和圖表上顯示遙測時使用。

當從 IoT Central 應用程式匯出遙測時，您可匯入加入佇列的時間和 iothub-creation-time-utc 屬性。

若要深入了解訊息屬性，請參閱裝置到雲端 IoT 中樞訊息的系統屬性。

最佳作法

這些建議會示範如何實作裝置，以利用 IoT Central 中的內建高可用性、災害復原和自動調整功能。

裝置佈建

隨著應用程式內的 IoT 中樞數目變更，裝置可能需要連線到不同的中樞。

裝置連線到 IoT Central 之前，必須先在基礎服務中註冊並佈建。 當您將裝置新增至 IoT Central 應用程式時，IoT Central 會將輸入新增至 DPS 註冊群組。 IoT Central UI 會顯示來自註冊群組的資訊，例如識別碼範圍、裝置識別碼和金鑰。

當裝置第一次連線到 IoT Central 應用程式時，DPS 會在其中一個註冊群組的連結 IoT 中樞中佈建裝置。 裝置接著會與該 IoT 中樞相關聯。 DPS 會使用配置原則，在應用程式中跨 IoT 中樞對佈建進行負載平衡。 此流程可確保每個 IoT 中樞都有相似的佈建裝置數目。

若要深入了解 IoT Central 中的註冊和佈建，請參閱 IoT Central 裝置連線指南。

處理連線失敗

當 IoT Central 自動調整或處理災害復原案例時，可能會更新其基礎 IoT 中樞。 若要維護連線，您的裝置程式碼應透過建立與新IoT 中樞端點的連線來處理特定的連線錯誤。

如果裝置在連線時收到下列任何錯誤，應使用 DPS 重新佈建裝置，以取得新的連接字串。 這些錯誤表示連接字串不再有效：

  • 無法連線的 IoT 中樞端點。
  • 過期的安全性權杖。
  • IoT 中樞中的裝置已停用。

如果裝置在連線時收到下列任何錯誤，應使用輪詢策略來重新連線。 這些錯誤表示連接字串仍然有效，但暫時性狀況讓裝置無法連線：

  • 遭操作員封鎖的裝置。
  • 服務發生內部錯誤 500。

如要深入了解裝置錯誤碼，請參閱疑難排解裝置連線。

若要深入了解如何實作自動重新連線，請參閱管理裝置重新連線以建立復原的應用程式。

目前，IoT Edge 裝置無法在 IoT 中樞之間移動。

測試容錯移轉功能

Azure CLI 可讓您測試裝置程式碼的容錯移轉功能。 CLI 命令的運作方式是暫時將裝置註冊切換至不同的內部 IoT 中樞。 如要確認裝置容錯移轉是否正常運作，請檢查裝置是否仍會傳送遙測並回應命令。

如要執行裝置的容錯移轉測試，請執行下列命令：

az iot central device manual-failover \
    --app-id {Application ID of your IoT Central application} \
    --device-id {Device ID of the device you're testing} \
    --ttl-minutes {How to wait before moving the device back to it's original IoT hub}

提示

如要尋找應用程式識別碼，請瀏覽至 IoT Central 應用程式中的應用程式 > 管理。

如果命令成功，您會看到與以下範例類似的輸出:

Command group 'iot central device' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
{
  "hubIdentifier": "6bd4...bafa",
  "message": "Success! This device is now being failed over. You can check your device'’'s status using 'iot central device registration-info' command. The device will revert to its original hub at Tue, 18 May 2021 11:03:45 GMT. You can choose to failback earlier using device-manual-failback command. Learn more: https://aka.ms/iotc-device-test"
}

如要深入了解 CLI 命令，請參閱 az iot central device manual-failover。

您現在可以檢查來自裝置的遙測仍會到達您的 IoT Central 應用程式。

提示

若要查看以各種程式設計語言處理故障轉移的範例裝置程式代碼，請參閱 IoT Central高可用性用戶端。

下一步

部分建議後續步驟為：