Share via

Handleiding voor ioT-Plug en Play modellering

  • Artikel

De kern van IoT Plug en Play is een apparaatmodel dat de mogelijkheden van een apparaat beschrijft voor een IoT Plug en Play-toepassing. Dit model is gestructureerd als een set interfaces die het volgende definiëren:

  • Eigenschappen die de alleen-lezen- of schrijfbare status van apparaat of andere entiteit vertegenwoordigen. Een serienummer van een apparaat kan bijvoorbeeld een alleen-lezeneigenschap zijn en een doeltemperatuur op een thermostaat kan een schrijfbare eigenschap zijn.
  • Telemetrievelden die de gegevens definiëren die door een apparaat worden verzonden, ongeacht of de gegevens een normale stroom sensormetingen, een incidentele fout of een informatiebericht zijn.
  • Opdrachten waarmee functies of bewerkingen die op het apparaat kunnen worden uitgevoerd, worden beschreven. Met een opdracht kan bijvoorbeeld een gateway opnieuw worden opgestart of een foto worden gemaakt met een externe camera.

Voor meer informatie over hoe IoT Plug en Play apparaatmodellen gebruikt, raadpleegt u de handleiding voor IoT-Plug en Play voor apparaatontwikkelaars en de ontwikkelaarshandleiding voor IoT-Plug en Play-services.

Als u een model wilt definiëren, gebruikt u de Digital Twins Definition Language (DTDL). DTDL maakt gebruik van een JSON-variant met de naam JSON-LD. Het volgende codefragment toont het model voor een thermostaatapparaat dat:

  • Heeft een unieke model-id: dtmi:com:example:Thermostat;1.
  • Verzendt temperatuurtelemetrie.
  • Heeft een beschrijfbare eigenschap om de doeltemperatuur in te stellen.
  • Heeft een alleen-lezen eigenschap om de maximale temperatuur te rapporteren sinds de laatste herstart.
  • Reageert op een opdracht die gedurende een bepaalde periode maximale, minimale en gemiddelde temperaturen aanvraagt.
{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "displayName": "Temperature",
      "description": "Temperature in degrees Celsius.",
      "schema": "double",
      "unit": "degreeCelsius"
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "targetTemperature",
      "schema": "double",
      "displayName": "Target Temperature",
      "description": "Allows to remotely specify the desired target temperature.",
      "unit": "degreeCelsius",
      "writable": true
    },
    {
      "@type": [
        "Property",
        "Temperature"
      ],
      "name": "maxTempSinceLastReboot",
      "schema": "double",
      "unit": "degreeCelsius",
      "displayName": "Max temperature since last reboot.",
      "description": "Returns the max temperature since last device reboot."
    },
    {
      "@type": "Command",
      "name": "getMaxMinReport",
      "displayName": "Get Max-Min report.",
      "description": "This command returns the max, min and average temperature from the specified time to the current time.",
      "request": {
        "name": "since",
        "displayName": "Since",
        "description": "Period to return the max-min report.",
        "schema": "dateTime"
      },
      "response": {
        "name": "tempReport",
        "displayName": "Temperature Report",
        "schema": {
          "@type": "Object",
          "fields": [
            {
              "name": "maxTemp",
              "displayName": "Max temperature",
              "schema": "double"
            },
            {
              "name": "minTemp",
              "displayName": "Min temperature",
              "schema": "double"
            },
            {
              "name": "avgTemp",
              "displayName": "Average Temperature",
              "schema": "double"
            },
            {
              "name": "startTime",
              "displayName": "Start Time",
              "schema": "dateTime"
            },
            {
              "name": "endTime",
              "displayName": "End Time",
              "schema": "dateTime"
            }
          ]
        }
      }
    }
  ]
}

Het thermostaatmodel heeft één interface. Latere voorbeelden in dit artikel bevatten complexere modellen die gebruikmaken van onderdelen en overname.

In dit artikel wordt beschreven hoe u uw eigen modellen ontwerpt en ontwerpt en behandelt onderwerpen zoals gegevenstypen, modelstructuur en hulpprogramma's.

Zie de digital Twins Definition Language-specificatie voor meer informatie.

Notitie

IoT Central ondersteunt momenteel DTDL v2 met een IoT Central-extensie.

Modelstructuur

Eigenschappen, telemetrie en opdrachten worden gegroepeerd in interfaces. In deze sectie wordt beschreven hoe u interfaces kunt gebruiken om eenvoudige en complexe modellen te beschrijven met behulp van onderdelen en overname.

Model-id's

Elke interface heeft een unieke digital twin model identifier (DTMI). Complexe modellen gebruiken DTMIs om onderdelen te identificeren. Toepassingen kunnen de DTMIs gebruiken die apparaten verzenden om modeldefinities in een opslagplaats te vinden.

DTMIs moet de volgende naamconventie gebruiken:

  • Het DTMI-voorvoegsel is dtmi:.
  • Het DTMI-achtervoegsel is het versienummer voor het model, zoals ;2.
  • De hoofdtekst van de DTMI wordt toegewezen aan de map en het bestand in de modelopslagplaats waar het model is opgeslagen. Het versienummer maakt deel uit van de bestandsnaam.

Het model dat wordt geïdentificeerd door de DTMI dtmi:com:Example:Thermostat;2 , wordt bijvoorbeeld opgeslagen in het bestand dtmi/com/example/thermostat-2.json .

In het volgende fragment ziet u het overzicht van een interfacedefinitie met de unieke DTMI:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;2",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    ...
  ]
}

Geen onderdelen

Een eenvoudig model, zoals de thermostaat die eerder werd weergegeven, maakt geen gebruik van ingesloten of trapsgewijze onderdelen. Telemetrie, eigenschappen en opdrachten worden gedefinieerd in het contents knooppunt van de interface.

In het volgende voorbeeld ziet u een deel van een eenvoudig model dat geen onderdelen gebruikt:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "displayName": "Temperature",
      "description": "Temperature in degrees Celsius.",
      "schema": "double",
      "unit": "degreeCelsius"
    },
    {
      "@type": [
        "Property",
...

Hulpprogramma's zoals Azure IoT Explorer en de ontwerpfunctie voor apparaatsjablonen van IoT Central labelen een zelfstandige interface, zoals de thermostaat als standaardonderdeel.

In de volgende schermopname ziet u hoe het model wordt weergegeven in het hulpprogramma Azure IoT Explorer:

Schermopname van het standaardonderdeel in het hulpprogramma Azure IoT Explorer.

In de volgende schermopname ziet u hoe het model wordt weergegeven als het standaardonderdeel in de ontwerpfunctie voor ioT Central-apparaatsjablonen. Selecteer Identiteit weergeven om de DTMI van het model te zien:

Schermopname van het thermostaatmodel in het ontwerpprogramma voor apparaatsjablonen van IoT Central.

De model-id wordt opgeslagen in een eigenschap van een apparaatdubbel, zoals in de volgende schermopname wordt weergegeven:

Schermopname van het hulpprogramma Azure IoT Explorer met de model-id in een digitale dubbel-eigenschap.

Een DTDL-model zonder onderdelen is een handige vereenvoudiging voor een apparaat of een IoT Edge-module met één set telemetrie, eigenschappen en opdrachten. Een model dat geen onderdelen gebruikt, maakt het eenvoudig om een bestaand apparaat of een bestaande module te migreren als een IoT-Plug en Play apparaat of module. U maakt een DTDL-model dat uw werkelijke apparaat of module beschrijft zonder dat u onderdelen hoeft te definiëren.

Tip

Een module kan een apparaatmodule of een IoT Edge-module zijn.

Opnieuw gebruiken

Er zijn twee manieren om interfacedefinities opnieuw te gebruiken.

  • Gebruik meerdere onderdelen in een model om te verwijzen naar andere interfacedefinities.
  • Overname gebruiken om bestaande interfacedefinities uit te breiden.

Meerdere onderdelen

Met onderdelen kunt u een modelinterface bouwen als een assembly van andere interfaces.

De thermostaatinterface wordt bijvoorbeeld gedefinieerd als een model. U kunt deze interface opnemen als een of meer onderdelen wanneer u het model temperatuurregelaar definieert. In het volgende voorbeeld worden deze onderdelen aangeroepen thermostat1 en thermostat2.

Voor een DTDL-model met meerdere onderdelen zijn er twee of meer onderdeelsecties. Elke sectie is @type ingesteld op Component en verwijst expliciet naar een schema, zoals wordt weergegeven in het volgende fragment:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "description": "Device with two thermostats and remote reboot.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "DataSize"
      ],
      "name": "workingSet",
      "displayName": "Working Set",
      "description": "Current working set of the device memory in KiB.",
      "schema": "double",
      "unit": "kibibyte"
    },
    {
      "@type": "Property",
      "name": "serialNumber",
      "displayName": "Serial Number",
      "description": "Serial number of the device.",
      "schema": "string"
    },
    {
      "@type": "Command",
      "name": "reboot",
      "displayName": "Reboot",
      "description": "Reboots the device after waiting the number of seconds specified.",
      "request": {
        "name": "delay",
        "displayName": "Delay",
        "description": "Number of seconds to wait before rebooting the device.",
        "schema": "integer"
      }
    },
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1",
      "displayName": "Thermostat One",
      "description": "Thermostat One of Two."
    },
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat2",
      "displayName": "Thermostat Two",
      "description": "Thermostat Two of Two."
    },
    {
      "@type": "Component",
      "schema": "dtmi:azure:DeviceManagement:DeviceInformation;1",
      "name": "deviceInformation",
      "displayName": "Device Information interface",
      "description": "Optional interface with basic device hardware information."
    }
  ]
}

Dit model bevat drie onderdelen die zijn gedefinieerd in de inhoudssectie: twee Thermostat onderdelen en een DeviceInformation onderdeel. De inhoudssectie bevat ook eigenschaps-, telemetrie- en opdrachtdefinities.

In de volgende schermopnamen ziet u hoe dit model wordt weergegeven in IoT Central. De eigenschaps-, telemetrie- en opdrachtdefinities in de temperatuurcontroller worden weergegeven in het onderdeel Standaard op het hoogste niveau. De eigenschaps-, telemetrie- en opdrachtdefinities voor elke thermostaat worden weergegeven in de onderdeeldefinities:

Schermopname van de apparaatsjabloon voor de temperatuurcontroller in IoT Central.

Schermopname van de thermostaatonderdelen in de apparaatsjabloon voor de temperatuurcontroller in IoT Central.

Zie de Ontwikkelaarshandleiding voor IoT-Plug en Play voor apparaten voor informatie over het schrijven van apparaatcode die interactie heeft met onderdelen.

Zie de ontwikkelaarshandleiding voor IoT Plug en Play service voor informatie over het schrijven van servicecode die communiceert met onderdelen op een apparaat.

Overname

Met overname kunt u mogelijkheden in een basisinterface opnieuw gebruiken om de mogelijkheden van een interface uit te breiden. Verschillende apparaatmodellen kunnen bijvoorbeeld algemene mogelijkheden delen, zoals een serienummer:

Diagram met een voorbeeld van overname in een apparaatmodel. Een thermostaatinterface en een stroomcontrollerinterface delen beide mogelijkheden vanuit een basisinterface.

Het volgende codefragment toont een DTML-model dat gebruikmaakt van het extends trefwoord om de overnamerelatie te definiëren die in het vorige diagram wordt weergegeven:

[
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:Thermostat;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Telemetry",
        "name": "temperature",
        "schema": "double",
        "unit": "degreeCelsius"
      },
      {
        "@type": "Property",
        "name": "targetTemperature",
        "schema": "double",
        "unit": "degreeCelsius",
        "writable": true
      }
    ],
    "extends": [
      "dtmi:com:example:baseDevice;1"
    ]
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:baseDevice;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Property",
        "name": "SerialNumber",
        "schema": "double",
        "writable": false
      }
    ]
  }
]

In de volgende schermopname ziet u dit model in de ioT Central-apparaatsjabloonomgeving:

Schermopname van de overname van de interface in IoT Central.

Wanneer u code aan de apparaat- of servicezijde schrijft, hoeft uw code niets speciaals te doen om overgenomen interfaces te verwerken. In het voorbeeld dat in deze sectie wordt weergegeven, rapporteert uw apparaatcode het serienummer alsof het deel uitmaakt van de thermostaatinterface.

Tips

U kunt onderdelen en overname combineren wanneer u een model maakt. In het volgende diagram ziet u een thermostat model dat wordt overgenomen van een baseDevice interface. De baseDevice interface heeft een onderdeel dat zelf overgaat van een andere interface:

Diagram van een model dat gebruikmaakt van zowel onderdelen als overname.

In het volgende fragment ziet u een DTML-model dat gebruikmaakt van de extends en component trefwoorden voor het definiëren van de overnamerelatie en het gebruik van onderdelen die in het vorige diagram worden weergegeven:

[
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:Thermostat;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Telemetry",
        "name": "temperature",
        "schema": "double",
        "unit": "degreeCelsius"
      },
      {
        "@type": "Property",
        "name": "targetTemperature",
        "schema": "double",
        "unit": "degreeCelsius",
        "writable": true
      }
    ],
    "extends": [
      "dtmi:com:example:baseDevice;1"
    ]
  },
  {
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:baseDevice;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Property",
        "name": "SerialNumber",
        "schema": "double",
        "writable": false
      },
      {
        "@type" : "Component",
        "schema": "dtmi:com:example:baseComponent;1",
        "name": "baseComponent"
      }
    ]
  }
]

Data types

Gebruik gegevenstypen om telemetrie, eigenschappen en opdrachtparameters te definiëren. Gegevenstypen kunnen primitief of complex zijn. Complexe gegevenstypen maken gebruik van primitieven of andere complexe typen. De maximale diepte voor complexe typen is vijf niveaus.

Primitieve typen

In de volgende tabel ziet u de set primitieve typen die u kunt gebruiken:

Primitief type Beschrijving
boolean Een booleaanse waarde
date Een volledige datum zoals gedefinieerd in sectie 5.6 van RFC 3339
dateTime Een datum/tijd zoals gedefinieerd in RFC 3339
double Een IEEE 8-byte drijvende komma
duration Een duur in ISO 8601-indeling
float Een IEEE 4-byte drijvende komma
integer Een ondertekend geheel getal van 4 bytes
long Een ondertekend geheel getal van 8 bytes
string Een UTF8-tekenreeks
time Een fulltime zoals gedefinieerd in sectie 5.6 van RFC 3339

In het volgende fragment ziet u een voorbeeld van een telemetriedefinitie die gebruikmaakt van het double type in het schema veld:

{
  "@type": "Telemetry",
  "name": "temperature",
  "displayName": "Temperature",
  "schema": "double"
}

Complexe gegevenstypen

Complexe gegevenstypen zijn een matrix, opsomming, toewijzing, object of een van de georuimtelijke typen.

Matrices

Een matrix is een indexeerbaar gegevenstype waarbij alle elementen hetzelfde type zijn. Het elementtype kan een primitief of complex type zijn.

In het volgende codefragment ziet u een voorbeeld van een telemetriedefinitie die gebruikmaakt van het Array type in het schema veld. De elementen van de matrix zijn booleaanse waarden:

{
  "@type": "Telemetry",
  "name": "ledState",
  "schema": {
    "@type": "Array",
    "elementSchema": "boolean"
  }
}

Opsommingen

Een opsomming beschrijft een type met een set benoemde labels die worden toegewezen aan waarden. De waarden kunnen gehele getallen of tekenreeksen zijn, maar de labels zijn altijd tekenreeksen.

In het volgende codefragment ziet u een voorbeeld van een telemetriedefinitie die gebruikmaakt van het Enum type in het schema veld. De waarden in de opsomming zijn gehele getallen:

{
  "@type": "Telemetry",
  "name": "state",
  "schema": {
    "@type": "Enum",
    "valueSchema": "integer",
    "enumValues": [
      {
        "name": "offline",
        "displayName": "Offline",
        "enumValue": 1
      },
      {
        "name": "online",
        "displayName": "Online",
        "enumValue": 2
      }
    ]
  }
}

Maps

Een kaart is een type met sleutel-waardeparen waarbij de waarden allemaal hetzelfde type hebben. De sleutel in een kaart moet een tekenreeks zijn. De waarden in een kaart kunnen elk type zijn, inclusief een ander complex type.

In het volgende fragment ziet u een voorbeeld van een eigenschapsdefinitie die gebruikmaakt van het Map type in het schema veld. De waarden in de kaart zijn tekenreeksen:

{
  "@type": "Property",
  "name": "modules",
  "writable": true,
  "schema": {
    "@type": "Map",
    "mapKey": {
      "name": "moduleName",
      "schema": "string"
    },
    "mapValue": {
      "name": "moduleState",
      "schema": "string"
    }
  }
}

Objecten

Een objecttype bestaat uit benoemde velden. De typen velden in een objecttoewijzing kunnen primitieve of complexe typen zijn.

In het volgende codefragment ziet u een voorbeeld van een telemetriedefinitie die gebruikmaakt van het Object type in het schema veld. De velden in het object zijn dateTime, durationen string typen:

{
  "@type": "Telemetry",
  "name": "monitor",
  "schema": {
    "@type": "Object",
    "fields": [
      {
        "name": "start",
        "schema": "dateTime"
      },
      {
        "name": "interval",
        "schema": "duration"
      },
      {
        "name": "status",
        "schema": "string"
      }
    ]
  }
}

Georuimtelijke typen

DTDL biedt een set georuimtelijke typen, gebaseerd op GeoJSON, voor het modelleren van geografische gegevensstructuren: point, multiPoint, lineString, multiLineString, en multiPolygonpolygon. Deze typen zijn vooraf gedefinieerde geneste structuren van matrices, objecten en opsommingen.

In het volgende fragment ziet u een voorbeeld van een telemetriedefinitie die gebruikmaakt van het point type in het schema veld:

{
  "@type": "Telemetry",
  "name": "location",
  "schema": "point"
}

Omdat de georuimtelijke typen op matrix zijn gebaseerd, kunnen ze momenteel niet worden gebruikt in eigenschapsdefinities.

Semantische typen

Het gegevenstype van een eigenschap of telemetriedefinitie geeft de indeling aan van de gegevens die een apparaat uitwisselt met een service. Het semantische type bevat informatie over telemetrie en eigenschappen die een toepassing kan gebruiken om te bepalen hoe een waarde moet worden verwerkt of weergegeven. Elk semantisch type heeft een of meer gekoppelde eenheden. Celsius en fahrenheit zijn bijvoorbeeld eenheden voor het semantische temperatuurtype. IoT Central-dashboards en -analyses kunnen de informatie van het semantische type gebruiken om te bepalen hoe telemetrie- of eigenschapswaarden en weergave-eenheden moeten worden uitgezet. Als u wilt weten hoe u de modelparser kunt gebruiken om de semantische typen te lezen, raadpleegt u Inzicht in de digital Twins-modelparser.

In het volgende fragment ziet u een voorbeeld van een telemetriedefinitie met semantische typegegevens. Het semantische type Temperature wordt toegevoegd aan de @type matrix en de unit waarde degreeCelsius is een van de geldige eenheden voor het semantische type:

{
  "@type": [
    "Telemetry",
    "Temperature"
  ],
  "name": "temperature",
  "schema": "double",
  "unit": "degreeCelsius"
}

Lokalisatie

Toepassingen, zoals IoT Central, gebruiken informatie in het model om dynamisch een gebruikersinterface te bouwen rond de gegevens die worden uitgewisseld met een IoT-Plug en Play-apparaat. Tegels op een dashboard kunnen bijvoorbeeld namen en beschrijvingen weergeven voor telemetrie, eigenschappen en opdrachten.

De optionele description velden displayName in het model bevatten tekenreeksen die zijn bedoeld voor gebruik in een gebruikersinterface. Deze velden kunnen gelokaliseerde tekenreeksen bevatten die een toepassing kan gebruiken om een gelokaliseerde gebruikersinterface weer te geven.

In het volgende fragment ziet u een voorbeeld van een telemetriedefinitie voor temperatuur die gelokaliseerde tekenreeksen bevat:

{
  "@type": [
    "Telemetry",
    "Temperature"
  ],
  "description": {
    "en": "Temperature in degrees Celsius.",
    "it": "Temperatura in gradi Celsius."
  },
  "displayName": {
    "en": "Temperature",
    "it": "Temperatura"
  },
  "name": "temperature",
  "schema": "double",
  "unit": "degreeCelsius"
}

Gelokaliseerde tekenreeksen toevoegen is optioneel. Het volgende voorbeeld heeft slechts één standaardtaal:

{
  "@type": [
    "Telemetry",
    "Temperature"
  ],
  "description": "Temperature in degrees Celsius.",
  "displayName": "Temperature",
  "name": "temperature",
  "schema": "double",
  "unit": "degreeCelsius"
}

Levenscyclus en hulpprogramma's

De vier levenscyclusfasen voor een apparaatmodel zijn auteur, publiceren, gebruiken en versie:

Auteur

DTML-apparaatmodellen zijn JSON-documenten die u in een teksteditor kunt maken. In IoT Central kunt u echter de GUI-omgeving van de apparaatsjabloon gebruiken om een DTML-model te maken. In IoT Central kunt u het volgende doen:

  • Maak interfaces waarmee eigenschappen, telemetrie en opdrachten worden gedefinieerd.
  • Gebruik onderdelen om meerdere interfaces samen te stellen.
  • Overnamerelaties tussen interfaces definiëren.
  • DTML-modelbestanden importeren en exporteren.

Zie Een nieuw IoT-apparaattype definiëren in uw Azure IoT Central-toepassing voor meer informatie.

Er is een DTDL-ontwerpextensie voor VS Code die ondersteuning biedt voor zowel DTDL v2 als DTDL v3.

Als u de DTDL-extensie voor VS Code wilt installeren, gaat u naar de DTDL-editor voor Visual Studio Code. U kunt ook zoeken naar DTDL in de weergave Extensies in VS Code.

Nadat u de extensie hebt geïnstalleerd, gebruikt u deze om u te helpen bij het ontwerpen van DTDL-modelbestanden in VS Code:

  • De extensie biedt syntaxisvalidatie in DTDL-modelbestanden, waarbij fouten worden gemarkeerd, zoals wordt weergegeven in de volgende schermopname:

    Schermopname van DTDL-modelvalidatie in VS Code.

  • Gebruik intellisense en automatisch aanvullen wanneer u DTDL-modellen bewerkt:

    Schermopname van intellisense voor DTDL-modellen in VS Code.

  • Maak een nieuwe DTDL-interface. De opdracht DTDL: Interface maken maakt een JSON-bestand met een nieuwe interface. De interface bevat voorbeeldtelemetrie, eigenschaps- en opdrachtdefinities.

Gebruik

Toepassingen, zoals IoT Central, maken gebruik van apparaatmodellen. In IoT Central maakt een model deel uit van de apparaatsjabloon die de mogelijkheden van het apparaat beschrijft. IoT Central gebruikt de apparaatsjabloon om dynamisch een gebruikersinterface voor het apparaat te bouwen, inclusief dashboards en analyses.

Notitie

IoT Central definieert enkele extensies voor de DTDL-taal. Zie de IoT Central-extensie voor meer informatie.

Een aangepaste oplossing kan de Digital Twins-modelparser gebruiken om inzicht te hebben in de mogelijkheden van een apparaat dat het model implementeert. Zie IoT Plug en Play-modellen gebruiken in een IoT-oplossing voor meer informatie.

Versie

Om ervoor te zorgen dat apparaten en oplossingen aan de serverzijde die gebruikmaken van modellen blijven werken, zijn gepubliceerde modellen onveranderbaar.

De DTMI bevat een versienummer dat u kunt gebruiken om meerdere versies van een model te maken. Apparaten en oplossingen aan de serverzijde kunnen gebruikmaken van de specifieke versie die ze hebben ontworpen.

IoT Central implementeert meer versiebeheerregels voor apparaatmodellen. Als u een apparaatsjabloon en het bijbehorende model in IoT Central versiet, kunt u apparaten migreren van eerdere versies naar latere versies. Gemigreerde apparaten kunnen echter geen nieuwe mogelijkheden gebruiken zonder een firmware-upgrade. Zie Een apparaatsjabloon bewerken voor meer informatie.

Publiceren

Vanaf februari 2024 wordt het Azure Certified Device-programma buiten gebruik gesteld. Daarom accepteert Microsoft geen verzendingen van DTDL-modellen meer naar de Opslagplaats voor Azure IoT Plug and Play-modellen .

Als u uw eigen modelopslagplaats wilt instellen, kunt u de opslagplaats met hulpprogramma's voor Azure IoT Plug and Play-modellen gebruiken. Deze opslagplaats bevat de code voor het dmr-client CLI-hulpprogramma waarmee DTDL-modellen kunnen worden gevalideerd, geïmporteerd en uitgebreid. Met dit hulpprogramma kunt u ook modelopslagplaatsen indexeren die voldoen aan de conventies van de apparaatmodelopslagplaats.

Limieten en beperkingen

De volgende lijst bevat een overzicht van enkele belangrijke beperkingen en limieten voor modellen:

  • Op dit moment is de maximale diepte voor matrices, kaarten en objecten vijf niveaus.
  • U kunt geen matrices gebruiken in eigenschapsdefinities.
  • U kunt interfaces uitbreiden tot een diepte van 10 niveaus.
  • Een interface kan maximaal twee andere interfaces uitbreiden.
  • Een onderdeel kan geen ander onderdeel bevatten.

Meer informatie over de digital Twins-modelparser

De Digital Twins Definition Language (DTDL) wordt beschreven in de DTDL-specificatie. Gebruikers kunnen het NuGet-pakket Digital Twins Model Parser gebruiken om een DTDL v2- of v3-model te valideren en er query's op uit te voeren. Het DTDL-model kan worden gedefinieerd in meerdere bestanden.

De DTDL-modelparser installeren

De parser is beschikbaar in NuGet.org met de id: DTDLParser. Als u de parser wilt installeren, gebruikt u alle compatibele NuGet-pakketbeheer zoals die in Visual Studio of in de dotnet CLI.

dotnet add package DTDLParser

Notitie

Op het moment van schrijven is 1.0.52de parserversie.

De parser gebruiken om een model te valideren en te inspecteren

DTDLParser is een bibliotheek waarmee u het volgende kunt doen:

  • Bepaal of een of meer modellen geldig zijn volgens de taal v2- of v3-specificaties.
  • Specifieke modelleringsfouten identificeren.
  • Controleer de inhoud van het model.

Een model kan bestaan uit een of meer interfaces die worden beschreven in JSON-bestanden. U kunt de parser gebruiken om alle bestanden te laden die een model definiëren en vervolgens alle bestanden als geheel valideren, inclusief verwijzingen tussen de bestanden.

De DTDLParser voor .NET-opslagplaats bevat de volgende voorbeelden die het gebruik van de parser illustreren:

  • DTDLParserResolveSample laat zien hoe u een interface met externe verwijzingen parseert, de afhankelijkheden kunt oplossen met behulp van de Azure.IoT.ModelsRepository client.
  • DTDLParserJSInteropSample laat zien hoe u de DTDL-parser gebruikt vanuit JavaScript die wordt uitgevoerd in de browser, met behulp van .NET JSInterop.

De DTDLParser voor .NET-opslagplaats bevat ook een verzameling zelfstudies die laten zien hoe u de parser kunt gebruiken om modellen te valideren en te inspecteren.

Met de modelparser-API kunnen veel scenario's taken automatiseren of valideren die afhankelijk zijn van DTDL-modellen. U kunt bijvoorbeeld dynamisch een gebruikersinterface bouwen op basis van de informatie in het model.

Volgende stappen

Nu u meer hebt geleerd over apparaatmodellering, vindt u hier nog enkele resources: