Leitfaden: Modellierung mit IoT Plug & Play

Das Herzstück von IoT Plug & Play ist ein Gerätemodell, das die Funktionen eines Geräts für eine IoT Plug & Play-fähige Anwendung beschreibt. Dieses Modell ist als ein Satz von Schnittstellen strukturiert, die Folgendes definieren:

• Eigenschaften, die den schreibgeschützten oder schreibbaren Status eines Geräts oder einer anderen Entität darstellen. Beispielsweise kann eine Geräteseriennummer eine schreibgeschützte Eigenschaft sein und die Zieltemperatur eines Thermostats eine schreibbare Eigenschaft.
• Telemetriefelder, die die von einem Gerät ausgegebenen Daten bestimmen, und zwar unabhängig davon, ob es sich bei den Daten um einen herkömmlichen Datenstrom mit Sensormesswerten, einen gelegentlichen Fehler oder eine Informationsmeldung handelt.
• Befehle, die eine Funktion oder einen Vorgang beschreiben, die bzw. der auf einem Gerät ausgeführt werden kann. Durch einen Befehl kann beispielsweise ein Gateway neu gestartet oder ein Foto mit einer Remotekamera aufgenommen werden.

Weitere Informationen dazu, wie IoT Plug & Play mit Gerätemodellen arbeitet, finden Sie im Leitfaden für IoT Plug & Play-Geräteentwickler und Leitfaden für IoT Plug & Play-Dienstentwickler.

Zum Definieren eines Modells verwenden Sie DTDL (Digital Twins Definition Language). DTDL nutzt eine JSON-Variante namens JSON-LD. Der folgende Codeausschnitt zeigt das Modell eines Thermostatgeräts mit folgenden Merkmalen:

• Eindeutige Modell-ID: dtmi:com:example:Thermostat;1
• Sendet Temperaturtelemetriedaten
• Beschreibbare Eigenschaft zum Festlegen der Zieltemperatur
• Schreibgeschützte Eigenschaft zum Melden der Maximaltemperatur seit dem letzten Neustart
• Reaktion auf einen Befehl, der die maximale, minimale und durchschnittliche Temperatur im Verlauf eines Zeitraums abfragt

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "displayName": "Temperature",
      "description": "Temperature in degrees Celsius.",
      "schema": "double",
      "unit": "degreeCelsius"
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "targetTemperature",
      "schema": "double",
      "displayName": "Target Temperature",
      "description": "Allows to remotely specify the desired target temperature.",
      "unit": "degreeCelsius",
      "writable": true
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "maxTempSinceLastReboot",
      "schema": "double",
      "unit": "degreeCelsius",
      "displayName": "Max temperature since last reboot.",
      "description": "Returns the max temperature since last device reboot."
    },
    {
      "@type": "Command",
      "name": "getMaxMinReport",
      "displayName": "Get Max-Min report.",
      "description": "This command returns the max, min and average temperature from the specified time to the current time.",
      "request": {
        "name": "since",
        "displayName": "Since",
        "description": "Period to return the max-min report.",
        "schema": "dateTime"
      },
      "response": {
        "name": "tempReport",
        "displayName": "Temperature Report",
        "schema": {
          "@type": "Object",
          "fields": [
            {
              "name": "maxTemp",
              "displayName": "Max temperature",
              "schema": "double"
            },
            {
              "name": "minTemp",
              "displayName": "Min temperature",
              "schema": "double"
            },
            {
              "name": "avgTemp",
              "displayName": "Average Temperature",
              "schema": "double"
            },
            {
              "name": "startTime",
              "displayName": "Start Time",
              "schema": "dateTime"
            },
            {
              "name": "endTime",
              "displayName": "End Time",
              "schema": "dateTime"
            }
          ]
        }
      }
    }
  ]
}

Das Thermostatmodell hat nur eine Schnittstelle. In späteren Beispielen in diesem Artikel werden komplexere Modelle mit Komponenten und Vererbung vorgestellt.

In diesem Artikel wird beschrieben, wie Sie Ihre eigenen Modelle entwerfen und erstellen. Dabei werden Themen wie Datentypen, Modellstruktur und Tools behandelt.

Weitere Informationen finden Sie in der Spezifikation Digital Twins Definition Language.

Modellstruktur

Eigenschaften, Telemetriedaten und Befehle sind in Schnittstellen gruppiert. In diesem Abschnitt wird beschrieben, wie Sie mithilfe von Schnittstellen einfache und komplexe Modelle unter Verwendung von Komponenten und Vererbung beschreiben können.

Modell-IDs

Jede Schnittstelle verfügt über einen eindeutigen Modellbezeichner für digitale Zwillinge (Digital Twin Model Identifier, DTMI). Komplexe Modelle verwenden DTMIs, um Komponenten zu bestimmen. Anwendungen können anhand der von Geräten gesendeten DTMIs in einem Repository nach Modelldefinitionen suchen.

DTMIs sollten die folgenden Benennungskonventionen verwenden:

• Das DTMI-Präfix ist dtmi:.
• Das DTMI-Suffix ist die Versionsnummer des Modells, z. B. ;2.
• Der Hauptteil des DTMI ist dem Ordner und der Datei im Modellrepository zugeordnet, in dem das Modell gespeichert ist. Die Versionsnummer ist Teil des Dateinamens.

Beispielsweise wird das vom DTMI dtmi:com:Example:Thermostat;2 identifizierte Modell in der Datei dtmi/com/example/thermostat-2.json gespeichert.

Der folgende Ausschnitt zeigt den Aufbau einer Schnittstellendefinition mit ihrem eindeutigen DTMI:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;2",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    ...
  ]
}

Keine Komponenten

Ein einfaches Modell, wie das zuvor gezeigte Thermostat, hat weder eingebettete noch kaskadierende Komponenten. Telemetrie, Eigenschaften und Befehle werden im Knoten contents der Schnittstelle definiert.

Das folgende Beispiel zeigt einen Teil eines einfachen Modells, das keine Komponenten verwendet:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "displayName": "Temperature",
      "description": "Temperature in degrees Celsius.",
      "schema": "double",
      "unit": "degreeCelsius"
    },
    {
      "@type": [
        "Property",
...

Tools wie Azure IoT Explorer und der Designer für IoT Central-Gerätevorlagen bezeichnen eine eigenständige Schnittstelle wie das Thermostat als Standardkomponente.

Der folgende Screenshot zeigt, wie das Modell im Azure IoT-Explorer-Tool angezeigt wird:

Der folgende Screenshot zeigt, wie das Modell im IoT Central-Gerätevorlagen-Designer als Standardkomponente angezeigt wird. Wählen Sie Identität anzeigen aus, um den DTMI des Modells anzuzeigen:

Die Modell-ID wird in einer Eigenschaft für Gerätezwillinge gespeichert, wie der folgenden Screenshot zeigt:

Ein DTDL-Modell ohne Komponenten ist eine nützliche Vereinfachung für Geräte oder IoT Edge-Module mit nur einer Gruppe von Telemetriedaten, Eigenschaften und Befehlen. Mit einem Modell, das keine Komponenten verwendet, können Sie aus einem vorhandenen Gerät oder Modul ganz einfach ein IoT Plug & Play-Gerät oder -Modul machen. Sie erstellen ein DTDL-Modell, das Ihr tatsächliches Gerät oder Modul beschreibt, ohne dass dabei Komponenten definiert werden müssen.

Wiederverwendung

Es gibt zwei Möglichkeiten zur Wiederverwendung von Schnittstellendefinitionen.

• Lassen Sie mehrere Komponenten in einem Modell auf andere Schnittstellendefinitionen verweisen.
• Erweitern Sie Schnittstellendefinitionen mithilfe von Vererbung.

Mehrere Komponenten

Mithilfe von Komponenten können Sie eine Modellschnittstelle als eine Assembly aus anderen Schnittstellen erstellen.

Die Thermostatschnittstelle ist zum Beispiel als Modell definiert. Sie können diese Schnittstelle als eine oder mehrere Komponenten einbinden, wenn Sie das Temperaturreglermodell definieren. Im folgenden Beispiel werden diese Komponenten als thermostat1 und thermostat2 bezeichnet.

Ein DTDL-Modell mit mehreren Komponenten verfügt über mindestens zwei Komponentenabschnitte. In jedem Abschnitt ist @type auf Component festgelegt und ein expliziter Verweis auf ein Schema enthalten, wie im folgenden Codeausschnitt zu sehen:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "description": "Device with two thermostats and remote reboot.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "DataSize"
      ],
      "name": "workingSet",
      "displayName": "Working Set",
      "description": "Current working set of the device memory in KiB.",
      "schema": "double",
      "unit": "kibibyte"
    },
    {
      "@type": "Property",
      "name": "serialNumber",
      "displayName": "Serial Number",
      "description": "Serial number of the device.",
      "schema": "string"
    },
    {
      "@type": "Command",
      "name": "reboot",
      "displayName": "Reboot",
      "description": "Reboots the device after waiting the number of seconds specified.",
      "request": {
        "name": "delay",
        "displayName": "Delay",
        "description": "Number of seconds to wait before rebooting the device.",
        "schema": "integer"
      }
    },
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1",
      "displayName": "Thermostat One",
      "description": "Thermostat One of Two."
    },
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat2",
      "displayName": "Thermostat Two",
      "description": "Thermostat Two of Two."
    },
    {
      "@type": "Component",
      "schema": "dtmi:azure:DeviceManagement:DeviceInformation;1",
      "name": "deviceInformation",
      "displayName": "Device Information interface",
      "description": "Optional interface with basic device hardware information."
    }
  ]
}

Für dieses Modell sind im Inhaltsabschnitt drei Komponenten definiert: zwei Thermostat-Komponenten und eine DeviceInformation-Komponente. Der Inhaltsabschnitt enthält auch Eigenschafts-, Telemetrie- und Befehlsdefinitionen.

Die folgenden Screenshots zeigen, wie dieses Modell in IoT Central angezeigt wird. Die Eigenschafts-, Telemetrie- und Befehlsdefinitionen im Temperaturregler werden in der Standardkomponente auf der obersten Ebene gezeigt. Die Eigenschafts-, Telemetrie- und Befehlsdefinitionen für die einzelnen Thermostate werden in den Komponentendefinitionen gezeigt:

Informationen zum Schreiben von Gerätecode, der mit Komponenten interagiert, finden Sie im Leitfaden für IoT Plug & Play-Geräteentwickler.

Informationen zum Schreiben von Dienstcode, der mit Komponenten auf einem Gerät interagiert, finden Sie im Leitfaden für IoT Plug & Play-Dienstentwickler.

Vererbung

Durch Vererbung können Sie die Funktionsmöglichkeiten einer Basisschnittstelle zum Erweitern der Funktionsmöglichkeiten einer Schnittstelle wiederverwenden. Zum Beispiel können mehrere Gerätemodelle Funktionsmöglichkeiten wie eine Seriennummer gemeinsam nutzen:

Der folgende Ausschnitt zeigt ein DTML-Modell, in dem mit dem Schlüsselwort extends die im vorherigen Diagramm gezeigte Vererbungsbeziehung definiert wird:

[
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:Thermostat;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Telemetry",
        "name": "temperature",
        "schema": "double",
        "unit": "degreeCelsius"
      },
      {
        "@type": "Property",
        "name": "targetTemperature",
        "schema": "double",
        "unit": "degreeCelsius",
        "writable": true
      }
    ],
    "extends": [
      "dtmi:com:example:baseDevice;1"
    ]
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:baseDevice;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Property",
        "name": "SerialNumber",
        "schema": "double",
        "writable": false
      }
    ]
  }
]

Der folgende Screenshot zeigt dieses Modell in der Umgebung der IoT Central-Gerätevorlage:

Wenn Sie geräte- oder dienstseitigen Code schreiben, muss Ihr Code für die Handhabung vererbter Schnittstellen nichts Besonderes tun. In dem in diesem Abschnitt gezeigten Beispiel meldet Ihr Gerätecode die Seriennummer so, als ob sie Teil der Thermostatschnittstelle wäre.

Tipps

Beim Erstellen eines Modells können Sie Komponenten und Vererbung kombinieren. Das folgende Diagramm zeigt ein thermostat-Modell, das von einer baseDevice-Schnittstelle erbt. Die baseDevice-Schnittstelle hat eine Komponente, die wiederum von einer anderen Schnittstelle erbt:

Der folgende Ausschnitt zeigt ein DTML-Modell, in dem mit den Schlüsselwörtern extends und component die im vorherigen Diagramm gezeigte Vererbungsbeziehung und Verwendung von Komponenten definiert wird:

[
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:Thermostat;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Telemetry",
        "name": "temperature",
        "schema": "double",
        "unit": "degreeCelsius"
      },
      {
        "@type": "Property",
        "name": "targetTemperature",
        "schema": "double",
        "unit": "degreeCelsius",
        "writable": true
      }
    ],
    "extends": [
      "dtmi:com:example:baseDevice;1"
    ]
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:baseDevice;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Property",
        "name": "SerialNumber",
        "schema": "double",
        "writable": false
      },
      {
        "@type" : "Component",
        "schema": "dtmi:com:example:baseComponent;1",
        "name": "baseComponent"
      }
    ]
  }
]

Datentypen

Mit Datentypen können Sie Telemetrie, Eigenschaften und Befehlsparameter definieren. Datentypen können primitiv oder komplex sein. Komplexe Datentypen verwenden Grundtypen oder andere komplexe Typen. Die maximale Tiefe komplexer Typen ist fünf Ebenen.

Einfache Typen

Die folgende Tabelle zeigt die Gruppe einfacher Typen, die Sie verwenden können:

Der folgende Ausschnitt zeigt ein Beispiel einer Telemetriedefinition mit dem Typ double im Feld schema:

{
  "@type": "Telemetry",
  "name": "temperature",
  "displayName": "Temperature",
  "schema": "double"
}

Komplexe Datentypen

Komplexe Datentypen sind vom Typ Array, Enumeration, Zuordnung, Objekt oder einem der räumlichen Typen.

Arrays

Ein Array ist ein indizierbarer Datentyp, bei dem alle Elemente den gleichen Typ haben. Der Elementtyp kann einfach oder komplex sein.

Der folgende Ausschnitt zeigt ein Beispiel einer Telemetriedefinition mit dem Typ Array im Feld schema. Die Elemente des Arrays sind boolesche Werte:

{
  "@type": "Telemetry",
  "name": "ledState",
  "schema": {
    "@type": "Array",
    "elementSchema": "boolean"
  }
}

Enumerationen

Eine Enumeration beschreibt einen Typ mit einer Gruppe benannter Bezeichnungen, die Werten zugeordnet werden. Die Werte können entweder ganze Zahlen oder Zeichenfolgen sein, die Bezeichnungen sind jedoch stets Zeichenfolgen.

Der folgende Ausschnitt zeigt ein Beispiel einer Telemetriedefinition mit dem Typ Enum im Feld schema. Die Werte in der Enumeration sind ganze Zahlen:

{
  "@type": "Telemetry",
  "name": "state",
  "schema": {
    "@type": "Enum",
    "valueSchema": "integer",
    "enumValues": [
      {
        "name": "offline",
        "displayName": "Offline",
        "enumValue": 1
      },
      {
        "name": "online",
        "displayName": "Online",
        "enumValue": 2
      }
    ]
  }
}

Maps

Eine Zuordnung ist ein Typ mit Schlüssel-Wert-Paaren, bei dem die Werte alle den gleichen Typ haben. Der Schlüssel in einer Zuordnung muss eine Zeichenfolge sein. Die Werte in einer Zuordnung können einen beliebigen Typ haben, auch einen anderen komplexen Typ.

Der folgende Ausschnitt zeigt ein Beispiel einer Eigenschaftsdefinition mit dem Typ Map im Feld schema. Die Werte in der Zuordnung sind Zeichenfolgen:

{
  "@type": "Property",
  "name": "modules",
  "writable": true,
  "schema": {
    "@type": "Map",
    "mapKey": {
      "name": "moduleName",
      "schema": "string"
    },
    "mapValue": {
      "name": "moduleState",
      "schema": "string"
    }
  }
}

Objekte

Ein Objekttyp besteht aus benannten Feldern. Die Typen der Felder in einer Objektzuordnung können primitiv oder komplex sein.

Der folgende Ausschnitt zeigt ein Beispiel einer Telemetriedefinition mit dem Typ Object im Feld schema. Die Felder im Objekt haben die Typen dateTime, duration und string:

{
  "@type": "Telemetry",
  "name": "monitor",
  "schema": {
    "@type": "Object",
    "fields": [
      {
        "name": "start",
        "schema": "dateTime"
      },
      {
        "name": "interval",
        "schema": "duration"
      },
      {
        "name": "status",
        "schema": "string"
      }
    ]
  }
}

Räumliche Typen

DTDL bietet eine Reihe räumlicher auf GeoJSON basierender Typen zur Modellierung geografischer Datenstrukturen: point, multiPoint, lineString, multiLineString, polygon, und multiPolygon. Diese Typen sind vordefinierte geschachtelte Strukturen von Arrays, Objekten und Enumerationen.

Der folgende Ausschnitt zeigt ein Beispiel einer Telemetriedefinition mit dem Typ point im Feld schema:

{
  "@type": "Telemetry",
  "name": "location",
  "schema": "point"
}

Da die räumlichen Typen arraybasiert sind, werden sie derzeit nicht in Eigenschaftsdefinitionen unterstützt.

Semantische Typen

Der Datentyp einer Eigenschafts- oder Telemetriedefinition legt das Format der Daten fest, die ein Gerät mit einem Dienst austauscht. Der semantische Typ liefert Informationen zu Telemetrie und Eigenschaften, anhand derer eine Anwendung bestimmen kann, wie ein Wert verarbeitet oder angezeigt werden soll. Zu jedem semantischen Typ gehören eine oder mehrere Einheiten. Beispielsweise sind Celsius und Fahrenheit Einheiten des semantischen Typs „Temperatur“. IoT Central-Dashboards und -Analysen können anhand der Informationen des semantischen Typs bestimmen, wie Telemetrie- oder Eigenschaftswerte dargestellt und Einheiten angezeigt werden sollen. Informationen zum Lesen der semantischen Typen mithilfe des Modellparsers finden Sie unter Grundlegendes zum Modellparser „Digital Twins“.

Der folgende Ausschnitt zeigt ein Beispiel einer Telemetriedefinition mit Informationen des semantischen Typs. Der semantische Typ Temperature wird dem Array @type hinzugefügt. Der unit-Wert degreeCelsius ist eine der gültigen Einheiten für den semantischen Typ:

{
  "@type": [
    "Telemetry",
    "Temperature"
  ],
  "name": "temperature",
  "schema": "double",
  "unit": "degreeCelsius"
}

Lokalisierung

Anwendungen wie IoT Central können mithilfe der Informationen im Modell dynamisch eine Benutzeroberfläche anhand der Daten erstellen, die mit einem IoT Plug & Play-Gerät ausgetauscht werden. Beispielsweise können die Kacheln auf einem Dashboard Namen und Beschreibungen für Telemetrie, Eigenschaften und Befehle aufweisen.

Die optionalen Felder description und displayName im Modell enthalten Zeichenfolgen für die Verwendung auf einer Benutzeroberfläche. Diese Felder können lokalisierte Zeichenfolgen enthalten, mit denen eine Anwendung eine lokalisierte Benutzeroberfläche rendern kann.

Der folgende Ausschnitt zeigt ein Beispiel einer Telemetriedefinition für Temperatur mit lokalisierten Zeichenfolgen:

{
  "@type": [
    "Telemetry",
    "Temperature"
  ],
  "description": {
    "en": "Temperature in degrees Celsius.",
    "it": "Temperatura in gradi Celsius."
  },
  "displayName": {
    "en": "Temperature",
    "it": "Temperatura"
  },
  "name": "temperature",
  "schema": "double",
  "unit": "degreeCelsius"
}

Das Hinzufügen lokalisierter Zeichenfolgen ist optional. Das folgende Beispiel enthält nur eine einzige Standardsprache:

{
  "@type": [
    "Telemetry",
    "Temperature"
  ],
  "description": "Temperature in degrees Celsius.",
  "displayName": "Temperature",
  "name": "temperature",
  "schema": "double",
  "unit": "degreeCelsius"
}

Lebenszyklus und Tools

Die vier Phasen im Lebenszyklus eines Gerätemodells sind Erstellung, Veröffentlichung, Nutzung und Versionsverwaltung:

Autor

DTML-Gerätemodelle sind JSON-Dokumente, die in einem Texteditor erstellt werden können. In IoT Central können Sie jedoch ein DTML-Modell über die grafische Benutzeroberfläche der Gerätevorlage erstellen. IoT Central ermöglicht Folgendes:

• Erstellen von Schnittstellen, die Eigenschaften, Telemetrie und Befehle definieren
• Zusammenfügen mehrerer Schnittstellen mithilfe von Komponenten
• Definieren von Vererbungsbeziehungen zwischen Schnittstellen
• Importieren und Exportieren von DTML-Modelldateien

Weitere Informationen finden Sie unter Definieren eines neuen IoT-Gerätetyps in Ihrer Azure IoT Central-Anwendung.

Es gibt eine DTDL-Erstellungserweiterung für VS Code, die sowohl DTDL v2 als auch DTDL v3 unterstützt.

Wechseln Sie zur Installation der DTDL-Erweiterung für Visual Studio Code zum DTDL-Editor für Visual Studio Code. Sie können auch in Visual Studio Code in der Ansicht Erweiterungen nach DTDL suchen.

Nachdem Sie die Erweiterung installiert haben, erstellen Sie damit DTDL-Modelldateien in Visual Studio Code (VS Code):

• Die Erweiterung bietet Syntaxüberprüfung in DTDL-Modelldateien und hebt Fehler hervor, wie im folgenden Screenshot zu sehen ist:

  

• Verwenden Sie IntelliSense und das Feature „AutoVervollständigen“ beim Bearbeiten von DTDL-Modellen:

  

• Erstellen Sie eine neue DTDL-Schnittstelle. Der Befehl DTDL: Schnittstelle erstellen erstellt eine JSON-Datei mit einer neuen Schnittstelle. Die Schnittstelle enthält Beispiele für Telemetrie, Eigenschaften und Befehlsdefinitionen.

Verwenden

Anwendungen wie IoT Central nutzen Gerätemodelle. In IoT Central ist ein Modell Teil der Gerätevorlage, die die Fähigkeiten des Geräts beschreibt. IoT Central erstellt anhand der Gerätevorlage dynamisch eine Benutzeroberfläche für das Gerät, einschließlich Dashboards und Analysen.

Eine benutzerdefinierte Lösung kann den Modellparser „Digital Twins“ verwenden, um die Funktionen eines Geräts zu verstehen, das das Modell implementiert. Weitere Informationen finden Sie unter Verwenden von IoT Plug & Play-Modellen in einer IoT-Lösung.

Version

Um sicherzustellen, dass Geräte und serverseitige Lösungen, die Modelle verwenden, weiterhin funktionieren, sind veröffentlichte Modelle unveränderbar.

Der DTMI enthält eine Versionsnummer, mit der Sie mehrere Versionen eines Modells erstellen können. Geräte und serverseitige Lösungen können die spezifische Version verwenden, die für sie vorgesehen ist.

IoT Central implementiert für Gerätemodelle weitere Versionsverwaltungsregeln. Wenn Sie eine Gerätevorlage und ihr Modell in IoT Central mit einer Version versehen, können Sie Geräte von älteren Versionen zu neueren Versionen migrieren. Migrierte Geräte können die neuen Funktionsmöglichkeiten jedoch nicht ohne ein Upgrade der Firmware nutzen. Weitere Informationen finden Sie unter Bearbeiten einer Gerätevorlage.

Veröffentlichen

Das Azure Certified Device-Programm wurde im Februar 2024 eingestellt. Daher nimmt Microsoft keine Einsendungen von DTDL-Modellen für das Repository Azure IoT Plug-and-Play-Modelle mehr an.

Wenn Sie Ihr eigenes Modell-Repository einrichten möchten, können Sie das Repository Azure IoT Plug-and-Play-Modelltools verwenden. Dieses Repository enthält den Code für das dmr-client-CLI-Tool, mit dem DTDL-Modelle überprüft, importiert und erweitert werden können. Mit diesem Tool können Sie auch Modell-Repositorys indizieren, die den Konventionen für Gerätemodell-Repositorys entsprechen.

Grenzen und Einschränkungen

In der folgenden Liste sind einige wichtige Einschränkungen und Obergrenzen für Modelle zusammengefasst:

• Zurzeit beträgt die maximale Tiefe für Arrays, Zuordnungen und Objekte fünf Ebenen.
• Arrays werden in Eigenschaftsdefinitionen nicht unterstützt.
• Sie können Schnittstellen auf eine Tiefe von 10 Ebenen erweitern.
• Eine Schnittstelle kann höchstens zwei weitere Schnittstellen erweitern.
• Eine Komponente kann keine andere Komponente enthalten.

Grundlegendes zum Modellparser „Digital Twins“

Die Digital Twins Definition Language (DTDL) wird unter Digital Twins Definition Language beschrieben. Benutzer können das NuGet-Paket für den Digital Twins-Modellparser verwenden, um ein DTDL v2 oder v3-Modell zu überprüfen und abzufragen. Das DTDL-Modell kann in mehreren Dateien definiert werden.

Installieren des DTDL-Modellparsers

Der Parser steht unter NuGet.org mit folgender ID zur Verfügung: DTDLParser. Verwenden Sie zur Installation des Parsers einen kompatiblen NuGet-Paket-Manager, z. B. den in Visual Studio oder in der dotnet-CLI.

dotnet add package DTDLParser

Verwenden des Parsers zur Überprüfung eines Modells

Der DTDLParser ist eine Bibliothek, die Sie für Folgendes verwenden können:

• Ermitteln, ob ein oder mehrere Modelle gemäß den Sprachspezifikationen v2 oder v3 gültig sind
• Identifizieren bestimmter Modellierungsfehler
• Untersuchen des Modellinhalts

Ein Modell kann aus mehreren in JSON-Dateien beschriebenen Schnittstellen bestehen. Sie können den Parser verwenden, um alle Dateien zu laden, die ein Modell definieren, und dann alle Dateien als Ganzes zu überprüfen, einschließlich zwischen den Dateien enthaltenen Verweisen.

Das DTDLParser für .NET-Repository enthält die folgenden Beispiele, die die Verwendung des Parsers veranschaulichen:

• DTDLParserResolveSample zeigt, wie eine Schnittstelle mit externen Verweisen analysiert wird; lösen Sie die Abhängigkeiten mithilfe des Azure.IoT.ModelsRepository-Clients auf.
• DTDLParserJSInteropSample zeigt, wie Sie den DTDL Parser aus JavaScript verwenden, der im Browser ausgeführt wird und .NET JSInterop verwendet.

Das DTDLParser für .NET-Repository enthält auch eine Sammlung von Lernprogrammen, die Ihnen zeigen, wie Sie den Parser zum Überprüfen von Modellen verwenden.

Die Modellparser-API ermöglicht es in vielen Szenarien, Aufgaben zu automatisieren oder zu überprüfen, die von DTDL-Modellen abhängig sind. Sie können beispielsweise dynamisch eine Benutzeroberfläche aus den Informationen im Modell erstellen.

Nächste Schritte

Nachdem Sie sich mit der Gerätemodellierung vertraut gemacht haben, finden Sie in den folgenden Artikeln weiterführende Informationen:

• Digital Twins Definition Language (DTDL)
• Azure IoT-Modellrepository