Erfahren Sie mehr über Zwillingsmodelle und wie man sie in Azure Digital Twins definiert

  • Artikel

Ein Hauptmerkmal von Azure Digital Twins ist die Fähigkeit, Ihr eigenes Vokabular zu definieren und Ihren Zwillingsgraph in den selbstdefinierten Begriffen Ihres Unternehmens zu erstellen. Diese Funktion wird mittels von Benutzern bereitgestellten Modellen ermöglicht. Sie können sich Modelle in einer Beschreibung Ihrer Umgebung als die Nomen vorstellen. Azure Digital Twins-Modelle werden in der auf JSON-LD basierenden Sprache Digital Twin Definition Language (DTDL) dargestellt.

Ein Modell ähnelt einer Klasse einer objektorientierten Programmiersprache und definiert eine Datenform für ein bestimmtes Konzept in Ihrer realen Arbeitsumgebung. Modelle haben Namen (wie z. B. Raum oder Temperatursensor) und enthalten Elemente wie Eigenschaften, Telemetrie und Beziehungen, die beschreiben, welche Aktivitäten dieser Entitätstyp in Ihrer Umgebung durchführt. Später nutzen Sie diese Modelle, um digitale Zwillinge zu erstellen, die bestimmte Entitäten gemäß dieser Typbeschreibung darstellen.

Digital Twin Definition Language (DTDL) für Modelle

Modelle für Azure Digital Twins werden mithilfe von DTDL (Digital Twins Definition Language) definiert.

Sie können die vollständige Sprachbeschreibung für DTDL v3 unter GitHub: DTDL Version 3 Language Description anzeigen. Diese Seite enthält DTDL-Referenzdetails und Beispiele, die Ihnen bei den ersten Schritten beim Schreiben Ihrer eigenen DTDL-Modelle helfen.

DTDL basiert auf JSON-LD und ist von der Programmiersprache unabhängig. DTDL ist nicht exklusiv für Azure Digital Twins. Es wird auch verwendet, um Gerätedaten in anderen IoT-Diensten wie IoT Plug & Play darzustellen.

Der restliche Artikel bietet eine Übersicht über die Verwendung der Sprache in Azure Digital Twins.

Unterstützte DTDL-Versionen

Azure Digital Twins unterstützt DTDL-Versionen 2 und 3 (in der Dokumentation auf v2 bzw. v3 gekürzt). V3 ist die empfohlene Wahl für die Modellierung in Azure Digital Twins basierend auf den erweiterten Funktionen, einschließlich:

Wenn diese Features in der Dokumentation erläutert werden, werden sie von einem Hinweis begleitet, dass sie nur in DTDL v3 verfügbar sind. Eine vollständige Liste der Unterschiede zwischen DTDL v2 und v3 finden Sie unter DTDL v3 Language Description: Changes from Version 2.

Azure Digital Twins unterstützt auch die Verwendung einer Mischung aus v2- und v3-Modellen innerhalb derselben instance. Beachten Sie beim gemeinsamen Verwenden von Modellen beider Versionen die folgenden Einschränkungen:

  • Eine v2-Schnittstelle kann keine v3-Schnittstelle erweitern oder eine Komponente mit einer v3-Schnittstelle als Schema aufweisen.
  • Umgekehrt kann eine v3-Schnittstelle eine v2-Schnittstelle erweitern, und eine v3-Schnittstelle kann eine Komponente mit einer v2-Schnittstelle als Schema aufweisen.
  • Beziehungen können in beide Richtungen verweisen, von einer v2-Modellquelle zu einem v3-Modellziel oder umgekehrt von einer v3-Modellquelle zu einem v2-Modellziel.

Sie können auch vorhandene v2-Modelle zu v3 migrieren. Anweisungen hierzu finden Sie unter Konvertieren von v2-Modellen in v3.

Übersicht über das Modell

Modelle von Digital Twin-Typen können ein einem beliebigen Text-Editor geschrieben werden. Die Sprache DTDL folgt der JSON-Syntax, weshalb Sie Modelle mit der Erweiterung .json speichern müssen. Durch Verwendung der JSON-Erweiterung wird vielen Text-Editoren zur Programmierung ermöglicht, eine grundlegende Syntaxprüfung und Hervorhebung für Ihre DTDL-Dokumente bereitzustellen. Es ist auch eine DTDL-Erweiterung für Visual Studio Code verfügbar.

Hier sehen Sie die Felder in einer Modellschnittstelle:

Feld BESCHREIBUNG
@id Ein Digital Twin Model Identifier (DTMI) für das Modell im Format dtmi:<domain>:<unique-model-identifier>;<model-version-number>. In DTDL v3 kann die Versionsnummer weggelassen oder als zweiteilige (<major>.<minor>) Versionsnummer strukturiert werden.
@type Gibt die Art der beschriebenen Informationen an. Bei einer Schnittstelle ist der Typ Interface.
@context Legt den Kontext für das JSON-Dokument fest. Modelle sollten für DTDL v2 oder dtmi:dtdl:context;3 für DTDL v3 verwendet dtmi:dtdl:context;2 werden. DTDL v3-Modelle können auch zusätzliche Featureerweiterungen in diesem Feld benennen.
displayName [optional] Bietet Ihnen die Möglichkeit, einen benutzerfreundlichen Namen für das Modell zu definieren. Wenn Sie dieses Feld nicht verwenden, verwendet das Modell seinen vollständigen DTMI-Wert.
contents Alle übrigen Schnittstellendaten werden hier als ein Array von Attributdefinitionen platziert. Jedes Attribut muss @type (Property, Telemetry, Relationship oder Component) bereitstellen, um die Art der Schnittstelleninformationen zu bestimmen, die beschrieben werden, und dann eine Reihe von Eigenschaften, die das eigentliche Attribut definieren. Im nächsten Abschnitt werden die Modellattribute ausführlich beschrieben.

Hier sehen Sie ein Beispiel für ein grundlegendes DTDL-Modell. Dieses Modell beschreibt ein Home-Objekt mit einer Eigenschaft für eine ID. Das Home-Modell definiert auch eine Beziehung zu einem Floor-Modell, das verwendet werden kann, um anzugeben, dass ein Home-Zwilling mit bestimmten Floor-Zwillingen verbunden ist.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Modellattribute

Die wichtigsten Informationen zu einem Modell werden durch ihre Attribute angegeben, die im Abschnitt contents der Modellschnittstelle definiert sind. Hier sehen Sie die Attribute, die in DTDL zur Verfügung stehen. Eine DTDL-Modellschnittstelle kann keines, eines oder mehrere der folgenden Felder enthalten:

  • Eigenschaft: Eigenschaften sind Datenfelder, die den Zustand einer Entität repräsentieren (wie die Eigenschaften in vielen objektorientierten Programmiersprachen). Eigenschaften haben Sicherungsspeicher und können jederzeit gelesen werden. Weitere Informationen finden Sie weiter unten unter Eigenschaften und Telemetrie.

  • Telemetrie: Telemetriefelder stellen Messungen oder Ereignisse dar und dienen häufig zur Beschreibung von Sensormesswerten von Geräten. Im Gegensatz zu Eigenschaften wird Telemetrie nicht in einem digitalen Zwilling gespeichert. Telemetrie ist eine Reihe von zeitgebundenen Datenereignissen, die bei ihrem Auftreten verarbeitet werden müssen. Weitere Informationen finden Sie weiter unten unter Eigenschaften und Telemetrie.

  • Beziehung: Anhand von Beziehungen können Sie darstellen, wie ein Digital Twin mit anderen Digital Twins zusammenarbeiten kann. Beziehungen können verschiedene semantische Bedeutungen darstellen, wie z. B. contains („Stockwerk enthält Raum“), cools („Klimaanlage kühlt Raum“) oder isBilledTo („Kompressor wird Benutzer in Rechnung gestellt“). Beziehungen ermöglichen der Lösung, einen Graphen miteinander verbundener Entitäten zu erstellen. Beziehungen können auch eigene Eigenschaften aufweisen. Weitere Informationen finden Sie weiter unten unter Beziehungen.

  • Komponenten: Komponenten ermöglichen Ihnen nach Wunsch das Erstellen Ihrer Modellschnittstelle als Zusammensetzung anderer Schnittstellen. Ein Beispiel für eine Komponente ist eine frontCamera-Schnittstelle (und eine andere Komponentenschnittstelle backCamera), die zum Definieren eines Modells für ein Telefon verwendet wird. Sie müssen zunächst eine Schnittstelle für Frontkamera so definieren, als wäre sie ihr eigenes Modell. Danach können Sie beim Definieren von Smartphone darauf verweisen.

    Beschreiben Sie mit einer Komponente etwas, das ein integraler Bestandteil Ihrer Lösung ist, aber keine separate Identität benötigt und im Digital Twin-Graph nicht unabhängig erstellt, gelöscht oder neu angeordnet werden muss. Wenn Sie möchten, dass Entitäten im Zwillingsgraphen unabhängig voneinander existieren, stellen Sie sie als separate Digital Twins verschiedener Modelle dar, die durch Beziehungen verbunden sind.

    Tipp

    Komponenten können auch zur Organisation verwendet werden, um Sätze verwandter Eigenschaften innerhalb einer Modellschnittstelle zu gruppieren. In diesem Fall können Sie sich jede Komponente als einen Namespace oder „Ordner“ innerhalb der Schnittstelle vorstellen.

    Weitere Informationen finden Sie weiter unten unter Komponenten.

Hinweis

Die DTDL v3-Sprachbeschreibung definiert auch Befehle, also Methoden, die auf einem digitalen Zwilling ausgeführt werden können (z. B. ein Zurücksetzungsbefehl oder ein Befehl zum Ein- oder Ausschalten eines Lüfters). Allerdings werden Befehle in Azure Digital Twins derzeit nicht unterstützt.

Eigenschaften und Telemetrie

In diesem Abschnitt werden Eigenschaften und Telemetriedaten in DTDL-Modellen ausführlicher erläutert.

Umfassende Informationen zu den Feldern, die als Teil einer Eigenschaft angezeigt werden können, finden Sie unter Eigenschaft in der DTDL v3-Sprachbeschreibung. Umfassende Informationen zu den Feldern, die als Teil von Telemetriedaten angezeigt werden können, finden Sie unter Telemetrie in der DTDL v3-Sprachbeschreibung.

Hinweis

Das writable DTDL-Attribut für Eigenschaften wird derzeit in Azure Digital Twins nicht unterstützt. Sie kann dem Modell hinzugefügt werden, aber Azure Digital Twins wird sie nicht erzwingen. Weitere Informationen finden Sie unter Dienstspezifische DTDL-Notizen.

Unterschied zwischen Eigenschaften und Telemetrie

Hier finden Sie einige Anleitungen zur konzeptionellen Unterscheidung zwischen DTDL-Eigenschaften und -Telemetriedaten in Azure Digital Twins.

  • Es wird erwartet, dass Eigenschaften über einen zugrunde liegenden Speicher verfügen. So können Sie eine Eigenschaft jederzeit lesen und ihren Wert abrufen. Wenn die Eigenschaft schreibbar ist, können Sie darin auch einen Wert speichern.
  • Telemetrie ähnelt eher einem Datenstrom von Ereignissen. Es handelt sich dabei um eine Reihe von Datennachrichten mit nur kurzer Lebensdauer. Wenn Sie kein Lauschen auf das Ereignis und keine Maßnahmen einrichten, die bei Eintreten des Ereignisses zu ergreifen sind, gibt es zu einem späteren Zeitpunkt keine Ablaufverfolgung für das Ereignis. Sie können dann nicht mehr zur Ablaufverfolgung zurückkehren und diese lesen.
    • In C#-Begriffen ist Telemetrie wie ein C#-Ereignis.
    • In IoT-Begriffen ist Telemetrie normalerweise eine einzelne Messung, die von einem Gerät gesendet wird.

Telemetrie wird oft bei IoT-Geräten verwendet, weil viele Geräte die von ihnen generierten Messwerte nicht speichern können (oder aus mangelnder Relevanz nicht speichern). Stattdessen senden sie die Messwerte einfach als Datenstrom von „Telemetrieereignissen“. In diesem Fall können Sie auf dem Gerät nicht jederzeit den neuesten Wert des Telemetriefelds abfragen. Sie müssen auf die Nachrichten vom Gerät lauschen und bei deren Eintreffen Maßnahmen ergreifen.

Wenn Sie ein Modell in Azure Digital Twins entwerfen, verwenden Sie deshalb in den meisten Fällen wahrscheinlich Eigenschaften zum Modellieren Ihrer Zwillinge. Dies erlaubt Ihnen die Nutzung des zugrunde liegenden Speichers und die Möglichkeit zum Lesen und Abfragen der Datenfelder.

Telemetrie und Eigenschaften arbeiten oft zusammen, um den Dateneingang von Geräten zu verarbeiten. Sie verwenden häufig deren Eingangsfunktion zum Lesen der Telemetrie oder der Eigenschaftsereignisse von Geräten und legen als Reaktion darauf eine Eigenschaft in Azure Digital Twins fest.

Sie können ein Telemetrieereignis auch über die Azure Digital Twins-API veröffentlichen. Telemetrie ist ein kurzlebiges Ereignis, für das ein Listener erforderlich ist.

Schema

Gemäß DTDL kann das Schema für die Attribute Eigenschaft und Telemetrie aus einfachen Standardtypen (integer, double, string und boolean) und anderen Typen wie dateTime und duration bestehen.

Zusätzlich zu den einfachen Typen können die Felder „Eigenschaft“ und „Telemetrie“ diese komplexen Typen enthalten:

  • Object
  • Map
  • Enum
  • Array, abhängig von der DTDL-Version
    • Für Eigenschaften Array wird der Typ in DTDL v2 nicht unterstützt, nur DTDL v3. Für Telemetriedaten Array wird der Typ sowohl in DTDL v2 als auch in v3 unterstützt.

Sie können auch semantische Typen sein, die es Ihnen gestatten, Werte mit Einheiten zu versehen. In DTDL v2 werden semantische Typen nativ unterstützt. in DTDL v3 können Sie sie mit einer Featureerweiterung einschließen.

Einfache Beispiele für Eigenschaften und Telemetrie

Hier sehen Sie ein einfaches Beispiel für eine Eigenschaft eines DTDL-Modells. Dieses Beispiel zeigt die ID-Eigenschaft eines Home-Objekts.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Hier sehen Sie ein einfaches Beispiel für das Feld Telemetrie eines DTDL-Modells. Dieses Beispiel zeigt die Temperaturtelemetrie an einem Sensor.

{
  "@id": "dtmi:com:adt:dtsample:sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Sensor",
  "contents": [
    {
    "@type": "Telemetry",
    "name": "Temperature",
    "schema": "double"      
    },
    {
      "@type": "Property",
      "name": "humidity",
      "schema": "double"      
    }
  ]
}

Beispiel für komplexen Objekttyp

Eigenschaften und Telemetriedaten können komplexe Typen aufweisen, einschließlich des Typs Object.

Das folgende Beispiel zeigt eine andere Version des Home-Modells mit einer Eigenschaft für seine Adresse. address ist ein Objekt mit eigenen Feldern für Straße, Ort, Bundesland und PLZ.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Beispiel für den semantischen DTDL v2-Typ

Semantische Typen dienen zum Ausdrücken eines Werts mit einer Einheit. Eigenschaften und Telemetriedaten für Azure Digital Twins können jeden der semantischen Typen verwenden, die von DTDL unterstützt werden.

In DTDL v2 werden semantische Typen nativ unterstützt. Weitere Informationen zu semantischen Typen in DTDL v2 finden Sie unter Semantiktypen in der DTDL v2-Sprachbeschreibung. Weitere Informationen zu semantischen Typen in DTDL v3 finden Sie unter quantitativeTypes DTDL v3-Featureerweiterung.

Das folgende Beispiel zeigt ein DTDL v2-Sensormodell mit einer semantischen Typtelemetrie für Temperature und einer semantischen Typeigenschaft für Humidity.

{
  "@id": "dtmi:com:adt:dtsample:v2sensor;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Sensor (v2 model)",
  "contents": [
    {
      "@type": ["Telemetry", "Temperature"],
      "name": "temperature",
      "schema": "double",
      "unit": "degreeFahrenheit"    
    },
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre" 
    }
  ]
}

Hinweis

„Property“ oder „Telemetry“ muss das erste Element des @type Arrays sein, gefolgt vom semantischen Typ. Andernfalls ist das Feld im Azure Digital Twins-Explorer möglicherweise nicht sichtbar.

Beziehungen

In diesem Abschnitt werden Beziehungen in DTDL-Modellen ausführlicher erläutert.

Eine umfassende Liste der Felder, die als Teil einer Beziehung angezeigt werden können, finden Sie unter Beziehung in der DTDL v3-Sprachbeschreibung.

Hinweis

Die DTDL-Attribute writable, minMultiplicity und maxMultiplicity für Beziehungen werden derzeit in Azure Digital Twins nicht unterstützt. Sie können dem Modell hinzugefügt werden, aber Azure Digital Twins wird sie nicht durchsetzen. Weitere Informationen finden Sie unter Dienstspezifische DTDL-Notizen.

Beispiel für eine einfache Beziehung

Hier sehen Sie ein einfaches Beispiel für eine Beziehung in einem DTDL-Modell. Dieses Beispiel zeigt eine Beziehung für ein Home-Modell, die es ihm erlaubt, eine Verbindung mit einem Floor-Modell herzustellen.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "contents": [
    {
      "@type": "Property",
      "name": "id",
      "schema": "string"     
    },    
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1"
    }
  ]
}

Hinweis

Für Beziehungen ist @id ein optionales Feld. Wenn @id nicht angegeben wird, wird vom Prozessor der Schnittstelle für digitale Zwillinge eine ID zugewiesen.

Gezielte und nicht gezielte Beziehungen

Beziehungen können mit oder ohne Ziel definiert werden. Ein Ziel gibt an, welche Typen von Zwillingen die Beziehung erreichen kann. Beispielsweise können Sie ein Ziel einschließen, um anzugeben, dass ein Home-Modell nur eine rel_has_floors-Beziehung mit Zwillingen besitzen kann, die Floor-Zwillinge sind.

Manchmal möchten Sie vielleicht eine Beziehung ohne ein bestimmtes Ziel definieren, damit die Beziehung eine Verbindung mit vielen verschiedenen Typen von Zwillingen herstellen kann.

Hier sehen Sie ein Beispiel für eine Beziehung in einem DTDL-Modell, die kein Ziel aufweist. In diesem Beispiel dient die Beziehung zum Definieren der Sensoren, über die ein Raum verfügen kann, und die Beziehung kann mit jedem Typ verbunden werden.

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "schema": "double",
      "unit": "gramPerCubicMetre"
    },
    {
      "@type": "Component",
      "name": "thermostat",
      "schema": "dtmi:com:adt:dtsample:thermostat;1"
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
      "name": "rel_has_sensors",
      "displayName": "Room has sensors"

Eigenschaften von Beziehungen

DTDL ermöglicht auch, dass Beziehungen eigene Eigenschaften aufweisen. Wenn Sie eine Beziehung innerhalb eines DTDL-Modells definieren, kann die Beziehung über ein eigenes properties Feld verfügen, in dem Sie benutzerdefinierte Eigenschaften definieren können, um den beziehungsspezifischen Zustand zu beschreiben.

Das folgende Beispiel zeigt eine andere Version des Home-Modells, bei der die rel_has_floors-Beziehung über eine Eigenschaft verfügt, die darstellt, wann die zugehörige Etage („Floor“) zuletzt belegt wurde.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": "Property",
      "name": "address",
      "schema": {
        "@type": "Object",
        "fields": [
          {
            "name": "street",
            "schema": "string"
          },
          {
            "name": "city",
            "schema": "string"
          },
          {
            "name": "state",
            "schema": "string"
          },
          {
            "name": "zip",
            "schema": "string"
          }
        ]
      }
    },
    {
      "@type": "Relationship",
      "@id": "dtmi:com:adt:dtsample:home:rel_has_floors;1",
      "name": "rel_has_floors",
      "displayName": "Home has floors",
      "target": "dtmi:com:adt:dtsample:floor;1",
      "properties": [
        {
          "@type": "Property",
          "name": "lastOccupied",
          "schema": "dateTime"
        }
      ]
    }
  ]
}

Komponenten

In diesem Abschnitt werden Komponenten in DTDL-Modellen ausführlicher erläutert.

Eine umfassende Liste der Felder, die als Teil einer Komponente angezeigt werden können, finden Sie unter Komponente in der DTDL v3-Sprachbeschreibung.

Beispiel für eine einfache Komponente

Hier sehen Sie ein einfaches Beispiel für eine Komponente eines DTDL-Modells. In diesem Beispiel wird ein Raummodell (Room) veranschaulicht, bei dem ein Thermostatmodell als Komponente verwendet wird.

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "schema": "double",
        "unit": "gramPerCubicMetre"
      },
      {
        "@type": "Component",
        "name": "thermostat",
        "schema": "dtmi:com:adt:dtsample:thermostat;1"
      },
      {
        "@type": "Relationship",
        "@id": "dtmi:com:adt:dtsample:room:rel_has_sensors;1",
        "name": "rel_has_sensors",
        "displayName": "Room has sensors"
      }
    ]
  },
  {
    "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "schema": "double",
        "unit": "degreeFahrenheit"
      }
    ]
  }
]

Falls andere Modelle bei dieser Lösung ebenfalls ein Thermostat enthalten sollen, kann in den entsprechenden eigenen Definitionen der Modelle genauso wie für den Raum auf dasselbe Thermostatmodell als Komponente verwiesen werden.

Wichtig

Die Komponentenschnittstelle (im obigen Beispiel ein Thermostat) muss in demselben Array wie alle anderen Schnittstellen definiert sein, von denen diese verwendet wird (im obigen Beispiel der Raum), damit der Komponentenverweis gefunden werden kann.

Vererbung im Modell

Mitunter möchten Sie ein Modell eventuell weiter spezialisieren. Beispielsweise kann es sinnvoll sein, mit einem generischen Modell wie Raum und spezialisierte Varianten Konferenzraum und Fitnessraum zu arbeiten. Um Spezialisierung ausdrücken zu können, unterstützt DTDL Vererbung. Schnittstellen können von einer oder mehreren Schnittstellen erben. Fügen Sie hierzu dem Modell ein Feld extends hinzu.

Der Abschnitt extends ist ein Schnittstellenname oder ein Array aus Schnittstellennamen (sodass die erweiternde Schnittstelle von mehreren übergeordneten Modellen erben kann). Ein einzelnes übergeordnetes Element kann als Basismodell für mehrere erweiternde Schnittstellen dienen.

Hinweis

In DTDL v2 können maximal extends zwei Schnittstellen aufgelistet werden. In DTDL v3 gibt es keine Beschränkung für die Anzahl der unmittelbaren Werte für einen extends.

In DTDL v2 und v3 beträgt die Gesamttiefegrenze für eine extends Hierarchie 10.

Im folgenden Beispiel wird das Home-Modell aus dem vorherigen DTDL-Beispiel als Untertyp eines größeren „Kern“-Modells (Core) neu konzipiert. Das übergeordnete Modell (Core) wird zuerst definiert. Anschließend baut das untergeordnete Modell (Home) unter Verwendung von extends darauf auf.

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;3",
    "displayName": "Core",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "schema": "string"
        },
        {
            "@type": "Property",
            "name": "name",
            "schema": "string"
        }
    ]
}

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;3",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

In diesem Fall trägt Core eine ID und einen Namen zu Home bei. Andere Modelle können auch das Core-Modell erweitern, um diese Eigenschaften ebenfalls zu erhalten. Hier sehen Sie ein Raummodell, das dieselbe übergeordnete Schnittstelle erweitert:

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "displayName": "Room",

Nach Anwendung der Vererbung macht die erweiternde Schnittstelle alle Eigenschaften in der gesamten Vererbungskette verfügbar.

Die erweiternde Schnittstelle kann keine Definitionen der übergeordneten Schnittstellen ändern, sondern sie nur ergänzen. Sie kann auch keine Fähigkeit neu definieren, die bereits in einer ihrer übergeordneten Schnittstellen definiert ist (selbst wenn die Fähigkeiten als gleich definiert sind). Wenn beispielsweise eine übergeordnete Schnittstelle die double-Eigenschaft massdefiniert, kann die erweiternde Schnittstelle keine Deklaration von mass enthalten, selbst wenn es sich ebenfalls um double handelt.

DTDL v3-Funktionserweiterungen

DTDL v3 ermöglicht Spracherweiterungen, die zusätzliche Metamodelklassen definieren, mit denen Sie umfangreichere Modelle schreiben können. In diesem Abschnitt werden die Funktionserweiterungsklassen beschrieben, mit denen Sie Ihren DTDL v3-Modellen Nicht-Kernfeatures hinzufügen können.

Jede Featureerweiterung wird durch ihren Kontextspezifizierer identifiziert, bei dem es sich um einen eindeutigen DtmI-Wert (Digital Twin Model Identifier) handelt. Um eine Featureerweiterung in einem Modell zu aktivieren, fügen Sie den Kontextbezeichner der Erweiterung dem Feld des @context Modells hinzu (zusammen mit dem allgemeinen DTDL-Kontextspezifizierer von dtmi:dtdl:context;3). Sie können demselben Modell mehrere Featureerweiterungen hinzufügen.

Hier sehen Sie ein Beispiel dafür, wie dieses @context Feld bei Featureerweiterungen aussehen könnte. Der folgende Auszug stammt aus einem Modell, das sowohl die QuantitativeTypes-Erweiterung als auch die Anmerkungserweiterung verwendet.

  "@context": [
      "dtmi:dtdl:context;3",
      "dtmi:dtdl:extension:quantitativeTypes;1",
      "dtmi:dtdl:extension:annotation;1"
  ]

Nachdem Sie einem Modell eine Featureerweiterung hinzugefügt haben, haben Sie Zugriff auf die zusätzlichen Typen dieser Erweiterung innerhalb des Modells. Sie können dem @type Feld eines DTDL-Elements zusätzliche Typen hinzufügen, um dem Element zusätzliche Funktionen zu geben. Der zusätzliche Typ kann dem Element zusätzliche Eigenschaften hinzufügen.

Hier sehen Sie beispielsweise einen Auszug aus einem Modell, das die Anmerkungserweiterung verwendet. Diese Erweiterung verfügt über einen zusätzlichen Typ namens ValueAnnotation, der im folgenden Beispiel einem Telemetrieelement hinzugefügt wird. Das Hinzufügen dieses zusätzlichen Typs zum Telemetry-Element ermöglicht dem Element ein zusätzliches annotates Feld, das verwendet wird, um eine andere Eigenschaft oder Telemetrie anzugeben, die von diesem Element mit Anmerkungen versehen ist.

{
  "@type": [ "Telemetry", "ValueAnnotation" ],
  "name": "currentTempAccuracy",
  "annotates": "currentTemp",
  "schema": "double"
  },

Im Rest dieses Abschnitts werden die Anmerkungserweiterung und andere DTDL v3-Funktionserweiterungen ausführlicher erläutert.

Anmerkungserweiterung

Die Anmerkungserweiterung wird verwendet, um benutzerdefinierte Metadaten zu einer Eigenschaft oder einem Telemetrieelement in einem DTDL v3-Modell hinzuzufügen. Sein Kontextspezifizierer ist dtmi:dtdl:extension:annotation;1.

Diese Erweiterung umfasst den ValueAnnotation adjunct-Typ, der einer DTDL-Eigenschaft oder einem Telemetrieelement hinzugefügt werden kann. Der ValueAnnotation Typ fügt dem Element ein Feld hinzu, annotateswodurch Sie eine andere Eigenschaft oder Telemetrie benennen können, die vom aktuellen Element mit Anmerkungen versehen ist.

Weitere Details und Beispiele für diese Erweiterung finden Sie unter Anmerkungserweiterung in der DTDL v3-Sprachbeschreibung.

Historisierungserweiterung

Die Historisierungserweiterung wird verwendet, um eine Eigenschaft oder Telemetrie in einem DTDL v3-Modell als etwas festzulegen, das historisiert werden soll (d. h. die verlaufsbezogene Sequenz ihrer Werte sollte zusammen mit zeiten, zu denen sich die Werte ändern) aufgezeichnet werden. Sein Kontextspezifizierer ist dtmi:dtdl:extension:historization;1.

Diese Erweiterung umfasst den Historized adjunct-Typ, der einer DTDL-Eigenschaft oder einem Telemetrieelement als Co-Typ hinzugefügt werden kann, um anzugeben, dass der Dienst die Verlaufswerte des Elements beibehalten und für Abfragen und Analysen verfügbar machen soll. Der Historized adjunct-Typ fügt dem Element keine Felder hinzu.

Weitere Details und Beispiele für diese Erweiterung finden Sie unter Historisierungserweiterung in der DTDL v3-Sprachbeschreibung.

Überschreiben der Erweiterung

Die überschreibende Erweiterung wird verwendet, um eine Eigenschaft in einem DTDL V3-Modell mit einem instance Wert zu überschreiben. Sie wird in Kombination mit der Anmerkungserweiterung verwendet, und ihr Kontextbezeichner ist dtmi:dtdl:extension:overriding;1.

Diese Erweiterung umfasst den Override adjunct-Typ, der einer DTDL-Eigenschaft hinzugefügt werden kann, die auch mit ValueAnnotation (aus der Anmerkungserweiterung) gemeinsam typisiert wird. Der Override Typ fügt dem -Element ein Feld hinzu, overrideswodurch Sie ein Feld für das mit Anmerkungen versehene Element benennen können, das mit dem Wert des aktuellen Elements überschrieben werden soll.

Weitere Details und Beispiele für diese Erweiterung finden Sie unter Überschreiben der Erweiterung in der DTDL v3-Sprachbeschreibung.

QuantitativeTypes-Erweiterung

Die QuantitativeTypes-Erweiterung wird verwendet, um semantische Typen, Einheitentypen und Einheiten in einem DTDL v3-Modell zu aktivieren. Sein Kontextspezifizierer ist dtmi:dtdl:extension:quantitativeTypes;1.

Diese Erweiterung ermöglicht die Verwendung vieler semantischer Typen als zusatzfähige Typen, die in DTDL v3 einem CommandRequest, einem Field, einem MapValue, einer Eigenschaft oder einer Telemetrie hinzugefügt werden können. Semantiktypen fügen dem Element ein Feld hinzu, unitdas eine gültige Einheit akzeptiert, die dem semantischen Typ entspricht.

Weitere Informationen zur Erweiterung, einschließlich Beispielen und einer vollständigen Liste unterstützter semantischer Typen und Einheiten, finden Sie unter QuantitativeTypes-Erweiterung in der DTDL v3-Sprachbeschreibung.

Dienstspezifische DTDL-Notizen

Nicht alle Dienste, die DTDL verwenden, implementieren genau die gleichen Features von DTDL. Es gibt einige DTDL-Funktionen, die Azure Digital Twins derzeit nicht unterstützt, darunter:

  • DTDL-Befehle
  • Das Attribut writable bei Eigenschaften oder Beziehungen. Obwohl dieses Attribut gemäß DTDL-Spezifikationen festgelegt werden kann, wird der Wert von Azure Digital Twins nicht verwendet. Stattdessen werden diese Attribute von externen Clients, die über allgemeine Schreibberechtigungen für den Azure Digital Twins-Dienst verfügen, immer als beschreibbar behandelt.
  • Die minMultiplicity und maxMultiplicity Eigenschaften von Beziehungen. Obwohl diese Attribute gemäß den DTDL-Spezifikationen festgelegt werden können, werden die Werte von Azure Digital Twins nicht erzwungen.

Damit ein DTDL-Modell mit Azure Digital Twins kompatibel ist, muss es auch diese Anforderungen erfüllen:

  • Alle DTDL-Elemente auf oberster Ebene in einem Modell müssen den Typ Interface haben. Der Grund für diese Anforderung ist, dass die APIs des Azure Digital Twins-Modells JSON-Objekte empfangen können, die entweder eine Schnittstelle oder ein Array von Schnittstellen darstellen. Infolgedessen sind auf der obersten Ebene keine anderen DTDL-Elementtypen zulässig.
  • DTDL für Azure Digital Twins darf keine Befehle definieren.
  • Azure Digital Twins erlaubt nur eine einzige Ebene der Komponentenschachtelung. Daher kann eine Schnittstelle, die als Komponente verwendet wird, selbst keine Komponenten enthalten.
  • Schnittstellen können nicht inline innerhalb anderer DTDL-Schnittstellen definiert werden, sondern müssen als separate Entitäten auf oberster Ebene mit eigenen IDs definiert werden. Wenn dann eine andere Schnittstelle diese Schnittstelle als Komponente oder durch Vererbung einbinden möchte, kann sie auf ihre ID verweisen.

Modellierungstools und bewährte Methoden

In diesem Abschnitt werden zusätzliche Überlegungen und Empfehlungen für die Modellierung beschrieben.

Verwenden vorhandener Branchenstandard-Ontologien

Eine Ontologie ist eine Reihe von Modellen, die eine bestimmte Domäne umfassend beschreiben, z. B. Fertigung, Gebäudestrukturen, IoT-Systeme, intelligente Städte, Energienetze, Webinhalte und mehr.

Wenn Ihre Lösung für eine bestimmte Branche bestimmt ist, die irgendeine Art von Modellierungsstandard verwendet, sollten Sie mit einem bereits vorhandenen Satz von Modellen beginnen, die für Ihre Branche entworfen wurden, anstatt Ihre Modelle von Grund auf neu zu entwerfen. Microsoft hat sich mit Domänenexperten zusammengetan, um DTDL-Modell-Ontologien basierend auf Branchenstandards zu erstellen, um die Neuerfindung zu minimieren und Konsistenz und Einfachheit in branchenübergreifenden Lösungen zu fördern. Weitere Informationen zu diesen Ontologien, einschließlich ihrer Verwendung und der verfügbaren Ontologien, finden Sie unter Was ist eine Ontologie?.

Überlegungen zu Abfrageauswirkungen

Wenn Sie beim Entwerfen von Modellen die Entitäten in Ihrer Umgebung wiedergeben möchten, kann es hilfreich sein, vorauszuschauen und die Implikationen zu betrachten, die Ihr Entwurf hinsichtlich Abfragen beinhaltet. Sie können Eigenschaften so entwerfen, dass Diagrammdurchläufe bei großen Resultsets vermieden werden. Sie können Beziehungen, die in einer einzelnen Abfrage beantwortet werden müssen, auch als einstufige Beziehungen modellieren.

Überprüfen von Modellen

Nachdem Sie ein Modell erstellt haben, sollten Sie Ihre Modelle offline validieren, bevor Sie sie in Ihre Azure Digital Twins-Instanz hochladen.

Um Ihre Modelle zu überprüfen, wird auf NuGet eine clientseitige DTDL-Analysebibliothek bereitgestellt: DTDLParser. Sie können die Parserbibliothek direkt in Ihrem C#-Code verwenden. Sie können auch die Beispielverwendung des Parsers im DTDLParserResolveSample in GitHub anzeigen.

Massenhochladen und -löschen von Modellen

Sobald Sie Ihre Modelle erstellt, erweitert oder ausgewählt haben, müssen Sie diese in Ihre Azure Digital Twins-Instanz hochladen, um sie zur Verwendung in Ihrer Lösung zur Verfügung zu stellen.

Sie können viele Modelle in einem einzelnen API-Aufruf hochladen, indem Sie die Auftrags-API verwenden. Die API kann gleichzeitig bis zum Azure Digital Twins-Grenzwert für die Anzahl von Modellen in einem instance akzeptieren und modelle bei Bedarf automatisch neu anordnen, um Abhängigkeiten zwischen ihnen aufzulösen. Ausführliche Anweisungen und Beispiele, die diese API verwenden, finden Sie unter Anweisungen zum Massenimport für Modelle.

Eine Alternative zur Auftrags-API ist das Modelluploaderbeispiel, das die einzelnen Modell-APIs verwendet, um mehrere Modelldateien gleichzeitig hochzuladen. Das Beispiel implementiert auch die automatische Neuanordnung, um Modellabhängigkeiten aufzulösen. Es funktioniert derzeit nur mit Version 2 von DTDL.

Wenn Sie alle Modelle in einer Azure Digital Twins-instance gleichzeitig löschen müssen, können Sie das Modelllöscherbeispiel verwenden. Dies ist ein Projekt, das rekursive Logik enthält, um Modellabhängigkeiten über den Löschvorgang zu behandeln. Es funktioniert derzeit nur mit Version 2 von DTDL.

Visualisieren von Modellen

Nachdem Sie Modelle auf Ihre Azure Digital Twins-Instanz hochgeladen haben, können Sie sie im Azure Digital Twins-Explorer anzeigen. Der Explorer enthält eine Liste aller Modelle in der Instanz sowie ein Modelldiagramm, das die Beziehungen der Modelle untereinander veranschaulicht, einschließlich Vererbungs- und Modellbeziehungen.

Hinweis

Derzeit unterstützt Azure Digital Twins Explorer DTDL v2-Modelle vollständig und unterstützt eingeschränkte Funktionen für DTDL v3-Modelle, einschließlich des Anzeigens von DTDL v3-Modellen im Bereich Modelle und anzeigen/bearbeiten von Zwillingen, die mit DTDL v3-Modellen erstellt wurden (einschließlich solcher mit Arrayeigenschaften). DTDL v3-Modelle werden jedoch nicht im Bereich Modelldiagramm angezeigt, und sie können nicht mit Azure Digital Twins Explorer importiert werden. Um DTDL v3-Modelle in Ihre instance zu importieren, verwenden Sie eine andere Entwicklerschnittstelle wie die APIs und SDKs oder die Azure CLI.

Hier ein Beispiel für ein Modelldiagramm:

Screenshot: Azure Digital Twins-Explorer. Der Bereich mit dem Modelldiagramm ist hervorgehoben.

Weitere Informationen zur Modelloberfläche im Azure Digital Twins-Explorer finden Sie unter Untersuchen von Modellen und des Modelldiagramms.

Nächste Schritte