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

En viktig egenskap hos Azure Digital Twins är möjligheten att definiera din egen vokabulär och skapa tvillinggrafen i de självdefinierade villkoren i din verksamhet. Den här funktionen tillhandahålls via modeller som tillhandahålls av användaren. Du kan tänka på modeller som substantiv i en beskrivning av din värld. Azure Digital Twins modeller representeras i JSON-LD-baserat 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 Room eller TemperatureSensor) och innehåller element som egenskaper, telemetri/händelser och kommandon som beskriver vad den här typen av entitet i din miljö kan göra. Senare kommer du att använda dessa modeller för att skapa digitala tvillingar som representerar specifika entiteter som uppfyller den här typbeskrivningen.

DTDL (Digital Twin Definition Language) för modeller

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

Du kan visa fullständiga språkspecifikter för DTDL i GitHub: Digital Twins Definition Language (DTDL) – Version 2. Den här sidan innehåller detaljerad DTDL-referens och exempel som hjälper dig att komma igång med att skriva dina egna DTDL-modeller.

DTDL är baserat på JSON-LD och är programmeringsspråksoberoende. DTDL är inte exklusivt för Azure Digital Twins, men används också för att representera enhetsdata i andra IoT-tjänster som IoT Plug and Play. Azure Digital Twins DTDL version 2 (användning av DTDL version 1 med Azure Digital Twins har nu gjorts inaktuell).

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

Azure Digital Twins om DTDL-implementering

Det är inte alla tjänster som använder DTDL som implementerar exakt samma funktioner i DTDL. Det finns vissa DTDL-funktioner som Azure Digital Twins stöder för närvarande, 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. Dessa attribut kan anges enligt DTDL-specifikationer, men värdena tillämpas inte av Azure Digital Twins.

För att en DTDL-modell ska vara kompatibel 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-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 inte definiera några kommandon.
• Azure Digital Twins tillåter endast en enda nivå av kapsling av komponenter, vilket innebär att ett gränssnitt som används som en komponent inte kan ha några komponenter i sig.
• 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:er. När ett annat gränssnitt sedan vill inkludera det gränssnittet som en komponent eller genom arv kan det referera till dess ID.

Översikt över modell

Element i en modell

Inom en modelldefinition är kodobjektet på den översta nivån ett gränssnitt. Den här typen kapslar in hela modellen och resten av modellen definieras i gränssnittet.

Ett DTDL-modellgränssnitt 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 lagring som backing och kan läsas när som helst. Mer information finns i Egenskaper och telemetri nedan.

• Telemetri – Telemetrifält representerar mått eller händelser och används ofta för att beskriva enhetssensoravläsningar. Till skillnad från egenskaper lagras inte telemetri på en digital tvilling. Det är en serie med tidsbundna datahändelser som måste hanteras när de inträffar. Mer information finns i Egenskaper och telemetri nedan.

• Relation – Med relationer kan du representera hur en digital tvilling kan användas med andra digitala tvillingar. Relationer kan representera olika semantiska betydelser, t.ex. contains ("floor contains room"), cools ("hvac cools room"), isBilledTo ("kylar faktureras till användaren") och så vidare. Relationer gör att lösningen kan 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 ditt modellgränssnitt som en sammansättning av andra gränssnitt om du vill. Ett exempel på en komponent är ett frontCamera-gränssnitt (och ett annat komponentgränssnitt backCamera) som används för att definiera en modell för en telefon. Definiera först ett gränssnitt för frontCamera 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 viktig 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 förekomster i tvillingdiagrammet ska du representera dem som separata digitala tvillingpar med olika modeller, anslutna med relationer.

  Tips

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

  Mer information finns i Komponenter nedan.

Modellkod

Tvillingtypmodeller kan skrivas i valfri textredigerare. DTDL-språket följer JSON-syntaxen, så du bör lagra modeller med filnamnstillägget .json. Med 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 för Visual Studio Code.

Fälten i modellen är:

Exempelmodell

Det här avsnittet innehåller ett exempel på en grundläggande modell som skrivits som ett DTDL-gränssnitt.

Den här modellen beskriver ett Hem med en egenskap för ett ID. Hemmodellen definierar också en relation till en golvmodell, som kan användas för att ange att en hemtvilling är ansluten till vissa golvtvillingarna.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "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"
    }
  ]
}

Egenskaper och telemetri

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

En omfattande lista över de fält som kan visas som en del av en egenskap finns i Egenskap i specifikationen för DTDL v2. En omfattande lista över de fält som kan visas som en del av telemetrin finns i Telemetri i DTDL v2-specifikationen.

Skillnaden mellan egenskaper och telemetri

Här är några riktlinjer för begreppsmässigt skilja mellan DTDL-egenskap och telemetri i Azure Digital Twins.

• Egenskaper förväntas ha lagringsenheter, vilket innebär att du kan läsa en egenskap när som helst och hämta dess värde. Om egenskapen är skrivbar kan du även lagra ett värde i egenskapen .
• Telemetri är mer som en ström av händelser. Det är en uppsättning datameddelanden som har korta livslängder. Om du inte ställer in att lyssna efter händelsen och åtgärder som ska vidtas när den inträffar finns det ingen spårning av händelsen vid ett senare tillfälle. Du kan inte gå tillbaka till den och läsa den senare.
  • I C#-termer är telemetri som en C#-händelse.
  • I IoT-termer är telemetri vanligtvis ett enda mått som skickas av en enhet.

Telemetri används ofta med IoT-enheter eftersom många enheter antingen inte kan eller inte är intresserade av att lagra de måttvärden som de genererar. I stället skickar de ut dem som en ström av "telemetrihändelser". I det här fallet kan du inte när som helst fråga enheten efter det senaste värdet i telemetrifältet. Du måste lyssna på meddelandena från enheten och vidta åtgärder när meddelandena tas emot.

När du utformar en modell i en Azure Digital Twins du förmodligen använda egenskaper i de flesta fall för att modellera dina tvillingar. På så sätt kan du ha lagring för lagringsenheter och möjlighet att läsa och köra frågor mot datafälten.

Telemetri och egenskaper fungerar ofta tillsammans för att hantera indata från enheter. Eftersom all ingress till Azure Digital Twins ärvia API:er använder du vanligtvis ingressfunktionen för att läsa telemetri- eller egenskapshändelser från enheter och ange en egenskap i Azure Digital Twins som svar.

Du kan också publicera en telemetrihändelse från Azure Digital Twins API. Precis som med annan telemetri är det en kortlivad händelse som kräver att en lyssnare hanterar.

Schema

Enligt DTDL kan schemat för egenskaps- och telemetriattribut vara av primitiva standardtyper– , , och – och andra typer integer som och double string boolean dateTime duration .

Förutom primitiva typer kan egenskaps- och telemetrifält ha dessa komplexa typer:

• Object
• Map
• Enum
• (endast telemetri)Array

De kan också vara semantiskatyper, vilket gör att du kan kommentera värden med enheter.

Grundläggande egenskaps- och telemetriexempel

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

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "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"
    }
  ]
}

Här är ett grundläggande exempel på ett telemetrifält på en DTDL-modell. Det här exemplet visar telemetri om temperatur på en sensor.

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

Exempel på komplex typ (objekt)

Egenskaper och telemetri 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, ort, delstat och zip.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "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å semantisk typ

Semantiska typer gör det möjligt att uttrycka ett värde med en enhet. Egenskaper och telemetri kan representeras med någon av de semantiska typer som stöds av DTDL. Mer information om semantiska typer i DTDL och vilka värden som stöds finns i Semantiska typer i DTDL v2-specifikationen.

I följande exempel visas en sensormodell med en telemetri av semantisk typ för Temperatur och en semantisk typegenskap för Fuktighet.

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

Relationer

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

En omfattande lista över de fält som kan visas som en del av en relation finns i Relation i specifikationen för DTDL v2.

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 hemmodell som gör att den kan ansluta till en golvmodell.

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "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"
    }
  ]
}

Riktade och icke-riktade relationer

Relationer kan definieras med eller utan ett 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 hemmodell bara kan ha en rel_has_floors med tvillingar som är golvtvillingarna.

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 används relationen för att definiera vilka sensorer ett rum kan ha och relationen kan ansluta till vilken typ som helst.

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {
      "@type": ["Property", "Humidity"],
      "name": "humidity",
      "unit": "gramPerCubicMetre",
      "schema": "double"
    },
    {
      "@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 tillåter också att relationer har egna egenskaper. När du definierar en relation i en DTDL-modell kan relationen ha ett eget fält där du kan definiera anpassade egenskaper för properties att beskriva relationsspecifikt tillstånd.

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

{
  "@id": "dtmi:com:adt:dtsample:home;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "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 specifikationen för DTDL v2.

Grundläggande komponentexempel

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 en komponent.

[
  {
    "@id": "dtmi:com:adt:dtsample:room;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Room",
    "extends": "dtmi:com:adt:dtsample:core;1",
    "contents": [
      {
        "@type": ["Property", "Humidity"],
        "name": "humidity",
        "unit": "gramPerCubicMetre",
        "schema": "double"
      },
      {
        "@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;2",
    "@id": "dtmi:com:adt:dtsample:thermostat;1",
    "@type": "Interface",
    "displayName": "thermostat",
    "contents": [
      {
        "@type": ["Property", "Temperature"],
        "name": "temperature",
        "unit": "degreeFahrenheit",
        "schema": "double"
      }
    ]
  }
]

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 rummet gör.

Modellarv

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

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

I följande exempel åter föreställa sig hemmodellen från det tidigare DTDL-exemplet som en undertyp av en större "kärnmodell". Den överordnade modellen (Core) definieras först och sedan bygger den underordnade modellen (Start) på den med hjälp av extends .

{
    "@id": "dtmi:com:adt:dtsample:core;1",
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "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;2",
  "displayName": "Home",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

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

{
  "@id": "dtmi:com:adt:dtsample:room;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  "displayName": "Room",
  "extends": "dtmi:com:adt:dtsample:core;1",
  "contents": [
    {

När arv har tillämpats exponerar det utökande gränssnittet 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 i dem. Det kan inte heller definiera om en funktion som redan har definierats i något av dess överordnade gränssnitt (även om funktionerna har definierats att vara desamma). Om ett överordnat gränssnitt till exempel definierar en egenskapsvikt kan det utökande gränssnittet inte innehålla en deklaration av mass , även om double det också är en double .

Metodtips för modellering

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

Verifiera modeller

Det finns ett språkoberoende DTDL-valideringsexempel för att verifiera modelldokument för att kontrollera att DTDL är korrekt innan du överför det till din instans.

DTDL-validerarexempel bygger på ett .NET DTDL-parserbibliotek, som är tillgängligt på NuGet som ett bibliotek på klientsidan: Microsoft.Azure.DigitalTwins.Parser. Du kan också använda biblioteket direkt för att utforma din egen valideringslösning. När du använder parserbiblioteket ska du se till att använda en version som är kompatibel med den version Azure Digital Twins körs. För närvarande är detta version 3.12.4.

Du kan lära dig mer om valideringsexempel och parserbibliotek, inklusive användningsexempel, i Parsa och validera modeller.

Modelleringsverktyg

Det finns flera exempel som gör det ännu enklare att hantera modeller och ontologier. De finns på den här lagringsplatsen: Verktyg Digital Twins DTDL (Definition Language).

I det här avsnittet beskrivs den aktuella uppsättningen exempel i detalj.

Modelluppladdare

När du är klar med att skapa, utöka eller välja dina modeller kan 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 göra det med hjälp av Azure Digital Twins API:er, enligt beskrivningen i Hantera DTDL-modeller.

Men om du har många modeller att ladda upp– eller om de har många beroenden som skulle göra beställningen av enskilda uppladdningar komplicerad – kan du använda exemplet Azure Digital Twins Model Uploader för att ladda upp många modeller samtidigt. Följ anvisningarna i exemplet för att konfigurera och använda det här projektet för att ladda upp modeller till din egen instans.

Modell visualiserare

När du har laddat upp modeller till din Azure Digital Twins-instans kan du visa modellerna i din Azure Digital Twins-instans, inklusive arv och modellrelationer, med hjälp av Azure Digital Twins Model Visualizer. Det här exemplet är för närvarande i ett utkasttillstånd. Vi uppmuntrar digital twins-utvecklings communityn att utöka och bidra till exemplet.

Nästa steg

• Lär dig mer om att skapa modeller baserade på branschstandardbaserade 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: Digital Twins och tvillingdiagrammet