Meer informatie over dubbelmodellen en het definiëren ervan in Azure Digital Twins

Artikel
01/04/2024

Een belangrijk kenmerk van Azure Digital Twins is de mogelijkheid om uw eigen woordenlijst te definiëren en uw tweelinggrafiek te bouwen in de zelf gedefinieerde termen van uw bedrijf. Deze mogelijkheid wordt geboden via door de gebruiker geleverde modellen. U kunt modellen zien als zelfstandige naamwoorden in een beschrijving van uw wereld. Azure Digital Twins-modellen worden weergegeven in de DTDL (Digital Twin Definition Language) op basis van JSON-LD.

Een model is vergelijkbaar met een klasse in een objectgeoriënteerde programmeertaal en definieert een gegevensvorm voor één bepaald concept in uw echte werkomgeving. Modellen hebben namen (zoals Room of TemperatureSensor) en bevatten elementen zoals eigenschappen, onderdelen en relaties die beschrijven wat dit type entiteit in uw omgeving doet. Later gebruikt u deze modellen om digitale dubbels te maken die specifieke entiteiten vertegenwoordigen die voldoen aan deze typebeschrijving.

Digital Twin Definition Language (DTDL) voor modellen

Modellen voor Azure Digital Twins worden gedefinieerd met behulp van de Digital Twins Definition Language (DTDL).

U kunt de volledige taalbeschrijving voor DTDL v3 bekijken in GitHub: DTDL versie 3 Taalbeschrijving. Deze pagina bevat DTDL-referentiedetails en voorbeelden om u te helpen aan de slag te gaan met het schrijven van uw eigen DTDL-modellen.

DTDL is gebaseerd op JSON-LD en is computertaalonafhankelijk. DTDL is niet exclusief voor Azure Digital Twins. Het wordt ook gebruikt om apparaatgegevens in andere IoT-services, zoals IoT-Plug en Play, weer te geven.

In de rest van dit artikel wordt samengevat hoe de taal wordt gebruikt in Azure Digital Twins.

Ondersteunde DTDL-versies

Azure Digital Twins ondersteunt respectievelijk DTDL-versies 2 en 3 (ingekort in de documentatie naar respectievelijk v2 en v3). V3 is de aanbevolen keuze voor modellering in Azure Digital Twins op basis van de uitgebreide mogelijkheden, waaronder:

DTMI-versie ontspanning
Matrixondersteuning voor eigenschappen
Verhoogde limieten voor modelovername
Functie-extensies
- De mogelijkheid om aangepaste interfaceschema's te versieren met semantische typen (geleverd met de extensie QuantitativeTypes)

Waar deze functies worden besproken in de documentatie, worden ze vergezeld van een opmerking dat ze alleen beschikbaar zijn in DTDL v3. Zie DTDL v3 Language Description: Changes from Version 2 (Wijzigingen van versie 2) voor een volledige lijst met verschillen tussen DTDL v2 en v3.

Azure Digital Twins biedt ook ondersteuning voor het gebruik van een combinatie van v2- en v3-modellen binnen hetzelfde exemplaar. Houd rekening met de volgende beperkingen wanneer u modellen van beide versies samen gebruikt:

Een v2-interface kan geen v3-interface uitbreiden of een onderdeel met een v3-interface als schema hebben.
Omgekeerd kan een v3-interface een v2-interface uitbreiden en kan een v3-interface een onderdeel met een v2-interface als schema hebben.
Relaties kunnen in beide richtingen wijzen, van een v2-modelbron naar een v3-modeldoel, of omgekeerd van een v3-modelbron naar een v2-modeldoel.

U kunt ook bestaande v2-modellen migreren naar v3. Zie V2-modellen converteren naar v3 voor instructies over hoe u dit doet.

Notitie

Momenteel biedt Azure Digital Twins Explorer volledige ondersteuning voor DTDL v2-modellen en biedt ondersteuning voor beperkte functionaliteit voor DTDL v3-modellen. In Azure Digital Twins Explorer kunnen DTDL v3-modellen worden weergegeven in het deelvenster Modellen en dubbels die zijn gemaakt met DTDL v3-modellen, kunnen worden bekeken en bewerkt (inclusief modellen met matrixeigenschappen). DTDL v3-modellen worden echter niet weergegeven in het deelvenster Model Graph en kunnen niet worden geïmporteerd met behulp van Azure Digital Twins Explorer. Als u DTDL v3-modellen wilt importeren in uw exemplaar, gebruikt u een andere ontwikkelaarsinterface, zoals de API's en SDK's of de Azure CLI.

Overzicht van modellen

Modellen van dubbeltypen kunnen in elke teksteditor worden geschreven. De DTDL-taal volgt de JSON-syntaxis, dus u moet modellen opslaan met de extensie .json. Met behulp van de JSON-extensie kunnen veel programmeerteksteditors eenvoudige syntaxiscontrole en markeringen voor uw DTDL-documenten bieden. Er is ook een DTDL-extensie beschikbaar voor Visual Studio Code.

Dit zijn de velden in een modelinterface:

Veld	Beschrijving
`@id`	Een Digital Twin Model Identifier (DTMI) voor het model, in de indeling `dtmi:<domain>:<unique-model-identifier>;<model-version-number>`. In DTDL v3 kan het versienummer worden weggelaten of gestructureerd als een tweedelige (`<major>.<minor>`) versienummer.
`@type`	Identificeert het soort informatie dat wordt beschreven. Voor een interface is `Interface`het type .
`@context`	Hiermee stelt u de context voor het JSON-document in. Modellen moeten worden gebruikt `dtmi:dtdl:context;2` voor DTDL v2 of `dtmi:dtdl:context;3` voor DTDL v3. DTDL v3-modellen kunnen ook aanvullende functie-extensies in dit veld noemen.
`displayName`	[optioneel] Hiermee kunt u een beschrijvende naam voor het model definiëren. Als u dit veld niet gebruikt, gebruikt het model de volledige DTMI-waarde.
`contents`	Alle resterende interfacegegevens worden hier geplaatst als een matrix met kenmerkdefinities. Elk kenmerk moet een `@type` (`Property`, `Relationship`of `Component`) opgeven om het type interface-informatie te identificeren dat wordt beschreven, en vervolgens een set eigenschappen die het werkelijke kenmerk definiëren. In de volgende sectie worden de modelkenmerken gedetailleerd beschreven.

Hier volgt een voorbeeld van een eenvoudig DTDL-model. In dit model wordt een start beschreven, met één eigenschap voor een id. Het Home-model definieert ook een relatie met een Floor-model, dat kan worden gebruikt om aan te geven dat een homedubbel is verbonden met bepaalde floordubbels.

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

Modelkenmerken

De belangrijkste informatie over een model wordt gegeven door de kenmerken ervan, die zijn gedefinieerd in de contents sectie van de modelinterface.

Dit zijn de kenmerken die beschikbaar zijn in DTDL die worden ondersteund in Azure Digital Twins. Een DTDL-modelinterface die wordt gebruikt voor Azure Digital Twins kan nul, één of veel van elk van de volgende velden bevatten:

Eigenschap : eigenschappen zijn gegevensvelden die de status van een entiteit vertegenwoordigen (zoals de eigenschappen in veel objectgeoriënteerde programmeertalen). Eigenschappen hebben back-upopslag en kunnen op elk gewenst moment worden gelezen. Zie Eigenschappen hieronder voor meer informatie.
Relatie : met relaties kunt u voorstellen hoe een digitale dubbel kan worden betrokken bij andere digitale dubbels. Relaties kunnen verschillende semantische betekenissen vertegenwoordigen, zoals contains ("floor contains room"), cools ("hvac cools room"), isBilledTo ("compressor wordt gefactureerd aan gebruiker") enzovoort. Met relaties kan de oplossing een grafiek van onderling gerelateerde entiteiten bieden. Relaties kunnen ook eigenschappen van hun eigen eigenschappen hebben. Zie de onderstaande relaties voor meer informatie.
Component - Met onderdelen kunt u desgewenst uw modelinterface bouwen als een assembly van andere interfaces. Een voorbeeld van een onderdeel is een frontCamera-interface (en een andere onderdeelinterface backCamera) die wordt gebruikt bij het definiëren van een model voor een telefoon. Definieer eerst een interface voor frontCamera alsof het een eigen model was en verwijs er vervolgens naar bij het definiëren van Telefoon.

Gebruik een onderdeel om iets te beschrijven dat een integraal onderdeel van uw oplossing is, maar geen afzonderlijke identiteit nodig heeft en niet afzonderlijk hoeft te worden gemaakt, verwijderd of opnieuw hoeft te worden gerangschikt in de tweelinggrafiek. Als u wilt dat entiteiten onafhankelijke bestaanen hebben in de tweelinggrafiek, vertegenwoordigen ze als afzonderlijke digitale dubbels van verschillende modellen, verbonden door relaties.

Tip

Onderdelen kunnen ook worden gebruikt voor de organisatie om sets gerelateerde eigenschappen binnen een modelinterface te groeperen. In deze situatie kunt u elk onderdeel beschouwen als een naamruimte of map in de interface.

Zie Onderdelen hieronder voor meer informatie.

De DTDL v3-taalbeschrijving definieert ook opdrachten en telemetrie, maar geen van deze worden gebruikt in Azure Digital Twins. Opdrachten worden niet ondersteund en telemetrie, hoewel dit is toegestaan in modeldefinities, heeft geen unieke use-case in Azure Digital Twins-modellering. In plaats van DTDL-telemetrie te gebruiken, moet u DTDL-eigenschappen gebruiken voor het opslaan van statusgegevens van dubbels.

Notitie

Hoewel het niet nodig is om telemetrievelden in uw DTDL-modellen te definiëren om binnenkomende apparaatgegevens op te slaan, kan Azure Digital Twins gebeurtenissen verzenden als telemetrie met behulp van de SendTelemetry-API. Hiermee wordt een digital twin-telemetrieberichtgebeurtenis geactiveerd die kan worden ontvangen door een gebeurtenis-handler om acties uit te voeren op andere tweelingen of downstreamservices te activeren.

Eigenschappen

In deze sectie vindt u meer informatie over eigenschappen in DTDL-modellen.

Zie Eigenschap in de taalbeschrijving van DTDL v3 voor uitgebreide informatie over de velden die kunnen worden weergegeven als onderdeel van een eigenschap.

Notitie

Het writable DTDL-kenmerk voor eigenschappen wordt momenteel niet ondersteund in Azure Digital Twins. Het kan worden toegevoegd aan het model, maar Azure Digital Twins dwingt het niet af. Zie Servicespecifieke DTDL-notities voor meer informatie.

Schema

Volgens DTDL kan het schema voor eigenschapskenmerken een standaard primitief type zijn,integerdoublestring en booleanandere typen, zoals dateTime enduration.

Naast primitieve typen kunnen eigenschapsvelden deze complexe typen hebben:

Object
Map
Enum
Array, alleen in DTDL v3. Array type voor eigenschappen wordt niet ondersteund in DTDL v2.

Ze kunnen ook semantische typen zijn, waarmee u aantekeningen kunt maken op waarden met eenheden. In DTDL v2 worden semantische typen systeemeigen ondersteund. In DTDL v3 kunt u ze opnemen met een functie-extensie.

Voorbeeld van basiseigenschap

Hier volgt een eenvoudig voorbeeld van een eigenschap in een DTDL-model. In dit voorbeeld ziet u de id-eigenschap van een start.

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

Voorbeeld van complex objecttype

Eigenschappen kunnen van complexe typen zijn, waaronder een Object type.

In het volgende voorbeeld ziet u een andere versie van het Home-model, met een eigenschap voor het adres. address is een object, met zijn eigen velden voor straat, stad, staat en 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"
        }
      ]
    }
  ]
}

Voorbeeld van Semantisch type DTDL v2

Semantische typen zijn bedoeld voor het uitdrukken van een waarde met een eenheid. Eigenschappen voor Azure Digital Twins kunnen gebruikmaken van een van de semantische typen die worden ondersteund door DTDL.

In DTDL v2 worden semantische typen systeemeigen ondersteund. Zie Semantische typen in de DTDL v2-taalbeschrijving voor meer informatie over semantische typen in DTDL v2. Zie de functieextensie QuantitativeTypes DTDL v3 voor meer informatie over semantische typen in DTDL v3.

In het volgende voorbeeld ziet u een DTDL v2-sensormodel met semantische typeeigenschappen voor Vochtigheid en Temperatuur.

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

Belangrijk

'Eigenschap' moet het eerste element van de @type matrix zijn, gevolgd door het semantische type. Anders is het veld mogelijk niet zichtbaar in Azure Digital Twins Explorer.

Relaties

In deze sectie wordt dieper ingegaan op relaties in DTDL-modellen.

Zie Relatie in de DTDL v3-taalbeschrijving voor een uitgebreide lijst met velden die kunnen worden weergegeven als onderdeel van een relatie.

Notitie

De writablekenmerken , minMultiplicityen maxMultiplicity DTDL voor relaties worden momenteel niet ondersteund in Azure Digital Twins. Ze kunnen worden toegevoegd aan het model, maar Azure Digital Twins dwingt ze niet af. Zie Servicespecifieke DTDL-notities voor meer informatie.

Voorbeeld van basisrelatie

Hier volgt een eenvoudig voorbeeld van een relatie in een DTDL-model. In dit voorbeeld ziet u een relatie op een thuismodel waarmee deze verbinding kan maken met een vloermodel.

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

Notitie

Voor relaties @id is een optioneel veld. Als er geen @id is opgegeven, wijst de interfaceprocessor van de digitale dubbel er een toe.

Gerichte en niet-gerichte relaties

Relaties kunnen worden gedefinieerd met of zonder een doel. Een doel geeft aan welke typen dubbels de relatie kan bereiken. U kunt bijvoorbeeld een doel opnemen om op te geven dat een thuismodel alleen een rel_has_floors relatie kan hebben met tweelingen die floordubbels zijn.

Soms wilt u mogelijk een relatie definiëren zonder een specifiek doel, zodat de relatie verbinding kan maken met veel verschillende typen tweelingen.

Hier volgt een voorbeeld van een relatie in een DTDL-model dat geen doel heeft. In dit voorbeeld is de relatie bedoeld voor het definiëren van de sensoren die een ruimte kan hebben en de relatie kan verbinding maken met elk type.

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

Eigenschappen van relaties

Met DTDL kunnen relaties ook eigenschappen van hun eigen eigenschappen hebben. Wanneer u een relatie in een DTDL-model definieert, kan de relatie een eigen properties veld hebben waarin u aangepaste eigenschappen kunt definiëren om de relatiespecifieke status te beschrijven.

In het volgende voorbeeld ziet u een andere versie van het Home-model, waarbij de rel_has_floors relatie een eigenschap heeft die aangeeft wanneer de gerelateerde verdieping voor het laatst bezet was.

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

Onderdelen

In deze sectie wordt dieper ingegaan op onderdelen in DTDL-modellen.

Zie Component in de DTDL v3 Language Description voor een uitgebreide lijst met velden die kunnen worden weergegeven als onderdeel van een onderdeel.

Voorbeeld van basisonderdeel

Hier volgt een basisvoorbeeld van een onderdeel in een DTDL-model. In dit voorbeeld ziet u een ruimtemodel dat gebruikmaakt van een thermostaatmodel als onderdeel.

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

Als andere modellen in deze oplossing ook een thermostaat moeten bevatten, kunnen ze verwijzen naar hetzelfde thermostaatmodel als een onderdeel in hun eigen definities, net zoals Room wel.

Belangrijk

De componentinterface (thermostaat in het bovenstaande voorbeeld) moet worden gedefinieerd in dezelfde matrix als alle interfaces die deze gebruiken (Ruimte in het bovenstaande voorbeeld) om de verwijzing naar het onderdeel te vinden.

Modelovername

Soms wilt u een model verder specialiseren. Het kan bijvoorbeeld handig zijn om een algemene modelruimte en gespecialiseerde varianten ConferenceRoom en Gym te hebben. DTDL ondersteunt overname om specialisatie uit te drukken. Interfaces kunnen overnemen van een of meer andere interfaces. U kunt dit doen door een extends veld toe te voegen aan het model.

De extends sectie is een interfacenaam of een matrix met interfacenamen (waardoor de uitbreidingsinterface kan worden overgenomen van meerdere bovenliggende modellen). Eén bovenliggend element kan fungeren als basismodel voor meerdere uitbreidingsinterfaces.

Notitie

In DTDL v2 kunnen er extends maximaal twee interfaces voor worden vermeld. In DTDL v3 is er geen limiet voor het aantal onmiddellijke waarden voor een extends.

In zowel DTDL v2 als v3 is de totale dieptelimiet voor een extends hiërarchie 10.

In het volgende voorbeeld wordt het Home-model uit het eerdere DTDL-voorbeeld opnieuw voorgesteld als een subtype van een groter 'kern'-model. Het bovenliggende model (Core) wordt eerst gedefinieerd en vervolgens bouwt het onderliggende model (Home) erop voort met behulp van extends.

{
    "@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 dit geval draagt Core een id en naam bij aan Home. Andere modellen kunnen ook het Core-model uitbreiden om deze eigenschappen op te halen. Hier volgt een ruimtemodel dat dezelfde bovenliggende interface uitbreidt:

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

Zodra overname is toegepast, worden met de uitbreidingsinterface alle eigenschappen uit de gehele overnameketen weergegeven.

De uitbreidingsinterface kan geen van de definities van de bovenliggende interfaces wijzigen; het kan alleen aan hen worden toegevoegd. Het kan ook geen mogelijkheid opnieuw definiëren die al is gedefinieerd in een van de bovenliggende interfaces (zelfs als de mogelijkheden zijn gedefinieerd om hetzelfde te zijn). Als een bovenliggende interface bijvoorbeeld een double eigenschap massdefinieert, kan de uitbreidingsinterface geen declaratie van massbevatten, zelfs niet als het ook een double.

DTDL v3-functie-extensies

DTDL v3 maakt taalextensies mogelijk die aanvullende metamodelklassen definiëren, die u kunt gebruiken om uitgebreidere modellen te schrijven. In deze sectie worden de functiesextensieklassen beschreven die u kunt gebruiken om niet-kernfuncties toe te voegen aan uw DTDL v3-modellen.

Elke functie-extensie wordt geïdentificeerd door de contextaanduiding. Dit is een unieke DTMI-waarde (Digital Twin Model Identifier). Als u een functie-extensie in een model wilt inschakelen, voegt u de contextaanduiding van de extensie toe aan het veld van @context het model (naast de algemene DTDL-contextaanduiding van dtmi:dtdl:context;3). U kunt meerdere functie-extensies toevoegen aan hetzelfde model.

Hier volgt een voorbeeld van hoe dat @context veld eruit kan zien met functie-extensies. Het volgende fragment is afkomstig van een model dat gebruikmaakt van zowel de extensie QuantitativeTypes als de annotatie-extensie.

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

Nadat u een functie-extensie aan een model hebt toegevoegd, hebt u toegang tot de adjunct-typen van die extensie binnen het model. U kunt aanvullende typen toevoegen aan het @type veld van een DTDL-element om het element extra mogelijkheden te geven. Het type adjunct kan extra eigenschappen toevoegen aan het element.

Hier volgt bijvoorbeeld een fragment van een model dat gebruikmaakt van de aantekeningsextensie. Deze extensie heeft een adjunct-type genaamd ValueAnnotation, dat in het onderstaande voorbeeld wordt toegevoegd aan een eigenschapselement. Als u dit adjunct-type toevoegt aan het eigenschapselement, kan het element een extra annotates veld hebben, dat wordt gebruikt om een andere eigenschap aan te geven die door dit element wordt geannoteerd.

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

In de rest van deze sectie worden de aantekeningsextensie en andere DTDL v3-functie-extensies uitgebreider uitgelegd.

Aantekeningsextensie

De extensie Aantekeningen wordt gebruikt om aangepaste metagegevens toe te voegen aan een eigenschapselement in een DTDL v3-model. De contextaanduiding is dtmi:dtdl:extension:annotation;1.

Deze extensie omvat het ValueAnnotation adjunct-type, dat kan worden toegevoegd aan een DTDL-eigenschapselement. Het ValueAnnotation type voegt één veld toe aan het element, annotateswaarmee u een andere eigenschap kunt noemen die wordt geannoteerd door het huidige element.

Zie de aantekeningsextensie in de DTDL v3-taalbeschrijving voor meer informatie en voorbeelden van deze extensie.

Historisatie-extensie

De historisatie-extensie wordt gebruikt om een eigenschap in een DTDL v3-model aan te wijzen als iets dat moet worden historiseerd (wat betekent dat de historische volgorde van de waarden moet worden vastgelegd, samen met tijdstippen waarop de waarden veranderen). De contextaanduiding is dtmi:dtdl:extension:historization;1.

Deze extensie omvat het Historized adjunct-type, dat kan worden toegevoegd als een co-type aan een DTDL-eigenschapselement om aan te geven dat de service de historische waarden van het element moet behouden en deze beschikbaar moet maken voor het uitvoeren van query's en analyses. Het Historized type adjunct voegt geen velden toe aan het element.

Zie Historization-extensie in de DTDL v3 Language Description voor meer informatie en voorbeelden van deze extensie.

Extensie overschrijven

De overschrijvende extensie wordt gebruikt om een eigenschap in een DTDL V3-model met een instantiewaarde te overschrijven. Deze wordt gebruikt in combinatie met de aantekeningsextensie en de contextaanduiding is dtmi:dtdl:extension:overriding;1.

Deze extensie omvat het Override adjunct-type, dat kan worden toegevoegd aan een DTDL-eigenschap die ook wordt getypeerd met ValueAnnotation (uit de aantekeningsextensie). Het Override type voegt één veld toe aan het element, overrideswaarmee u een veld op het geannoteerde element een naam kunt geven die moet worden overschreven door de waarde van het huidige element.

Zie De extensie overschrijven in de DTDL v3-taalbeschrijving voor meer informatie en voorbeelden van deze extensie.

Extensie Kwantitatieftypen

De extensie QuantitativeTypes wordt gebruikt om semantische typen, eenheidstypen en eenheden in een DTDL v3-model in te schakelen. De contextaanduiding is dtmi:dtdl:extension:quantitativeTypes;1.

Deze extensie maakt het gebruik van veel semantische typen mogelijk als adjunct-typen, die kunnen worden toegevoegd aan een CommandRequest, een veld, een MapValue of een eigenschap in DTDL v3. Semantische typen voegen één veld toe aan het element, unitdat een geldige eenheid accepteert die overeenkomt met het semantische type.

Zie de extensie QuantitativeTypes in de DTDL v3-taalbeschrijving voor meer informatie over de extensie, inclusief voorbeelden en een volledige lijst met ondersteunde semantische typen en eenheden.

Servicespecifieke DTDL-notities

Niet alle services die gebruikmaken van DTDL implementeren exact dezelfde functies van DTDL. Er zijn enkele DTDL-functies die momenteel niet door Azure Digital Twins worden ondersteund, waaronder:

DTDL-opdrachten
Het writable kenmerk voor eigenschappen of relaties. Hoewel dit kenmerk kan worden ingesteld volgens DTDL-specificaties, wordt de waarde niet gebruikt door Azure Digital Twins. In plaats daarvan worden deze kenmerken altijd behandeld als beschrijfbaar door externe clients met algemene schrijfmachtigingen voor de Azure Digital Twins-service.
De minMultiplicity en maxMultiplicity eigenschappen voor relaties. Hoewel deze kenmerken kunnen worden ingesteld volgens DTDL-specificaties, worden de waarden niet afgedwongen door Azure Digital Twins.

Voor een DTDL-model dat compatibel is met Azure Digital Twins, moet het ook voldoen aan deze vereisten:

Alle DTDL-elementen op het hoogste niveau in een model moeten van het type Interfacezijn. De reden hiervoor is dat Azure Digital Twins-model-API's JSON-objecten kunnen ontvangen die een interface of een matrix van interfaces vertegenwoordigen. Als gevolg hiervan zijn er geen andere DTDL-elementtypen toegestaan op het hoogste niveau.
DTDL voor Azure Digital Twins mag geen opdrachten definiëren.
Azure Digital Twins staat slechts één niveau van het nesten van onderdelen toe, wat betekent dat een interface die als onderdeel wordt gebruikt, geen onderdelen zelf kan hebben.
Interfaces kunnen niet inline worden gedefinieerd binnen andere DTDL-interfaces; Ze moeten worden gedefinieerd als afzonderlijke entiteiten op het hoogste niveau met hun eigen id's. Wanneer een andere interface die interface als onderdeel of overname wil opnemen, kan deze vervolgens verwijzen naar de id.

Hulpprogramma's en best practices voor modellering

In deze sectie worden aanvullende overwegingen en aanbevelingen voor modellering beschreven.

Bestaande industriestandaard ontologieën gebruiken

Een ontologie is een reeks modellen die een bepaald domein uitgebreid beschrijven, zoals productie, bouwstructuren, IoT-systemen, slimme steden, energienetten, webinhoud en meer.

Als uw oplossing voor een bepaalde branche is die gebruikmaakt van een soort modelleringsstandaard, kunt u overwegen om te beginnen met een bestaande set modellen die zijn ontworpen voor uw branche in plaats van uw modellen helemaal zelf te ontwerpen. Microsoft werkt samen met domeinexperts om DTDL-modelonologieën te maken op basis van industriestandaarden, om te helpen bij het minimaliseren van heruitvinding en het stimuleren van consistentie en eenvoud in alle brancheoplossingen. U kunt meer lezen over deze ontologieën, waaronder hoe u deze kunt gebruiken en welke ontologieën er nu beschikbaar zijn, in Wat is een ontologie?.

Bekijk de gevolgen van query's

Bij het ontwerpen van modellen om de entiteiten in uw omgeving weer te geven, kan het handig zijn om vooruit te kijken en rekening te houden met de gevolgen van de query van uw ontwerp. U kunt eigenschappen ontwerpen op een manier die grote resultatensets van grafiekkruising voorkomt. U kunt ook relaties modelleren die in één query moeten worden beantwoord als relaties op één niveau.

Modellen valideren

Nadat u een model hebt gemaakt, is het raadzaam om uw modellen offline te valideren voordat u ze uploadt naar uw Azure Digital Twins-exemplaar.

Om u te helpen uw modellen te valideren, wordt er een DTDL-parseringsbibliotheek aan de clientzijde van .NET aangeboden in NuGet: DTDLParser. U kunt de parserbibliotheek rechtstreeks in uw C#-code gebruiken. U kunt ook het voorbeeldgebruik van de parser bekijken in de DTDLParserResolveSample in GitHub.

Modellen bulksgewijs uploaden en verwijderen

Wanneer u klaar bent met het maken, uitbreiden of selecteren van uw modellen, moet u ze uploaden naar uw Azure Digital Twins-exemplaar om ze beschikbaar te maken voor gebruik in uw oplossing.

U kunt veel modellen uploaden in één API-aanroep met behulp van de Import Jobs-API. De API kan tegelijkertijd de limiet voor Azure Digital Twins accepteren voor het aantal modellen in een exemplaar en de volgorde van modellen wordt automatisch opnieuw gerangschikt als dat nodig is om afhankelijkheden tussen deze modellen op te lossen. Zie de instructies voor bulkimport voor modellen voor gedetailleerde instructies en voorbeelden die gebruikmaken van deze API.

Een alternatief voor de IMPORT Jobs-API is het voorbeeld van de modeluploader, die gebruikmaakt van de afzonderlijke model-API's om meerdere modelbestanden tegelijk te uploaden. In het voorbeeld wordt ook automatisch opnieuw ordenen geïmplementeerd om modelafhankelijkheden op te lossen. Het werkt momenteel alleen met versie 2 van DTDL.

Als u alle modellen in een Azure Digital Twins-exemplaar tegelijk wilt verwijderen, kunt u het voorbeeld model verwijderen. Dit is een project dat recursieve logica bevat voor het verwerken van modelafhankelijkheden via het verwijderingsproces. Het werkt momenteel alleen met versie 2 van DTDL.

Als u de gegevens in een exemplaar wilt wissen door alle modellen samen met alle dubbels en relaties te verwijderen, kunt u de API Taken verwijderen gebruiken.

Modellen visualiseren

Zodra u modellen hebt geüpload naar uw Azure Digital Twins-exemplaar, kunt u Azure Digital Twins Explorer gebruiken om ze weer te geven. De verkenner bevat een lijst met alle modellen in het exemplaar, evenals een modelgrafiek die laat zien hoe ze zich met elkaar verhouden, inclusief overname- en modelrelaties.

Notitie

Hier volgt een voorbeeld van hoe een modelgrafiek eruit kan zien:

Zie Modellen en modelgrafiek verkennen voor meer informatie over de modelervaring in Azure Digital Twins Explorer.

Volgende stappen

Meer informatie over het maken van modellen op basis van industriestandaard ontologieën: Wat is een ontologie?
Meer informatie over het beheren van modellen met API-bewerkingen: DTDL-modellen beheren
Meer informatie over hoe modellen worden gebruikt om digitale dubbels te maken: Digitale dubbels en de tweelinggrafiek

Meer informatie over dubbelmodellen en het definiëren ervan in Azure Digital Twins

Digital Twin Definition Language (DTDL) voor modellen

Ondersteunde DTDL-versies

Overzicht van modellen

Modelkenmerken

Eigenschappen

Schema

Voorbeeld van basiseigenschap

Voorbeeld van complex objecttype

Voorbeeld van Semantisch type DTDL v2

Relaties

Voorbeeld van basisrelatie

Gerichte en niet-gerichte relaties

Eigenschappen van relaties

Onderdelen

Voorbeeld van basisonderdeel

Modelovername

DTDL v3-functie-extensies

Aantekeningsextensie

Historisatie-extensie

Extensie overschrijven

Extensie Kwantitatieftypen

Servicespecifieke DTDL-notities

Hulpprogramma's en best practices voor modellering

Bestaande industriestandaard ontologieën gebruiken

Bekijk de gevolgen van query's

Modellen valideren

Modellen bulksgewijs uploaden en verwijderen

Modellen visualiseren

Volgende stappen

Aanvullende resources