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 (z. B. Raum- oder Temperatursensor) und enthalten Elemente wie Eigenschaften, Komponenten und Beziehungen, die beschreiben, was diese Art von Entität in Ihrer Umgebung tut. 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 in GitHub anzeigen: DTDL Version 3 Sprachbeschreibung. Diese Seite enthält DTDL-Referenzdetails und Beispiele, die Ihnen bei den ersten Schritten beim Schreiben Eigener 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 die DTDL-Versionen 2 und 3 (gekürzt in der Dokumentation auf v2 bzw. v3). V3 ist die empfohlene Wahl für die Modellierung in Azure Digital Twins basierend auf seinen erweiterten Funktionen, darunter:

Wenn diese Features in der Dokumentation erläutert werden, werden sie von einer Notiz 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 Instanz. Beachten Sie bei der gemeinsamen Verwendung 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 zeigen, von einer v2-Modellquelle auf ein 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.

Hinweis

Derzeit unterstützt Azure Digital Twins Explorer dtDL v2-Modelle vollständig und unterstützt eingeschränkte Funktionen für DTDL v3-Modelle. In Azure Digital Twins Explorer können DTDL v3-Modelle im Bereich "Modelle" angezeigt werden, und Zwillinge, die mit DTDL v3-Modellen erstellt wurden, können angezeigt und bearbeitet werden (einschließlich der Modelle 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 Instanz zu importieren, verwenden Sie eine andere Entwicklerschnittstelle wie die APIs und SDKs oder die Azure CLI.

Ü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 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 ein @type (, oder Component) bereitstellen, Relationshipum die Art der beschreibten Schnittstelleninformationen zu identifizieren, und dann eine Reihe von Eigenschaften, die dasProperty tatsächliche 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"
    }
  ]
}

Modell-Attribute

Die wichtigsten Informationen zu einem Modell werden durch ihre Attribute angegeben, die im Abschnitt contents der Modellschnittstelle definiert sind.

Hier sind die in DTDL verfügbaren Attribute, die in Azure Digital Twins unterstützt werden. Eine DTDL-Modellschnittstelle, die für Azure Digital Twins verwendet wird, kann null, eins oder viele 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 unter "Eigenschaften " weiter unten.

  • 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 Front Kamera schnittstelle (und eine andere Komponentenschnittstelle zurück Kamera), die beim 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.

Die DTDL v3-Sprachbeschreibung definiert auch Befehle und Telemetrie, aber keine dieser Befehle werden in Azure Digital Twins verwendet. Befehle werden nicht unterstützt, und Telemetrie – obwohl es in Modelldefinitionen zulässig ist – verfügt über keinen eindeutigen Anwendungsfall in azure Digital Twins-Modellierung. Statt DTDL-Telemetrie zu verwenden, sollten Sie DTDL-Eigenschaften zum Speichern von Twin State-Informationen verwenden.

Hinweis

Obwohl es nicht erforderlich ist, Telemetriefelder in Ihren DTDL-Modellen zum Speichern eingehender Gerätedaten zu definieren, können Azure Digital Twins Ereignisse als Telemetrie mithilfe der SendTelemetry-API ausgeben. Dadurch wird ein Digital Twin Telemetry Message-Ereignis ausgelöst, das von einem Ereignishandler empfangen werden kann, um Aktionen für andere Zwillinge auszuführen oder nachgeschaltete Dienste auszulösen.

Eigenschaften

Dieser Abschnitt enthält ausführlichere Informationen zu Eigenschaften in DTDL-Modellen.

Umfassende Informationen zu den Feldern, die als Teil einer Eigenschaft angezeigt werden können, finden Sie unter "Eigenschaft" 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.

Schema

Gemäß DTDL kann das Schema für Eigenschaftsattribute ein Standardgrundtyp (integer, , double, stringund booleanandere Typen wie dateTime und duration) sein.

Zusätzlich zu primitiven Typen können Eigenschaftsfelder diese komplexen Typen aufweisen:

  • Object
  • Map
  • Enum
  • Array, nur in DTDL v3. Array Der Typ für Eigenschaften wird in DTDL v2 nicht 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 in eine Featureerweiterung einschließen.

Basic-Eigenschaft (Beispiel)

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

Beispiel für komplexen Objekttyp

Eigenschaften können komplexe Typen sein, einschließlich eines Object Typs.

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

DTDL v2-Semantiktyp (Beispiel)

Semantische Typen dienen zum Ausdrücken eines Werts mit einer Einheit. Eigenschaften für Azure Digital Twins können alle 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. Informationen zu semantischen Typen in DTDL v3 finden Sie in der Featureerweiterung QuantitativeTypes DTDL v3.

Das folgende Beispiel zeigt ein DTDL v2 Sensormodell mit semantischen Typeigenschaften für Feuchtigkeit und Temperatur.

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

Wichtig

"Property" 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 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 Component in the DTDL v3 Language Description.

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 jeweils extends mindestens zwei Schnittstellen aufgeführt sein. In DTDL v3 gibt es keine Beschränkung für die Anzahl der unmittelbaren Werte für ein extends.

In DTDL v2 und v3 beträgt der Gesamttiefegrenzwert 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-Featureerweiterungen

DTDL v3 ermöglicht Spracherweiterungen, die zusätzliche Metamodellklassen definieren, mit denen Sie umfangreichere Modelle schreiben können. In diesem Abschnitt werden die Featureerweiterungsklassen beschrieben, die Sie verwenden können, um Ihren DTDL v3-Modellen Nichtkernfeatures hinzuzufügen.

Jede Featureerweiterung wird durch ihren Kontextbezeichner 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 zum Feld des @context Modells hinzu (zusammen mit dem allgemeinen DTDL-Kontextbezeichner von dtmi:dtdl:context;3). Sie können demselben Modell mehrere Featureerweiterungen hinzufügen.

Nachfolgend finden Sie ein Beispiel dafür, wie dieses @context Feld mit Featureerweiterungen aussehen kann. Der folgende Auszug stammt aus einem Modell, das sowohl die Erweiterung QuantitativeTypes als auch die Annotation-Erweiterung 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 Adjunct-Typen dieser Erweiterung innerhalb des Modells. Sie können dem Feld eines DTDL-Elements Adjunct-Typen @type hinzufügen, um dem Element zusätzliche Funktionen zu bieten. Der Adjuncttyp kann dem Element zusätzliche Eigenschaften hinzufügen.

Hier ist beispielsweise ein Auszug aus einem Modell, das die Anmerkungserweiterung verwendet. Diese Erweiterung hat einen adjunct-Typ namens ValueAnnotation, der im folgenden Beispiel zu einem Eigenschaftselement hinzugefügt wird. Durch Hinzufügen dieses Adjuncttyps zum Eigenschaftselement kann das Element über ein zusätzliches annotates Feld verfügen, das verwendet wird, um eine andere Eigenschaft anzugeben, die von diesem Element kommentiert wird.

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

Im restlichen Abschnitt werden die Annotation-Erweiterung und andere DTDL v3-Featureerweiterungen ausführlicher erläutert.

Anmerkungserweiterung

Die Annotation-Erweiterung wird verwendet, um einem Eigenschaftselement in einem DTDL v3-Modell benutzerdefinierte Metadaten hinzuzufügen. Der Kontextbezeichner ist dtmi:dtdl:extension:annotation;1.

Diese Erweiterung enthält den ValueAnnotation Adjunct-Typ, der einem DTDL-Eigenschaftselement hinzugefügt werden kann. Der ValueAnnotation Typ fügt dem Element ein Feld hinzu, mit dem Sie eine andere Eigenschaft benennen können, annotatesdie vom aktuellen Element kommentiert wird.

Weitere Details und Beispiele für diese Erweiterung finden Sie in der DTDL v3 Language Description.For more details and examples of this extension, see Annotation extension in the DTDL v3 Language Description.

Historisierungserweiterung

Die Historisierungserweiterung wird verwendet, um eine Eigenschaft in einem DTDL v3-Modell als etwas zu kennzeichnen, das historisiert werden soll (d. h. die historische Abfolge seiner Werte sollte zusammen mit Zeiten aufgezeichnet werden, in denen sich die Werte ändern). Der Kontextbezeichner ist dtmi:dtdl:extension:historization;1.

Diese Erweiterung enthält den Historized Adjunct-Typ, der einem DTDL-Eigenschaftselement als Co-Typ hinzugefügt werden kann, um anzugeben, dass der Dienst die historischen Werte 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 Historization-Erweiterung in der DTDL v3 Language Description.

Außerkraftsetzungserweiterung

Die Außerkraftsetzungserweiterung wird verwendet, um eine Eigenschaft in einem DTDL V3-Modell mit einem Instanzwert außer Kraft zu setzen. Es wird in Kombination mit der Anmerkungserweiterung verwendet, und der Kontextbezeichner ist dtmi:dtdl:extension:overriding;1.

Diese Erweiterung enthält den Override Adjunct-Typ, der einer DTDL-Eigenschaft hinzugefügt werden kann, die auch mit ValueAnnotation (aus der Anmerkungserweiterung) gemeinsam eingegeben wird. Der Override Typ fügt dem Element ein Feld hinzu, overridesmit dem Sie ein Feld für das kommentierte Element benennen können, das durch den Wert des aktuellen Elements überschrieben werden soll.

Weitere Details und Beispiele für diese Erweiterung finden Sie unter Überschreibungserweiterung in der DTDL v3 Language Description.

QuantitativeTypes-Erweiterung

Die QuantitativeTypes-Erweiterung wird verwendet, um semantische Typen, Einheitentypen und Einheiten in einem DTDL v3-Modell zu ermöglichen. Der Kontextbezeichner ist dtmi:dtdl:extension:quantitativeTypes;1.

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

Weitere Informationen zur Erweiterung, einschließlich Beispiele und einer vollständigen Liste der unterstützten semantischen Typen und Einheiten, finden Sie unter QuantitativeTypes-Erweiterung in der DTDL v3 Language Description.

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 Do umfassend beschreiben Standard wie Fertigung, Gebäudestrukturen, IoT-Systeme, Smart Cities, Energienetze, Webinhalte und vieles mehr.

Wenn Ihre Lösung für eine bestimmte Branche geeignet ist, die irgendeine Art von Modellierungsstandard verwendet, sollten Sie mit einem bereits vorhandenen Satz von Modellen beginnen, die für Ihre Branche entwickelt wurden, anstatt Ihre Modelle von Grund auf neu zu entwerfen. Microsoft hat sich mit do Standard Experten zusammengetan, um DTDL-Modell-Ontologien basierend auf Branchenstandards zu erstellen, um die Neufindung 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 eine clientseitige DTDL-Analysebibliothek für .NET auf NuGet: DTDLParser bereitgestellt. 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 mithilfe der Importaufträge-API hochladen. Die API kann gleichzeitig bis zum Azure Digital Twins-Grenzwert für die Anzahl von Modellen in einer Instanz 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 Massenimportanweisungen für Modelle.

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

Wenn Sie alle Modelle in einer Azure Digital Twins-Instanz gleichzeitig löschen müssen, können Sie das Model Deleter-Beispiel verwenden. Dies ist ein Projekt, das rekursive Logik zum Behandeln von Modellabhängigkeiten über den Löschvorgang enthält. Es funktioniert derzeit nur mit Version 2 von DTDL.

Oder wenn Sie die Daten in einer Instanz löschen möchten, indem Sie alle Modelle zusammen mit allen Zwillingen und Beziehungen löschen, können Sie die Delete Jobs-API verwenden.

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. In Azure Digital Twins Explorer können DTDL v3-Modelle im Bereich "Modelle" angezeigt werden, und Zwillinge, die mit DTDL v3-Modellen erstellt wurden, können angezeigt und bearbeitet werden (einschließlich der Modelle 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 Instanz zu importieren, verwenden Sie eine andere Entwicklerschnittstelle wie die APIs und SDKs oder die Azure CLI.

Hier ein Beispiel für ein Modelldiagramm:

Screenshot of Azure Digital Twins Explorer. The Model Graph panel is highlighted.

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

Nächste Schritte