Verwenden von IoT Plug & Play-Modellen in einer IoT-Lösung
In diesem Artikel wird beschrieben, wie Sie in einer IoT-Lösung die Modell-ID eines IoT Plug & Play Geräts identifizieren und dann seine Modelldefinition abrufen.
IoT-Lösungen lassen sich in zwei Hauptkategorien unterteilen:
Eine zweckgebundene Lösung funktioniert mit einer bekannten Auswahl an Modellen für die IoT Plug & Play Geräte, die eine Verbindung mit der Lösung herstellen. Diese Modelle werden bei der Entwicklung der Lösung verwendet.
Eine modellgesteuerte Lösung funktioniert mit dem Modell jedes IoT Plug & Play-Geräts. Die Entwicklung einer modellgesteuerten Lösung ist komplexer. Der Vorteil ist jedoch, dass Ihre Lösung mit allen zukünftig hinzugefügten Geräten funktioniert. Eine modellgesteuerte IoT-Lösung ruft ein Modell ab und ermittelt mit ihm die vom Gerät implementierten Telemetriedaten, Eigenschaften und Befehle.
Zum Verwenden eines IoT Plug & Play-Modells geht eine IoT-Lösung folgendermaßen vor:
Sie identifiziert die Modell-ID des Modells, das von dem IoT Plug & Play-Gerät oder -Modul oder dem IoT Edge-Modul implementiert wird, das mit der Lösung verbunden ist.
Sie verwendet die Modell-ID zum Abrufen der Modelldefinition des verbundenen Geräts aus einem Modellrepository oder einem benutzerdefinierten Speicher.
Wenn ein IoT Plug & Play-Gerät eine Verbindung mit IoT-Hub herstellt, registriert es die Modell-ID des von ihm implementierten Modells bei IoT Hub.
IoT Hub benachrichtigt die Lösung im Rahmen des Geräteverbindungsflows mit der Gerätemodell-ID.
Eine Lösung kann die Modell-ID des IoT Plug & Play-Geräts mithilfe einer der folgenden drei Methoden erhalten:
Die Lösung kann die API zum Abrufen von Gerätezwillingen verwenden, um die Modell-ID des IoT Plug & Play-Geräts abzurufen.
Tipp
Verwenden Sie für Module und IoT Edge-Module ModuleClient.getTwin.
Im folgenden Antwortausschnitt eines Gerätezwillings enthält modelId
die Modell-ID eines IoT Plug & Play-Geräts:
{
"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": {...}
}
}
Die Lösung kann die API zum Abrufen von digitalen Zwillingen verwenden, um die Modell-ID des Modells abzurufen, das vom IoT Plug & Play-Gerät implementiert wurde.
Im folgenden Antwortausschnitt eines digitalen Zwillings enthält $metadata.$model
die Modell-ID eines IoT Plug & Play-Geräts:
{
"$dtId": "sample-device",
"$metadata": {
"$model": "dtmi:com:example:TemperatureController;1",
"serialNumber": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}
Eine Geräteverbindung führt zu einer Benachrichtigung über ein Änderungsereignis für einen digitalen Zwilling. Eine Lösung muss diese Ereignisbenachrichtigungen abonnieren. Informationen zum Aktivieren des Routings für Ereignisse bei digitalen Zwillingen finden Sie unter Verwenden des IoT Hub-Nachrichtenroutings zum Senden von D2C-Nachrichten an verschiedene Endpunkte.
Die Lösung kann das im folgenden Codeausschnitt gezeigte Ereignis verwenden, um mehr über das IoT Plug & Play-Gerät zu erfahren, das eine Verbindung herstellt, und seine Modell-ID abzurufen:
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"
}
]
Eine Lösung verwendet die zuvor identifizierte Modell-ID, um die zugehörige Modelldefinition abzurufen.
Eine Lösung kann die Modelldefinition mithilfe einer der folgenden Optionen erhalten:
Lösungen können DTDL-Modelle aus dem Gerätemodellrepository (DMR, Device Model Repository) abrufen. Das DMR ist ein öffentliches Repository, das von Microsoft gehostet wird und eine Sammlung kuratierter DTDL-Modelle enthält. Die im DMR gespeicherten öffentlichen Gerätemodelle stehen für alle zur Verfügung und können vom öffentlichen Endpunkt https://devicemodels.azure.com aus in Benutzeranwendungen integriert werden.
Nachdem Sie die Modell-ID für eine neue Geräteverbindung identifiziert haben, führen Sie die folgenden Schritte aus:
Rufen Sie die Modelldefinition mithilfe der Modell-ID aus dem Modellrepository ab. Weitere Informationen finden Sie unter Auflösen von Modellen.
Mithilfe der Modelldefinition des verbundenen Geräts können Sie die Funktionen des Geräts auflisten.
Mithilfe der aufgelisteten Funktionen des Geräts können Sie Benutzern ermöglichen, mit dem Gerät zu interagieren.
Die DMR-Konventionen enthalten weitere Artefakte zur Vereinfachung der Nutzung von gehosteten Modellen. Diese Features sind für benutzerdefinierte oder private Repositorys optional.
- Index: Alle verfügbaren DTMIs werden über einen Index verfügbar gemacht, der aus einer Sequenz von JSON-Dateien besteht, z. B.: https://devicemodels.azure.com/index.page.2.json
- Erweitert. Eine Datei mit allen Abhängigkeiten ist für jede Schnittstelle verfügbar, z. B.: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
- Metadaten. Diese Datei macht wichtige Attribute eines Repositorys verfügbar und wird regelmäßig mit der momentaufnahme der neuesten veröffentlichten Modelle aktualisiert. Sie enthält Features, die ein Repository implementiert, z. B. ob der Modellindex oder erweiterte Modelldateien verfügbar sind. Sie können auf die DMR-Metadaten unter zugreifen. https://devicemodels.azure.com/metadata.json
Um programmgesteuert auf die öffentlichen DTDL-Modelle im DMR zuzugreifen, können Sie das im NuGet-Paket Azure.IoT.ModelsRepository verfügbare ModelsRepositoryClient
-Objekt verwenden. Dieser Client ist standardmäßig so konfiguriert, dass er das unter devicemodels.azure.com verfügbare öffentliche DMR abfragt. Er kann für ein beliebiges benutzerdefiniertes Repository konfiguriert werden.
Der Client akzeptiert einen DTMI
als Eingabe und gibt ein Wörterbuch mit allen erforderlichen Schnittstellen zurück:
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));
Die erwartete Ausgabe zeigt den DTMI
der drei in der Abhängigkeitskette gefundenen Schnittstellen an:
dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1
Der ModelsRepositoryClient
kann so konfiguriert werden, dass ein benutzerdefiniertes DMR (über HTTPs verfügbar) und die Abhängigkeitsauflösung mit dem ModelDependencyResolution
-Flag angegeben wird:
- Deaktiviert. Gibt nur die angegebene Schnittstelle zurück, ohne jegliche Abhängigkeit.
- Aktiviert. Gibt alle Schnittstellen in der Abhängigkeitskette zurück.
Tipp
Benutzerdefinierte Repositorys machen die .expanded.json
-Datei möglicherweise nicht verfügbar. Wenn diese Datei nicht verfügbar ist, wird vom Client ein Fallback ausgeführt, um jede Abhängigkeit lokal zu verarbeiten.
Im nächsten Codebeispiel wird gezeigt, wie der ModelsRepositoryClient
mit einer benutzerdefinierten Repository-Basis-URL initialisiert wird. In diesem Fall werden die raw
-URLs aus der GitHub-API ohne die expanded
-Variante verwendet, da diese am raw
-Endpunkt nicht verfügbar ist. Der AzureEventSourceListener
wird initialisiert, um die vom Client ausgeführte HTTP-Anforderung zu überprüfen:
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));
Im Azure SDK-Repository auf GitHub finden Sie weitere Beispiele: Azure.Iot.ModelsRepository/samples.
Lösungen können diese Modelldefinitionen in einem lokalen Dateisystem oder in einem öffentlichen Dateispeicher speichern oder eine benutzerdefinierte Implementierung nutzen.
Nachdem Sie die Modell-ID für eine neue Geräteverbindung identifiziert haben, führen Sie die folgenden Schritte aus:
Rufen Sie die Modelldefinition mithilfe der Modell-ID aus Ihrem benutzerdefinierten Speicher ab.
Mithilfe der Modelldefinition des verbundenen Geräts können Sie die Funktionen des Geräts auflisten.
Mithilfe der aufgelisteten Funktionen des Geräts können Sie Benutzern ermöglichen, mit dem Gerät zu interagieren.
Nachdem Sie gelernt haben, wie IoT Plug & Play-Modelle in eine IoT-Lösung integriert werden, finden Sie hier einige der empfohlenen nächsten Schritte: