Lär dig mer om tvillingmodeller och hur du definierar dem i Azure Digital Twins

Artikel
01/04/2024

En viktig egenskap hos Azure Digital Twins är möjligheten att definiera din egen vokabulär och skapa din tvillinggraf i de självdefinierade villkoren för din verksamhet. Den här funktionen tillhandahålls via användardefinierade modeller. Du kan se modeller som substantiv i en beskrivning av din värld. Azure Digital Twins-modeller representeras i JSON-LD-baserade DTDL (Digital Twin Definition Language).

En modell liknar en klass i ett objektorienterat programmeringsspråk och definierar en dataform för ett visst begrepp i din verkliga arbetsmiljö. Modeller har namn (till exempel Rum eller TemperatureSensor) och innehåller element som egenskaper, komponenter och relationer som beskriver vad den här typen av entitet i din miljö gör. Senare använder du dessa modeller för att skapa digitala tvillingar som representerar specifika entiteter som uppfyller den här typen av beskrivning.

DTDL (Digital Twin Definition Language) för modeller

Modeller för Azure Digital Twins definieras med DTDL (Digital Twins Definition Language).

Du kan visa den fullständiga språkbeskrivningen för DTDL v3 i GitHub: Språkbeskrivning för DTDL version 3. Den här sidan innehåller DTDL-referensinformation och exempel som hjälper dig att komma igång med att skriva egna DTDL-modeller.

DTDL är baserat på JSON-LD och är programmeringsspråksoberoende. DTDL är inte exklusivt för Azure Digital Twins. Det används också för att representera enhetsdata i andra IoT-tjänster, till exempel IoT Plug and Play.

Resten av den här artikeln sammanfattar hur språket används i Azure Digital Twins.

DTDL-versioner som stöds

Azure Digital Twins stöder DTDL-versionerna 2 och 3 (förkortas i dokumentationen till v2 respektive v3). V3 är det rekommenderade valet för modellering i Azure Digital Twins baserat på dess utökade funktioner, inklusive:

DTMI-versionsavslappning
Matrisstöd för egenskaper
Ökade gränser för modellarv
Funktionstillägg
- Möjligheten att dekorera anpassade gränssnittsscheman med semantiska typer (tillhandahålls med Tillägget QuantitativeTypes)

När dessa funktioner beskrivs i dokumentationen åtföljs de av en anteckning om att de endast är tillgängliga i DTDL v3. En fullständig lista över skillnader mellan DTDL v2 och v3 finns i Språkbeskrivning för DTDL v3: Ändringar från version 2.

Azure Digital Twins stöder också användning av en blandning av v2- och v3-modeller i samma instans. Tänk på följande begränsningar när du använder modeller av båda versionerna tillsammans:

Ett v2-gränssnitt kan inte utöka ett v3-gränssnitt eller ha en komponent med ett v3-gränssnitt som schema.
Omvänt kan ett v3-gränssnitt utöka ett v2-gränssnitt, och ett v3-gränssnitt kan ha en komponent med ett v2-gränssnitt som schema.
Relationer kan peka i endera riktningen, från en v2-modellkälla till ett v3-modellmål eller vice versa från en v3-modellkälla till ett v2-modellmål.

Du kan också migrera befintliga v2-modeller till v3. Anvisningar om hur du gör detta finns i Konvertera v2-modeller till v3.

Kommentar

För närvarande har Azure Digital Twins Explorer fullt stöd för DTDL v2-modeller och har stöd för begränsade funktioner för DTDL v3-modeller. I Azure Digital Twins Explorer kan DTDL v3-modeller visas i panelen Modeller och tvillingar som skapats med DTDL v3-modeller kan visas och redigeras (inklusive de med matrisegenskaper). DTDL v3-modeller visas dock inte i panelen Modelldiagram och de kan inte importeras med Azure Digital Twins Explorer. Om du vill importera DTDL v3-modeller till din instans använder du ett annat utvecklargränssnitt som API:er och SDK:er eller Azure CLI.

Översikt över modell

Modeller av tvillingtyp kan skrivas i valfri textredigerare. DTDL-språket följer JSON-syntaxen, så du bör lagra modeller med tillägget .json. Med hjälp av JSON-tillägget kan många programmeringstextredigerare tillhandahålla grundläggande syntaxkontroll och markering för dina DTDL-dokument. Det finns också ett DTDL-tillägg tillgängligt för Visual Studio Code.

Här är fälten i ett modellgränssnitt:

Fält	beskrivning
`@id`	En DTMI (Digital Twin Model Identifier) för modellen i formatet `dtmi:<domain>:<unique-model-identifier>;<model-version-number>`. I DTDL v3 kan versionsnumret utelämnas eller struktureras som ett versionsnummer i två delar (`<major>.<minor>`).
`@type`	Identifierar den typ av information som beskrivs. För ett gränssnitt är `Interface`typen .
`@context`	Anger kontexten för JSON-dokumentet. Modeller bör användas `dtmi:dtdl:context;2` för DTDL v2 eller `dtmi:dtdl:context;3` för DTDL v3. DTDL v3-modeller kan också namnge ytterligare funktionstillägg i det här fältet.
`displayName`	[valfritt] Ger dig möjlighet att definiera ett eget namn för modellen. Om du inte använder det här fältet använder modellen sitt fullständiga DTMI-värde.
`contents`	Alla återstående gränssnittsdata placeras här som en matris med attributdefinitioner. Varje attribut måste ange en `@type` (`Property`, `Relationship`, eller `Component`) för att identifiera vilken typ av gränssnittsinformation som beskrivs och sedan en uppsättning egenskaper som definierar det faktiska attributet. I nästa avsnitt beskrivs modellattributen i detalj.

Här är ett exempel på en grundläggande DTDL-modell. Den här modellen beskriver en Start med en egenskap för ett ID. Hemmodellen definierar också en relation till en golvmodell, som kan användas för att indikera att en hemtvilling är ansluten till vissa Floor-tvillingar.

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

Modellattribut

Huvudinformationen om en modell ges av dess attribut, som definieras i contents avsnittet i modellgränssnittet.

Här är de attribut som är tillgängliga i DTDL som stöds i Azure Digital Twins. Ett DTDL-modellgränssnitt som används för Azure Digital Twins kan innehålla noll, ett eller flera av följande fält:

Egenskap – Egenskaper är datafält som representerar tillståndet för en entitet (som egenskaperna i många objektorienterade programmeringsspråk). Egenskaper har säkerhetskopieringslagring och kan läsas när som helst. Mer information finns i Egenskaper nedan.
Relation – Med relationer kan du representera hur en digital tvilling kan ingå i andra digitala tvillingar. Relationer kan representera olika semantiska betydelser, till exempel contains ("golvet innehåller rum"), cools ("hvac kyler rummet"), isBilledTo ("kompressor faktureras till användaren" och så vidare. Med relationer kan lösningen tillhandahålla ett diagram över relaterade entiteter. Relationer kan också ha egna egenskaper. Mer information finns i Relationer nedan.
Komponent – Med komponenter kan du skapa modellgränssnittet som en sammansättning av andra gränssnitt, om du vill. Ett exempel på en komponent är ett front Kamera-gränssnitt (och ett annat komponentgränssnitt Kamera) som används för att definiera en modell för en telefon. Definiera först ett gränssnitt för front Kamera som om det vore en egen modell och referera sedan till det när du definierar Telefon.

Använd en komponent för att beskriva något som är en integrerad del av din lösning, men som inte behöver en separat identitet, och som inte behöver skapas, tas bort eller ordnas om i tvillingdiagrammet oberoende av varandra. Om du vill att entiteter ska ha oberoende existenser i tvillingdiagrammet representerar du dem som separata digitala tvillingar av olika modeller, anslutna via relationer.

Dricks

Komponenter kan också användas för organisation för att gruppera uppsättningar med relaterade egenskaper i ett modellgränssnitt. I den här situationen kan du se varje komponent som ett namnområde eller en "mapp" i gränssnittet.

Mer information finns i Komponenter nedan.

Språkbeskrivningen för DTDL v3 definierar även kommandon och telemetri, men ingen av dessa används i Azure Digital Twins. Kommandon stöds inte, och Telemetri – även om det är tillåtet i modelldefinitioner – har inget unikt användningsfall i Azure Digital Twins-modellering. I stället för att använda DTDL-telemetri bör du använda DTDL-egenskaper för att lagra information om tvillingtillstånd.

Kommentar

Även om du inte behöver definiera telemetrifält i dina DTDL-modeller för att lagra inkommande enhetsdata, kan Azure Digital Twins generera händelser som telemetri med hjälp av SendTelemetry-API:et. Detta utlöser en digital tvilling-telemetrimeddelandehändelse som kan tas emot av en händelsehanterare för att vidta åtgärder på andra tvillingar eller utlösa underordnade tjänster.

Egenskaper

Det här avsnittet går in mer detaljerat om egenskaper i DTDL-modeller.

Omfattande information om fälten som kan visas som en del av en egenskap finns i Egenskap i språkbeskrivningen för DTDL v3.

Kommentar

writable DTDL-attributet för egenskaper stöds för närvarande inte i Azure Digital Twins. Den kan läggas till i modellen, men Azure Digital Twins tillämpar den inte. Mer information finns i Tjänstspecifika DTDL-anteckningar.

Schema

Enligt DTDL kan schemat för egenskapsattribut vara en primitiv standardtyp –integer , double, stringoch – och booleanandra typer som dateTime och duration.

Förutom primitiva typer kan egenskapsfält ha följande komplexa typer:

Object
Map
Enum
Array, endast i DTDL v3. Array typ för egenskaper stöds inte i DTDL v2.

De kan också vara semantiska typer, vilket gör att du kan kommentera värden med enheter. I DTDL v2 stöds semantiska typer internt. I DTDL v3 kan du inkludera dem med ett funktionstillägg.

Exempel på grundläggande egenskap

Här är ett grundläggande exempel på en egenskap i en DTDL-modell. Det här exemplet visar ID-egenskapen för en startsida.

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

Exempel på komplex objekttyp

Egenskaper kan vara av komplexa typer, inklusive en Object typ.

I följande exempel visas en annan version av hemmodellen med en egenskap för dess adress. address är ett objekt med egna fält för gata, stad, delstat och zip.

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

Exempel på DTDL v2-semantisk typ

Semantiska typer är till för att uttrycka ett värde med en enhet. Egenskaper för Azure Digital Twins kan använda någon av de semantiska typer som stöds av DTDL.

I DTDL v2 stöds semantiska typer internt. Mer information om semantiska typer i DTDL v2 finns i Semantiska typer i språkbeskrivningen för DTDL v2. Mer information om semantiska typer i DTDL v3 finns i funktionstillägget QuantitativeTypes DTDL v3.

I följande exempel visas en DTDL v2 Sensor-modell med semantiska typegenskaper för luftfuktighet och 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" 
    }
  ]
}

Viktigt!

Egenskapen måste vara det första elementet i matrisen @type följt av den semantiska typen. Annars kanske fältet inte visas i Azure Digital Twins Explorer.

Relationer

Det här avsnittet går in mer detaljerat om relationer i DTDL-modeller.

En omfattande lista över fält som kan visas som en del av en relation finns i Relation i språkbeskrivningen för DTDL v3.

Kommentar

Attributen writable, minMultiplicityoch maxMultiplicity DTDL för relationer stöds för närvarande inte i Azure Digital Twins. De kan läggas till i modellen, men Azure Digital Twins tillämpar dem inte. Mer information finns i Tjänstspecifika DTDL-anteckningar.

Exempel på grundläggande relation

Här är ett grundläggande exempel på en relation på en DTDL-modell. Det här exemplet visar en relation på en startmodell som gör att den kan ansluta till en golvmodell.

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

Kommentar

För relationer @id är ett valfritt fält. Om inget @id anges tilldelar den digitala tvillinggränssnittsprocessorn en.

Riktade och icke-riktade relationer

Relationer kan definieras med eller utan mål. Ett mål anger vilka typer av tvilling som relationen kan nå. Du kan till exempel inkludera ett mål för att ange att en startmodell bara kan ha en rel_has_floors relation med tvillingar som är floor twins.

Ibland kanske du vill definiera en relation utan ett specifikt mål, så att relationen kan ansluta till många olika typer av tvillingar.

Här är ett exempel på en relation på en DTDL-modell som inte har något mål. I det här exemplet är relationen till för att definiera vilka sensorer ett rum kan ha och relationen kan ansluta till valfri typ.

{
  "@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"

Egenskaper för relationer

DTDL gör det också möjligt för relationer att ha egna egenskaper. När du definierar en relation i en DTDL-modell kan relationen ha ett eget properties fält där du kan definiera anpassade egenskaper för att beskriva relationsspecifikt tillstånd.

I följande exempel visas en annan version av hemmodellen, där rel_has_floors relationen har en egenskap som representerar när den relaterade golvet senast användes.

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

Komponenter

Det här avsnittet innehåller mer information om komponenter i DTDL-modeller.

En omfattande lista över de fält som kan visas som en del av en komponent finns i Komponent i språkbeskrivningen för DTDL v3.

Exempel på grundläggande komponent

Här är ett grundläggande exempel på en komponent i en DTDL-modell. Det här exemplet visar en rumsmodell som använder en termostatmodell som komponent.

[
  {
    "@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"
      }
    ]
  }
]

Om andra modeller i den här lösningen också ska innehålla en termostat kan de referera till samma termostatmodell som en komponent i sina egna definitioner, precis som Room gör.

Viktigt!

Komponentgränssnittet (termostat i exemplet ovan) måste definieras i samma matris som alla gränssnitt som använder det (rum i exemplet ovan) för att komponentreferensen ska hittas.

Modellarv

Ibland kanske du vill specialisera en modell ytterligare. Det kan till exempel vara användbart att ha ett allmänt modellrum och specialiserade varianter ConferenceRoom och Gym. DTDL stöder arv för att uttrycka specialisering. Gränssnitt kan ärva från ett eller flera andra gränssnitt. Du kan göra det genom att lägga till ett extends fält i modellen.

Avsnittet extends är ett gränssnittsnamn eller en matris med gränssnittsnamn (vilket gör att det utökade gränssnittet kan ärva från flera överordnade modeller). En överordnad kan fungera som basmodell för flera utökade gränssnitt.

Kommentar

I DTDL v2 kan var och en extends ha högst två gränssnitt listade för den. I DTDL v3 finns det ingen gräns för antalet omedelbara värden för en extends.

I både DTDL v2 och v3 är den totala djupgränsen för en extends hierarki 10.

I följande exempel föreställer du dig startmodellen från det tidigare DTDL-exemplet som en undertyp av en större "core"-modell. Den överordnade modellen (Core) definieras först och sedan bygger den underordnade modellen (Start) på den med hjälp extendsav .

{
    "@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": [
    {

I det här fallet bidrar Core med ett ID och ett namn till Start. Andra modeller kan också utöka Core-modellen för att hämta dessa egenskaper också. Här är en Room-modell som utökar samma överordnade gränssnitt:

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

När arv har tillämpats exponerar utökande gränssnitt alla egenskaper från hela arvskedjan.

Det utökade gränssnittet kan inte ändra någon av definitionerna för de överordnade gränssnitten. det kan bara lägga till dem. Det kan inte heller omdefiniera en funktion som redan har definierats i något av dess överordnade gränssnitt (även om funktionerna har definierats som samma). Om ett överordnat gränssnitt till exempel definierar en double egenskap masskan det utökade gränssnittet inte innehålla en deklaration av mass, även om det också är en double.

DTDL v3-funktionstillägg

DTDL v3 möjliggör språktillägg som definierar ytterligare metamodelklasser, som du kan använda för att skriva mer avancerade modeller. I det här avsnittet beskrivs de funktionstilläggsklasser som du kan använda för att lägga till icke-kärnfunktioner i dina DTDL v3-modeller.

Varje funktionstillägg identifieras av dess kontextspecificerare, vilket är ett unikt DTMI-värde (Digital Twin Model Identifier). Om du vill aktivera ett funktionstillägg i en modell lägger du till tilläggets kontextspecificerare i modellens @context fält (tillsammans med den allmänna DTDL-kontextspecificeraren dtmi:dtdl:context;3för ). Du kan lägga till flera funktionstillägg i samma modell.

Här är ett exempel på hur det @context fältet kan se ut med funktionstillägg. Följande utdrag är från en modell som använder både QuantitativeTypes-tillägget och anteckningstillägget.

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

När du har lagt till ett funktionstillägg i en modell har du åtkomst till tilläggets adjungerade typer i modellen. Du kan lägga till tilläggstyper i @type fältet för ett DTDL-element för att ge elementet ytterligare funktioner. Tilläggstypen kan lägga till ytterligare egenskaper i elementet.

Här är till exempel ett utdrag från en modell som använder anteckningstillägget. Det här tillägget har en adjungerad typ med namnet ValueAnnotation, som läggs till i exemplet nedan i ett egenskapselement. Om du lägger till den här adjungerade typen i egenskapselementet kan elementet ha ytterligare ett annotates fält som används för att ange en annan egenskap som kommenteras av det här elementet.

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

I resten av det här avsnittet beskrivs anteckningstillägget och andra DTDL v3-funktionstillägg i detalj.

Tillägg för anteckning

Anteckningstillägget används för att lägga till anpassade metadata till ett egenskapselement i en DTDL v3-modell. Dess kontextspecificerare är dtmi:dtdl:extension:annotation;1.

Det här tillägget innehåller ValueAnnotation den adjungerade typen som kan läggas till i ett DTDL-egenskapselement. Typen ValueAnnotation lägger till ett fält i elementet , annotatessom gör att du kan namnge en annan egenskap som kommenteras av det aktuella elementet.

Mer information och exempel på det här tillägget finns i Annotation extension in the DTDL v3 Language Description (Anteckningstillägg i språkbeskrivningen för DTDL v3).

Historiseringstillägg

Historiseringstillägget används för att ange en egenskap i en DTDL v3-modell som något som ska historiseras (vilket innebär att den historiska sekvensen av dess värden ska registreras, tillsammans med tidpunkter då värdena ändras). Dess kontextspecificerare är dtmi:dtdl:extension:historization;1.

Det här tillägget innehåller den Historized adjungerade typen, som kan läggas till som en samtyp i ett DTDL-egenskapselement för att indikera att tjänsten ska bevara elementets historiska värden och göra dem tillgängliga för frågor och analys. Den Historized adjungerade typen lägger inte till några fält i elementet.

Mer information och exempel på det här tillägget finns i Historization-tillägget i språkbeskrivningen för DTDL v3.

Åsidosättande tillägg

Det övergripande tillägget används för att åsidosätta en egenskap i en DTDL V3-modell med ett instansvärde. Den används i kombination med anteckningstillägget och dess kontextspecificerare är dtmi:dtdl:extension:overriding;1.

Det här tillägget innehåller Override den adjungerade typen, som kan läggas till i en DTDL-egenskap som också är samskriven med ValueAnnotation (från anteckningstillägget). Typen Override lägger till ett fält i elementet , overridessom gör att du kan namnge ett fält på det kommenterade elementet som ska åsidosättas av det aktuella elementets värde.

Mer information och exempel på det här tillägget finns i Åsidosättande tillägg i språkbeskrivningen DTDL v3.

QuantitativeTypes-tillägg

Tillägget QuantitativeTypes används för att aktivera semantiska typer, enhetstyper och enheter i en DTDL v3-modell. Dess kontextspecificerare är dtmi:dtdl:extension:quantitativeTypes;1.

Det här tillägget möjliggör användning av många semantiska typer som adjungerade typer, som kan läggas till i en CommandRequest, ett fält, en MapValue eller en egenskap i DTDL v3. Semantiska typer lägger till ett fält i elementet , unitsom accepterar en giltig enhet som motsvarar den semantiska typen.

Mer information om tillägget, inklusive exempel och en fullständig lista över semantiska typer och enheter som stöds, finns i QuantitativeTypes-tillägget i språkbeskrivningen för DTDL v3.

Tjänstspecifika DTDL-anteckningar

Alla tjänster som använder DTDL implementerar inte exakt samma funktioner i DTDL. Det finns vissa DTDL-funktioner som Azure Digital Twins för närvarande inte stöder, inklusive:

DTDL-kommandon
Attributet writable för egenskaper eller relationer. Även om det här attributet kan anges enligt DTDL-specifikationer används inte värdet av Azure Digital Twins. I stället behandlas dessa attribut alltid som skrivbara av externa klienter som har allmänna skrivbehörigheter till Azure Digital Twins-tjänsten.
Egenskaperna minMultiplicity och maxMultiplicity för relationer. Även om dessa attribut kan anges enligt DTDL-specifikationer tillämpas inte värdena av Azure Digital Twins.

För att en DTDL-modell ska vara kompatibel med Azure Digital Twins måste den också uppfylla följande krav:

Alla DTDL-element på den översta nivån i en modell måste vara av typen Interface. Orsaken till det här kravet är att Azure Digital Twins-modell-API:er kan ta emot JSON-objekt som representerar antingen ett gränssnitt eller en matris med gränssnitt. Därför tillåts inga andra DTDL-elementtyper på den översta nivån.
DTDL för Azure Digital Twins får inte definiera några kommandon.
Azure Digital Twins tillåter endast en enda nivå av komponentkapsling, vilket innebär att ett gränssnitt som används som komponent inte kan ha några komponenter.
Gränssnitt kan inte definieras infogade i andra DTDL-gränssnitt. de måste definieras som separata entiteter på den översta nivån med sina egna ID:n. När ett annat gränssnitt sedan vill inkludera gränssnittet som en komponent eller genom arv kan det referera till sitt ID.

Modelleringsverktyg och metodtips

I det här avsnittet beskrivs ytterligare överväganden och rekommendationer för modellering.

Använda befintliga ontologier av branschstandard

En ontologi är en uppsättning modeller som på ett omfattande sätt beskriver en viss domän, till exempel tillverkning, byggnadsstrukturer, IoT-system, smarta städer, energinät, webbinnehåll med mera.

Om din lösning är för en viss bransch som använder någon form av modelleringsstandard kan du börja med en befintlig uppsättning modeller som är utformade för din bransch i stället för att designa dina modeller från grunden. Microsoft har samarbetat med domänexperter för att skapa DTDL-modell ontologier baserade på branschstandarder, för att minimera förnyelse och uppmuntra konsekvens och enkelhet i branschlösningar. Du kan läsa mer om dessa ontologier, inklusive hur du använder dem och vilka ontologier som är tillgängliga nu, i Vad är en ontologi?.

Överväg frågekonsekvenser

När du utformar modeller för att återspegla entiteterna i din miljö kan det vara användbart att titta framåt och fundera över frågekonsekvenserna av din design. Du kanske vill utforma egenskaper på ett sätt som undviker stora resultatuppsättningar från grafbläddering. Du kanske också vill modellera relationer som måste besvaras i en enda fråga som relationer på en nivå.

Verifiera modeller

När du har skapat en modell rekommenderar vi att du verifierar dina modeller offline innan du laddar upp dem till din Azure Digital Twins-instans.

För att hjälpa dig att verifiera dina modeller finns ett DTDL-parsningsbibliotek på .NET-klientsidan på NuGet: DTDLParser. Du kan använda parsningsbiblioteket direkt i C#-koden. Du kan också visa exempelanvändningen av parsern i DTDLParserResolveSample i GitHub.

Massuppladdning och borttagning av modeller

När du är klar med att skapa, utöka eller välja dina modeller måste du ladda upp dem till din Azure Digital Twins-instans för att göra dem tillgängliga för användning i din lösning.

Du kan ladda upp många modeller i ett enda API-anrop med hjälp av API:et Importera jobb. API:et kan samtidigt acceptera upp till Gränsen för Azure Digital Twins för antalet modeller i en instans, och det ordnar automatiskt om modeller om det behövs för att lösa beroenden mellan dem. Detaljerade instruktioner och exempel som använder det här API:et finns i massimportinstruktioner för modeller.

Ett alternativ till API:et för importjobb är modelluppladdningsexemplet, som använder de enskilda modell-API:erna för att ladda upp flera modellfiler samtidigt. Exemplet implementerar även automatisk omordning för att lösa modellberoenden. Det fungerar för närvarande bara med version 2 av DTDL.

Om du behöver ta bort alla modeller i en Azure Digital Twins-instans samtidigt kan du använda exemplet Model Deleter. Det här är ett projekt som innehåller rekursiv logik för att hantera modellberoenden genom borttagningsprocessen. Det fungerar för närvarande bara med version 2 av DTDL.

Om du vill rensa data i en instans genom att ta bort alla modeller tillsammans med alla tvillingar och relationer kan du använda API:et Ta bort jobb.

Visualisera modeller

När du har laddat upp modeller till din Azure Digital Twins-instans kan du använda Azure Digital Twins Explorer för att visa dem. Utforskaren innehåller en lista över alla modeller i instansen, samt ett modelldiagram som illustrerar hur de relaterar till varandra, inklusive arvs- och modellrelationer.

Kommentar

Här är ett exempel på hur ett modelldiagram kan se ut:

Mer information om modellupplevelsen i Azure Digital Twins Explorer finns i Utforska modeller och modellgrafen.

Nästa steg

Lär dig mer om att skapa modeller baserade på branschstandard ontologier: Vad är en ontologi?
Fördjupa dig i att hantera modeller med API-åtgärder: Hantera DTDL-modeller
Lär dig mer om hur modeller används för att skapa digitala tvillingar: Digitala tvillingar och tvillingdiagrammet

Lär dig mer om tvillingmodeller och hur du definierar dem i Azure Digital Twins

DTDL (Digital Twin Definition Language) för modeller

DTDL-versioner som stöds

Översikt över modell

Modellattribut

Egenskaper

Schema

Exempel på grundläggande egenskap

Exempel på komplex objekttyp

Exempel på DTDL v2-semantisk typ

Relationer

Exempel på grundläggande relation

Riktade och icke-riktade relationer

Egenskaper för relationer

Komponenter

Exempel på grundläggande komponent

Modellarv

DTDL v3-funktionstillägg

Tillägg för anteckning

Historiseringstillägg

Åsidosättande tillägg

QuantitativeTypes-tillägg

Tjänstspecifika DTDL-anteckningar

Modelleringsverktyg och metodtips

Använda befintliga ontologier av branschstandard

Överväg frågekonsekvenser

Verifiera modeller

Massuppladdning och borttagning av modeller

Visualisera modeller

Nästa steg

Ytterligare resurser