Další informace o modelech dvojčat a jejich definování v Azure Digital Twins

Klíčovou charakteristikou Azure Digital Twins je schopnost definovat vlastní slovník a sestavit graf dvojčat v rámci své firmy. Tato funkce je poskytována prostřednictvím uživatelem poskytnutých modelů. Modely si můžete v popisu svého světa myslet jako na podstatné jméno. Azure Digital Twins modely jsou reprezentovány v jazyce DTDL (Digital Twin Definition Language) založeném na LD JSON.

Model se podobá třídě v objektově orientovaném programovacím jazyce a definuje tvar dat pro jeden konkrétní koncept ve skutečném pracovním prostředí. Modely mají názvy (například Room nebo TemperatureSensor) a obsahují prvky, jako jsou vlastnosti, telemetrie/události, a příkazy, které popisují, co může tento typ entity ve vašem prostředí dělat. Později tyto modely použijete k vytvoření digitálních dvojčat, která představují konkrétní entity, které splňují tento popis typu.

DTDL (Digital Twin Definition Language) pro modely

Modely pro Azure Digital Twins se definují pomocí jazyka DTDL (Digital Twins Definition Language).

Úplné jazykové specifikace pro DTDL můžete zobrazit v GitHub: Digital Twins Definition Language (DTDL) – verze 2. Tato stránka obsahuje podrobné referenční informace k DTDL a příklady, které vám pomůžou začít psát vlastní modely DTDL.

DTDL vychází z jazyka JSON-LD a je nezávislý na programovacích jazycích. Jazyk DTDL se nevýlučně Azure Digital Twins, ale používá se také k reprezentaci dat zařízení v jiných službách IoT, jako je IoT Plug and Play. Azure Digital Twins používá DTDL verze 2 (použití DTDL verze 1 s Azure Digital Twins je teď zastaralé).

Zbývající část tohoto článku shrnuje, jak se jazyk používá v Azure Digital Twins.

Azure Digital Twins specifik implementace DTDL

Ne všechny služby, které používají DTDL, implementují přesně stejné funkce jako DTDL. Některé funkce DTDL aktuálně Azure Digital Twins nepodporují, mezi které patří:

• Příkazy DTDL
• Atribut writable pro vlastnosti nebo relace. I když tento atribut lze nastavit podle specifikací DTDL, hodnota není použita Azure Digital Twins. Externí klienti, kteří mají obecná oprávnění k zápisu do služby, jsou tyto atributy vždy považovány za zapisovatelné Azure Digital Twins službě.
• Vlastnosti minMultiplicity maxMultiplicity a u relací. I když je možné tyto atributy nastavit podle specifikací DTDL, hodnoty nejsou vynuceny Azure Digital Twins.

Aby byl model DTDL kompatibilní s Azure Digital Twins, musí také splňovat tyto požadavky:

• Všechny prvky DTDL nejvyšší úrovně v modelu musí být typu rozhraní. Důvodem tohoto požadavku je, Azure Digital Twins rozhraní API modelu mohou přijímat objekty JSON, které představují rozhraní nebo pole rozhraní. V důsledku toho nejsou na nejvyšší úrovni povoleny žádné jiné typy elementů DTDL.
• DTDL pro Azure Digital Twins nesmí definovat žádné příkazy.
• Azure Digital Twins umožňuje pouze jednu úroveň vnoření komponent, což znamená, že rozhraní, které se používá jako komponenta, nemůže mít žádné vlastní komponenty.
• Rozhraní nelze definovat jako vložené v rámci jiných rozhraní DTDL. Musí být definovány jako samostatné entity nejvyšší úrovně s vlastními ID. Když pak jiné rozhraní chce toto rozhraní zahrnout jako součást nebo prostřednictvím dědičnosti, může odkazovat na své ID.

Přehled modelů

Prvky modelu

V rámci definice modelu je položka kódu nejvyšší úrovně rozhraním. Tento typ zapouzdřuje celý model a zbytek modelu je definován v rámci rozhraní.

Rozhraní modelu DTDL může obsahovat nula, jedno nebo několik z následujících polí:

• Vlastnost – Vlastnosti jsou datová pole, která představují stav entity (například vlastnosti v mnoha objektově orientovaných programovacích jazycích). Vlastnosti mají zálohovací úložiště a lze je kdykoli číst. Další informace najdete níže v části Vlastnosti a telemetrie.

• Telemetrie – Pole telemetrie představují měření nebo události a často se používají k popisu odečtů ze senzorů zařízení. Na rozdíl od vlastností se telemetrie neuchovávají v digitálním dvojčete. Jedná se o řadu událostí dat vázaných na čas, které je potřeba zpracovat, jakmile k nim dojde. Další informace najdete níže v části Vlastnosti a telemetrie.

• Vztah – relace vám umožňují reprezentovat, jak se digitální dvojče může podílet na jiných digitálních dvojčatech. Relace mohou představovat různé sémantické významy, například obsahuje ("podlaží obsahuje místnost"), studená ("studená místnost hvac"), isBilledTo ("se fakturuje uživateli") atd. Relace umožňují řešení poskytovat graf vzájemně souvisejících entit. Relace mohou mít také své vlastní vlastnosti. Další informace najdete níže v tématu Relace.

• Komponenta – komponenty umožňují vytvořit rozhraní modelu jako sestavení jiných rozhraní, pokud chcete. Příkladem komponenty je rozhraní frontCamera (a další rozhraní komponenty backCamera), které se používají při definování modelu pro telefon. Nejprve definujte rozhraní pro frontCamera, jako by to byl vlastní model, a pak na něj odkazujte při Telefon.

  Pomocí komponenty můžete popsat něco, co je nedílnou součástí vašeho řešení, ale nepotřebuje samostatnou identitu a nemusí se vytvářet, odstraňovat ani měnit v grafu dvojčat nezávisle. Pokud chcete, aby entity v grafu dvojčat byly nezávislé, představují je jako samostatná digitální dvojčata různých modelů, která jsou propojena relacemi.

  Tip

  Komponenty lze také použít k uspořádání a seskupování sad souvisejících vlastností v rozhraní modelu. V takové situaci si jednotlivé komponenty můžete myslet jako na obor názvů nebo "složku" uvnitř rozhraní.

  Další informace najdete níže v části Komponenty.

Kód modelu

Modely typů dvojčat je možné napsat v libovolném textovém editoru. Jazyk DTDL se řídí syntaxí JSON, takže byste měli ukládat modely s příponou .json. Použití rozšíření JSON umožní mnoha programovacím textovým editorům základní kontrolu syntaxe a zvýraznění dokumentů DTDL. K dispozici je také rozšíření DTDL pro Visual Studio Code.

Pole modelu jsou:

Příklad modelu

Tato část obsahuje příklad základního modelu napsaného jako rozhraní DTDL.

Tento model popisuje domovskou stránku s jednou vlastností pro ID. Model Home také definuje relaci s modelem Floor, který se může použít k označení, že dvojče Home je připojené k určitým dvojčatům floor.

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

Vlastnosti a telemetrie

Tato část obsahuje podrobnější informace o vlastnostech a telemetrii v modelech DTDL.

Úplný seznam polí, která se dají zobrazit jako součást vlastnosti, najdete v části Vlastnost ve specifikacích DTDL v2. Úplný seznam polí, která se dají zobrazit jako součást telemetrie, najdete v tématu Telemetrie ve specifikacích DTDL v2.

Rozdíl mezi vlastnostmi a telemetrií

Tady je několik pokynů k koncepčnímu rozlišení mezi vlastností DTDL a telemetrií v Azure Digital Twins.

• Očekává se, že vlastnosti budou mít zálohovací úložiště, což znamená, že můžete kdykoli načíst vlastnost a načíst její hodnotu. Pokud je vlastnost zapisovatelná, můžete do vlastnosti uložit také hodnotu.
• Telemetrie se více podobná streamu událostí. Jedná se o sadu datových zpráv, které mají krátkou životnost. Pokud nasloucháte události a akcím, které se mají v okamžiku, kdy k ní dojde, nasloucháte, nebude možné událost později sledovat. Nemůžete se k tomu vrátit a přečíst si ho později.
  • V jazyce C# se telemetrie používá jako událost jazyka C#.
  • V pojmech IoT je telemetrie obvykle jedno měření odesílané zařízením.

Telemetrie se často používá se zařízeními IoT, protože mnoho zařízení buď nemůže nebo není zajímá, ukládá hodnoty měření, které generují. Místo toho je pošlou jako stream "telemetrických" událostí. V takovém případě se zařízení nemůžete kdykoli dotazovat na nejnovější hodnotu pole telemetrie. Budete muset naslouchat zprávám ze zařízení a provádět akce při jejich doručení.

V důsledku toho budete při navrhování modelu v Azure Digital Twins pravděpodobně k modelování dvojčat používat vlastnosti ve většině případů. Díky tomu budete mít zálohovací úložiště a možnost číst datová pole a dotazovat se na tato datová pole.

Telemetrie a vlastnosti často spolupracují při zpracování příchozího přenosu dat ze zařízení. Vzhledem k tomu, že veškerý příchozí Azure Digital Twins dat je prostřednictvím rozhraní API ,použijete obvykle funkci příchozího přenosu dat ke čtení telemetrických dat nebo událostí vlastností ze zařízení a k nastavení vlastnosti v Azure Digital Twins odpovědi.

Můžete také publikovat událost telemetrie z rozhraní API Azure Digital Twins api. Stejně jako u jiných telemetrických dat jde o krátkodobou událost, která vyžaduje, aby to zvládl naslouchací proces.

Schéma

Podle DTDL může být schéma pro atributy vlastnosti a telemetrie standardních primitivních typů – , , a – a dalších typů, integer jako jsou a double string boolean dateTime duration .

Kromě primitivních typů mohou mít pole vlastností a telemetrie tyto komplexní typy:

• Object
• Map
• Enum
• (jenom telemetrie)Array

Mohou to být také sémantickétypy , které umožňují anotovat hodnoty pomocí jednotek.

Základní příklady vlastností a telemetrie

Tady je základní příklad vlastnosti v modelu DTDL. Tento příklad ukazuje vlastnost ID objektu Home.

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

Tady je základní příklad pole telemetrie v modelu DTDL. Tento příklad ukazuje telemetrii teploty na senzoru.

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

Příklad komplexního typu (objektu)

Vlastnosti a telemetrie mohou být komplexních typů, včetně Object typu.

Následující příklad ukazuje jinou verzi modelu Home s vlastností pro jeho adresu. address je objekt s vlastními poli pro ulice, město, stát a psč.

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

Příklad sémantického typu

Sémantické typy umožňuje vyjádřit hodnotu pomocí jednotky. Vlastnosti a telemetrii lze reprezentovat libovolným sémantickým typem podporovaným jazykem DTDL. Další informace o sémantických typech v DTDL a podporovaných hodnotách najdete v tématu sémantické typy ve specifikacích DTDL v2.

Následující příklad ukazuje model senzoru s telemetrií sémantického typu pro Teplotu a vlastnost sémantického typu pro vlhkost.

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

Relace

Tato část obsahuje podrobnější informace o relacích v modelech DTDL.

Úplný seznam polí, která se dají zobrazit jako součást relace, najdete v tématu Relace ve specifikacích DTDL v2.

Příklad základní relace

Tady je základní příklad relace v modelu DTDL. Tento příklad ukazuje relaci na domácím modelu, která umožňuje připojit se k modelu Floor.

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

Cílené a necílené relace

Relace lze definovat s cílovým objektem nebo bez něj. Cíl určuje, ke kterým typům dvojčat může relace dosáhnout. Můžete například zahrnout cíl, který určí, že domovský model může mít pouze rel_has_floors dvojčaty, která jsou dvojčata floor.

Někdy můžete chtít definovat relaci bez konkrétního cíle, aby se vztah mohl připojit k mnoha různým typům dvojčat.

Tady je příklad relace v modelu DTDL, který nemá cíl. V tomto příkladu je vztah pro definování senzorů, které může mít místnost, a vztah se může připojit k libovolnému typu.

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

Vlastnosti relací

DTDL také umožňuje, aby relace byly vlastní vlastnosti. Při definování relace v rámci modelu DTDL může mít relace vlastní pole, ve kterém můžete definovat vlastní vlastnosti pro popis stavu properties specifického pro relaci.

Následující příklad ukazuje jinou verzi modelu Home, kde má relace vlastnost představující, kdy bylo související rel_has_floors podlaží naposledy zabíráno.

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

Komponenty

Tato část obsahuje podrobnější informace o komponentách v modelech DTDL.

Úplný seznam polí, která se dají zobrazit jako součást komponenty, najdete v části Součást ve specifikacích DTDL v2.

Příklad základní komponenty

Tady je základní příklad komponenty v modelu DTDL. Tento příklad ukazuje model Místnosti, který používá model termostatu jako součást.

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

Pokud by termostat měly obsahovat i jiné modely v tomto řešení, mohou ve svých vlastních definicích odkazovat na stejný model termostatu jako na komponentu, stejně jako to dělá Room.

Dědičnost modelu

Někdy můžete chtít model dále specializovat. Může být například užitečné mít obecný model Room (Místnost) a specializované varianty ConferenceRoom (Konferenční místnost) a Nakladate (Nakladate si). Pro vyjádření specializace DTDL podporuje dědičnost. Rozhraní mohou dědit z jednoho nebo více jiných rozhraní. Můžete to provést přidáním extends pole do modelu.

Oddíl je název rozhraní nebo pole názvů rozhraní (což umožňuje rozšíření rozhraní extends dědit z více nadřazených modelů). Jedna nadřazená třída může sloužit jako základní model pro více rozšiřujících rozhraní.

Následující příklad přestaví model Home z předchozího příkladu DTDL jako podtyp většího "základního" modelu. Nejprve se definuje nadřazený model (Core) a potom na něj podřízený model (Home) staví pomocí 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": [
    {

V tomto případě Core přispívá ID a názvem na domovskou stránku. Ostatní modely rozšiřují také základní model a rozšiřují tak tyto vlastnosti. Tady je model Místnosti, který rozšiřuje stejné nadřazené rozhraní:

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

Po použití dědičnosti rozšiřující rozhraní zpřístupňuje všechny vlastnosti z celého řetězu dědičnosti.

Rozšiřující rozhraní nemůže změnit žádnou z definic nadřazených rozhraní. Může k nim pouze přidat . Nemůže také předefinovat schopnost, která už je definovaná v žádném z nadřazených rozhraní (i když jsou schopnosti definované stejně). Pokud například nadřazené rozhraní definuje hmotnost vlastnosti , nesmí rozšiřující rozhraní obsahovat deklaraci hmotnosti , ani když se jedná o double double .

Osvědčené postupy modelování

Při navrhování modelů tak, aby odrážely entity ve vašem prostředí, může být užitečné se podívat dopředu a zvážit vliv vašeho návrhu na dotazy. Můžete chtít navrhnout vlastnosti způsobem, který zabrání rozsáhlým sadám výsledků v procházení grafu. Můžete také chtít modelovat relace, které bude potřeba zodpovědět v jednom dotazu jako relace na jedné úrovni.

Ověřování modelů

Pro ověřování dokumentů modelu je k dispozici ukázka nezávislá jazyka DTDL , aby bylo zajištěno, že je před nahráním do vaší instance správné DTDL.

ukázka validátoru DTDL je postavená na knihovně DTDL analyzátoru .net, která je k dispozici na NuGet jako knihovna na straně klienta: Microsoft. Azure. DigitalTwins. parser. Knihovnu můžete také použít přímo k návrhu vlastního řešení ověřování. Při použití knihovny analyzátoru se ujistěte, že používáte verzi, která je kompatibilní s verzí, kterou Azure Digital revláken používá. V současné době se jedná o verzi 3.12.4.

Můžete se dozvědět více o vzorcích a knihovně analyzátoru validátoru, včetně příkladů použití, při analýze a ověřování modelů.

Nástroje pro modelování

K dispozici je několik ukázek, které usnadňují práci s modely a ontologiemi. Nachází se v tomto úložišti: Tools for Digital Twins Definition Language (DTDL).

Tato část popisuje aktuální sadu ukázek podrobněji.

Nahrání modelu

Jakmile dokončíte vytváření, rozšiřování nebo výběr modelů, můžete je nahrát do vaší instance Azure Digital Twins, aby byly dostupné pro použití ve vašem řešení. Můžete to provést pomocí rozhraní API Azure Digital Twins ,jak je popsáno v článku Správa modelů DTDL.

Pokud ale máte mnoho modelů k nahrání nebo pokud mají mnoho vzájemných závislostí, které by komplikovaly řazení jednotlivých nahrávání, můžete k nahrání mnoha modelů najednou použít ukázku Azure Digital Twins Model Uploader. Podle pokynů v ukázce nakonfigurujte a použijte tento projekt k nahrání modelů do vlastní instance.

Vizualizér modelů

Po nahrání modelů do instance Azure Digital Twins můžete modely zobrazit v instanci Azure Digital Twins, včetně všech vztahů dědičnosti a modelu, pomocí vizualizéru Azure Digital Twins modelu. Tato ukázka je aktuálně ve stavu konceptu. Komunitě pro vývoj digitálních dvojčat doporučujeme rozšířit ukázku a přispívat do této ukázky.

Další kroky

• Přečtěte si o vytváření modelů založených na standardních ontologiích: Co je ontologie?

• Podrobnější informace o správě modelů pomocí operací rozhraní API: Správa modelů DTDL

• Přečtěte si, jak se modely používají k vytváření digitálních dvojčat: Digitální dvojčata a graf dvojčat.