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

發行項
03/22/2024

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

IoT 解決方案有兩大類別：

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

若要使用 IoT 隨插即用模型，IoT 解決方案：

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

識別模型標識碼

當 IoT 隨插即用裝置連線到 IoT 中樞時，它會向 IoT 中樞註冊其實作的模型型號標識符。

IoT 中樞將裝置型號標識碼通知解決方案作為裝置連線流程的一部分。

解決方案可以使用下列三種方法之一，取得 IoT 隨插即用裝置的型號識別碼：

取得裝置對應項 API

解決方案可以使用取得裝置對應項 API 來擷取 IoT 隨插即用裝置的模型標識碼。

提示

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

在下列裝置對應項回應代碼段中，modelId包含 IoT 隨插即用裝置的模型識別碼：

{
    "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 隨插即用裝置所實作之模型的模型識別碼。

在下列數字對應項回應代碼段中，$metadata.$model包含 IoT 隨插即用裝置的模型識別碼：

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

數字對應項變更事件通知

裝置聯機會導致 Digital Twin 變更事件通知。解決方案必須訂閱此事件通知。若要瞭解如何啟用數字對應項事件的路由，請參閱使用 IoT 中樞訊息路由將裝置到雲端訊息傳送至不同的端點。

解決方案可以使用下列代碼段中所示的事件來了解連線並取得其型號識別碼 IoT 隨插即用裝置：

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"
  }
]

擷取模型定義

解決方案會使用上述識別的模型標識符來擷取對應的模型定義。

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

模型存放庫

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

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

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

解析模型

DMR 慣例包含其他成品，可簡化託管模型的耗用量。這些功能是 自定義或私人存放庫的選擇性 功能。

索引。所有可用的 DTMIS 都會透過 JSON 檔案序列所組成的索引 公開，例如： https://devicemodels.azure.com/index.page.2.json
展開。具有所有相依性的檔案可供每個介面使用，例如： https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Metadata. 此檔案會公開存放庫的主要屬性，並使用最新的已發佈模型快照集定期重新整理。它包含存放庫實作的功能，例如模型索引或擴充模型檔案是否可供使用。您可以在存取 DMR 元數據 https://devicemodels.azure.com/metadata.json

若要以程式設計方式存取 DMR 中的公用 DTDL 模型，您可以使用 ModelsRepositoryClient NuGet 套件 Azure.IoT.ModelsRepository 中提供的。此客戶端預設會設定為查詢 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可以設定為透過 HTTP（s）- 查詢自訂 DMR，並使用旗標指定相依性解析ModelDependencyResolution：

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

提示

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

下列範例程式代碼示範如何使用自定義存放庫基底 URL 初始化 ModelsRepositoryClient ，在此情況下 raw ，使用 GitHub API 中的 URL 而不使用 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。

自訂存放區

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