在 IoT 解決方案中使用 IoT 隨插即用模型

發行項
09/04/2024

本文說明如何在 IoT 解決方案中識別 IoT 隨插即用裝置的模型 ID，然後擷取其模型定義。

IoT 解決方案有兩個廣泛的類別：

用途建置的解決方案適用於將連線至解決方案之 IoT 隨插即用裝置的一組已知模型。當您開發解決方案時，會使用這些模型。
模型驅動的解決方案可與任何 IoT 隨插即用裝置的模型搭配使用。建置模型驅動的解決方案較為複雜，但優點是您的解決方案可與未來可能新增的任何裝置搭配運作。模型驅動的 IoT 解決方案會擷取一個模型，並用它來判斷裝置所實作的遙測資料、屬性和命令。

為了使用 IoT 隨插即用模型，IoT 解決方案會：

識別連線至解決方案之 IoT 隨插即用裝置、模組或 IoT Edge 模組所實作之模型的模型 ID。
使用模型 ID，從模型存放庫或自訂存放區中擷取已連線裝置的模型定義。

識別模型 ID

當 IoT 隨插即用裝置連線到 IoT 中樞時，它會向 IoT 中樞註冊其所實作之模型的模型 ID。

作為裝置連線流程的一部分，IoT 中樞會告知該解決方案裝置的模型 ID。

解決方案可以使用下列三種方法的其中一種，來取得 IoT 隨插即用裝置的模型 ID：

取得裝置分身 API

解決方案可以使用 Get Device Twin API 來擷取 IoT 隨插即用裝置的模型 ID。

提示

針對模組和 IoT Edge 模組，請使用ModuleClient.getTwin。

在下列的裝置分身回應程式碼片段中，modelId 包含了 IoT 隨插即用裝置的模型 ID：

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

取得數位分身 API

解決方案可以使用 Get Digital Twin API 來擷取 IoT 隨插即用裝置所實作之模型的模型 ID。

在下列的數位分身回應程式碼片段中，$metadata.$model 包含了 IoT 隨插即用裝置的模型 ID：

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

數位分身變更事件通知

裝置連線可以引起數位分身變更事件通知。解決方案需要訂閱此事件通知。若要了解如何為數位分身事件啟用路由，請參閱使用 IoT 中樞訊息路由，將裝置到雲端的訊息傳送至不同端點。

解決方案可以使用下列程式碼片段中所示的事件，來了解連線的 IoT 隨插即用裝置並取得其模型 ID：

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

擷取模型定義

解決方案會使用先前所識別的模型 ID，以擷取對應的模型定義。

解決方案可以使用下列其中一個選項來取得模型定義：

模型存放庫

解決方案可以從裝置模型存放庫 (DMR) 擷取 DTDL 模型。 DMR 是由 Microsoft 所託管的公用存放庫，其中包含策劃的 DTDL 模型集合。儲存在 DMR 中的公用裝置模型可供所有人取用並從公用端點 https://devicemodels.azure.com 整合至應用程式中。

識別新裝置連線的模型 ID 之後，請遵循下列步驟執行：

使用模型存放庫中的模型 ID 來擷取模型定義。如需詳細資訊，請參閱解析模型。
使用連線裝置的模型定義，您可以列舉裝置的功能。
使用裝置的列舉功能，您可以讓使用者與裝置互動。

解析模型

DMR 慣例包含其他成品，可簡化裝載模型的取用。這些功能是自訂或私人存放庫的選用功能。

Index。所有可用的 DTMI 都會透過一連串 json 檔案所組成的索引公開，例如：https://devicemodels.azure.com/index.page.2.json
展開。可供每個介面使用且具有所有相依性的檔案，例如：https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadata. 此檔案會公開存放庫的索引鍵屬性，並使用最新的已發佈模型快照集定期重新整理。其中包含存放庫實作的功能，例如是否可使用模型索引或展開的模型檔案。您可以在 https://devicemodels.azure.com/metadata.json 上存取 DMR 中繼資料

若要以程式設計方式存取 DMR 中的公用 DTDL 模型，您可以使用 NuGet 套件 Azure.IoT.ModelsRepository 中提供的 ModelsRepositoryClient。根據預設，此用戶端會設定為查詢 devicemodels.azure.com 上可用的公用 DMR，並可設定為任何自訂存放庫。

用戶端接受 DTMI 作為輸入，並傳回具有所有必要介面的字典：

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

預期的輸出會顯示相依性鏈結中三個介面的 DTMI：

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

ModelsRepositoryClient 可以設定為查詢自訂 DMR (可透過 https 取得)，並使用 ModelDependencyResolution 旗標指定相依性解析：

Disabled. 只傳回指定的介面，沒有任何相依性。
Enabled。傳回相依性鏈結中的所有介面

提示

自訂存放庫可能不會公開 .expanded.json 檔案。無法使用此檔案時，用戶端會回溯以在本機處理每個相依性。

以下範例程式碼示範如何使用自訂存放庫基底 URL 來初始化 ModelsRepositoryClient，在此案例中，我們從 GitHub API 使用 raw，而不使用 expanded 形式，因為其無法在 raw 端點中使用。 AzureEventSourceListener 會初始化以檢查用戶端執行的 HTTP 要求：

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Azure SDK GitHub 存放庫中有更多範例可供使用：Azure.Iot.ModelsRepository/samples。

自訂存放區:

解決方案可以將這些模型定義儲存在本機檔案系統、公用檔案存放區中，或使用自訂實作。